Analytics

Overview

The plugin tracks analytics for user interactions, performance monitoring, and engagement measurement across AR and 3D experiences. This is enabled by default with no additional setup required.

Tracked events

The user journey is tracked from the moment the plugin loads to each user interaction. This includes engagement metrics with updates every second, as well as error monitoring.

Initialization

Event	Description
setup	Plugin successfully initialized
apiResponse	Product data successfully fetched from the API
apiResponseFailure	Product data fetched but SKU not found or both 3D and AR disabled
apiError	Product data fetching failed

API data (apiResponse, apiResponseFailure and apiError events)

Data	Description
duration (milliseconds)	Time from API call start to response
cacheHit	Whether the response was served from cache

Launch

Event	Description
previewLaunch	3D preview started
previewLaunchSuccess	3D preview successfully started
previewLaunchFailure	3D preview failed to start
arLaunch	AR experience started
arLaunchSuccess	AR experience successfully started
arLaunchFailure	AR experience failed to start
qrLaunch	QR code displayed for mobile AR
qrLaunchSuccess	QR code successfully displayed
qrLaunchFailure	QR code generation failed

Close

Event	Description
previewClose	3D preview closed
arClose	AR experience closed
qrClose	QR code closed

Performance

Event	Description
previewPerf	3D performance metrics captured after 2 seconds of interaction
arPerf	AR performance metrics captured after 2 seconds of tracking

Engagement

Event	Description
heartbeat	Engagement metrics (sent every 1 second during active use)

Event data

Standard properties (all events)

Data	Description
sessionId, setupId	Session tracking
hostname, href	Page context
userAgent, pluginVersion	Technical info
sku, apiKey	Product data
timeSinceSetup	Timing

Launch data (success and failure events)

Data	Description
duration (milliseconds)	Time from launch start to success or failure

AR launch breakdown (arLaunchSuccess and arLaunchFailure events)

Time spent in each AR loading phase. The phases run in parallel, so they don't add up to duration. A value is missing when the phase didn't run in that launch, e.g. reopening AR only reloads the effect.

Data	Description
scriptLoad (milliseconds)	Time until the AR script is loaded
cameraWait (milliseconds)	Time from requesting the camera until access is granted, including the user answering the permission prompt. On failure, time until the failure
download (milliseconds)	Time until all AR files are downloaded
downloadBytes	Size of the downloaded AR files
sdkInit (milliseconds)	AR engine initialization time
effectParse (milliseconds)	Time to load the product's AR effect after it's downloaded

Close data (previewClose, arClose and qrClose events)

Data	Description
loaded	Whether the experience had successfully launched before closing
duration (milliseconds)	Time from launch success to close (only when loaded is true)
engagement (milliseconds)	Engagement duration during the session (only when loaded is true)
trigger	What caused the close: close, switch, or detach

Performance data (previewPerf events)

Data	Description
fps	Average FPS during first 2 seconds of interaction

Performance data (arPerf events)

Data	Description
fps	Average FPS during first 2 seconds of tracking
tickDuration (milliseconds)	Average engine update duration
faceTrackDuration (milliseconds)	Average face tracking duration
footTrackDuration (milliseconds)	Average foot tracking duration
wristTrackDuration (milliseconds)	Average wrist tracking duration

Engagement data (heartbeat events)

Data	Description
engagementAR (milliseconds)	Duration during which tracking was successfully maintained in AR
engagement3D (milliseconds)	Time spent interacting with the 3D model (rotation, panning, zooming)
engagementTotal (milliseconds)	Sum of 3D and AR engagement time

Error data (failure events)

Data	Description
errorName	Error name
errorMessage	Error message
errorStack	Error stack trace (truncated to 4000 characters)

Data collection

What's collected:

• Technical performance metrics (loading times, success/failure rates)
• User interaction patterns and engagement duration
• Page context (URL, browser type, session information)
• Product identifiers (SKU, plugin configuration)

Privacy: No personal information collected. All sessions use anonymous, randomly generated IDs.

Custom tracking integration

Integrate your own analytics platform to track plugin usage, including launch events and engagement metrics.

3D / AR launch

Track when users launch 3D or AR experiences by adding analytics calls after the launch methods.

await shopAR.launch3D();
yourAnalytics.track('3d_launched');

await shopAR.launchAR();
yourAnalytics.track('ar_launched');

3D / AR launch failure

launch3D() and launchAR() return a Promise that rejects if the experience fails to start. Wrap the calls in a try/catch to track failures:

try {
  await shopAR.launch3D();
} catch (error) {
  yourAnalytics.track('3d_launch_failed', {
    errorName: error.name,
    errorMessage: error.message,
  });
}

try {
  await shopAR.launchAR();
} catch (error) {
  yourAnalytics.track('ar_launch_failed', {
    errorName: error.name,
    errorMessage: error.message,
  });
}

Engagement

Track engagement duration by providing callback functions that fire after configurable debounce intervals.

3D engagement tracks the time users spend rotating, panning or zooming the product in 3D.

AR engagement tracks the time users spend virtually trying on the product in AR.

await ShopAR.plugin.setup({
  // ...

  // 3D engagement tracking
  debounce3DEngagementMs: 2_000,
  onDebounced3DEngagement: (durationMs) => {
    yourAnalytics.track('3d_engagement', { duration });
  },

  // AR engagement tracking
  debounceAREngagementMs: 2_000,
  onDebouncedAREngagement: (durationMs) => {
    yourAnalytics.track('ar_engagement', { duration });
  },
});