Analytics Events

The SDK dispatches a unified vto-analytics CustomEvent at every state transition.

Listening

Google Tag Manager

document.addEventListener('vto-analytics', (e) => {
  window.dataLayer?.push(e.detail);
});

THG Tracker

document.addEventListener('vto-analytics', (e) => {
  window.Tracker?.push(e.detail);
});

Custom Handler

document.addEventListener('vto-analytics', (e) => {
  const { event, sessionId, data } = e.detail;
  fetch('/my-analytics', {
    method: 'POST',
    body: JSON.stringify({ event, sessionId, ...data }),
  });
});

Event Schema

interface VtoAnalyticsEvent {
  event: string;          // Event name (e.g. 'vto_button_click')
  sessionId: string;      // UUID per browser session
  timestamp: string;      // ISO 8601
  productName?: string;   // Product context
  productUrl?: string;
  data?: Record<string, unknown>;  // Event-specific payload
}

Event Reference

Core Events

| Event | When | Data | |-------|------|------| | vto_modal_open | Modal opens (integrator calls product.generate()) | personPhotoReady | | vto_modal_close | Modal closes | fromState | | vto_onboarding_view | Onboarding shown | — | | vto_onboarding_dismiss | Onboarding dismissed | — |

Upload Events

| Event | When | Data | |-------|------|------| | vto_photo_upload_start | File selected | fileSize, fileType | | vto_photo_upload_complete | Upload done | processingTimeMs, hasWarnings | | vto_photo_upload_error | Upload failed | errorMessage, errorCode | | vto_photo_change | Photo replaced | — | | vto_model_selected | Predefined model chosen | modelId | | vto_qr_shown | QR code displayed | — | | vto_qr_photo_received | Photo received via QR | — |

Generation Events

| Event | When | Data | |-------|------|------| | vto_generate_start | Generation begins | personImageRef | | vto_generate_complete | Generation succeeds | generationTimeMs | | vto_generate_error | Generation fails | errorMessage | | vto_result_view | Result shown | — |

Action Events

| Event | When | Data | |-------|------|------| | vto_add_to_cart | Add to bag clicked | sku | | vto_add_to_wishlist | Wishlist toggled | sku, added | | vto_history_view | History opened | resultCount |

Legacy Events (also dispatched)

| Event | When | |-------|------| | vto-download | User downloads result | | vto-share | User shares result | | vto-feedback | User submits feedback |

Server-side batching

The SDK automatically batches events and forwards them to the server’s analytics endpoint every 5 seconds (and on page unload).