Analytics Events

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

Listening

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

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

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).