Skip to main content

Analytics

When Dopple Visual is added to a webpage, certain analytics around interaction and usage (such as when a user rotates or zooms the camera to see the 3D product) are captured.

Some of these analytics events are already built-in and are captured for you automatically, but custom analytics events may also be created for capturing other actions on your webpage that relate to your 3D product, such as when a user adds a configured product to their shopping cart.

A good way to distinguish the two types of analytics events is by where they are triggered from:

  • Built-in events triggered by actions taken within Dopple Visual (either on the <canvas> element if using the Visual API, or within the Visual Component), such as a user rotating or zooming in on the product.
  • Custom events triggered by actions taken somewhere else on the page outside of Dopple Visual, such as a user clicking a call-to-action button in a menu next to the 3D product.

Built-in Events

Dopple Visual comes with a variety of built-in analytics events to help you see the most complete picture possible of how your users are interacting with your 3D products.

These events are captured automatically, without the need for you to manually capture any user actions or make any API calls.

EventDirect APIVisual ComponentNotes
cameraPan

Triggered when a user causes the camera to pan.

cameraRotate

Triggered when a user causes the camera to rotate.

cameraZoom

Triggered when a user causes the camera to zoom in or out.

multiSetValue

Triggered automatically when updating multiple properties of a 3D product’s configuration at once.

Examples include clicking a <button>, selecting an <option>, or checking a radio <input> that is bound to via the DOM binding data-av-multiproperty attribute.

productGetterAccessed

Triggered by getting the ProductComponent.product property.

productReady

Triggered by manually (or automatically by the Visual Component) calling new Atlatl.Product(…) and the Product being ready.

sessionReady

Triggered automatically when all products are loaded and the loading screen is hidden.

sessionStart

Triggered automatically when Dopple Visual is initialized.

setValue

Triggered by manually (or automatically by the Visual Component) calling Atlatl.Product.setValue(…) to update a single property of a 3D product’s configuration.

Examples include clicking a <button>, selecting an <option>, or checking a radio or checkbox <input> that is bound to via the DOM binding data-av-property attribute.

triggerEvent

Triggered by manually (or automatically by the Visual Component) calling Atlatl.Product.triggerEvent(…).

When using the Visual Component, requires that the DOM binding is in use as well. For example: <button data-av-event="myEvent">Click me</button>

variantChanged

Triggered by a user interacting with a control that is bound to by the Shopify binding.

Requires that the Shopify binding is in use.

visualGetterAccessed

Triggered by manually getting the VisualComponent.visual property.

Custom Events

Dopple Visual also supports triggering and sending custom events using analytics.sendCustomEvent(…). Custom events may be triggered by any actions on your webpage, such as a user clicking on a call-to-action button.

Standard events supported by Dopple are prefixed with $ and are intended for tracking conversions and sales funnel actions.

Standard custom events

Custom EventDescription
$addToCart

Denotes that content was added to a cart.

$softConversion

Denotes that the user started the conversion process (such as Try Before You Buy, Find a Local Shop, Contact Dealer, etc.).

$viewIn3D

Denotes that the Visual canvas was displayed to the user (useful for UIs where the 3D product is not initially visible to users, and visibility is triggered by a user action such as clicking a button).

$viewInAR

Denotes that Visual was displayed in AR (useful for UIs where the user can view the 3D product in AR using a button outside of Dopple Visual).

Using standard custom events

Custom events must be triggered manually by your page, typically when a user takes a specific action (such as clicking on a button in the UI).

To trigger a custom analytics event, call the analytics.sendCustomEvent(…) method on the Visual instance itself:

// Get the "Add to Cart" button
const myButton = document.getElementById('add-to-cart-button')

// Send the custom analytics event to Dopple when "Add to Cart" is clicked
myButton.addEventListener('click', () => {
const visual = document.querySelector('atlatl-visual')
visual.analytics.sendCustomEvent('$addToCart')
})

Using non-standard custom events

Non-standard custom events may also be sent to Dopple’s analytics. These events may be given any custom name, and may include a payload in the form of a JSON-like object with any additional details about the event.

// Get the button that will trigger the custom event
const myCustomButton = document.getElementById('custom-event-button')

// Send the custom analytics event to Dopple when the button is clicked
myCustomButton.addEventListener('click', () => {
const visual = document.querySelector('atlatl-visual')
visual.analytics.sendCustomEvent('userPerformedAnAction', {
// Optional: any additional data to include with your custom event may go here
name: 'User performed an action',
description: 'A user clicked a button that triggered this custom event.'
})
})

While standard custom events are useful for tracking conversions and funnel actions, non-standard custom events may be useful for tracking any other user actions on your page in relation to your 3D product.

caution

When using non-standard custom events, the event name must not begin with a $ character. Event names prefixed with $ are reserved for standard custom events only.

Custom Metadata

When analytics events are sent to Dopple’s platform, the payload also includes some metadata about the session, such as the client ID and session ID. However, it may be useful to include additional metadata along with these events that further tie each analytics event to specific data you want to capture.

For example, if a user is logged in on your site and has a unique user ID associated with them, that user ID may be added to the metadata, allowing you to see which actions and interactions that specific user took with the 3D product on your page.

// Set the user ID in the metadata for Dopple's analytics on page load
window.addEventListener('load', async () => {
const visual = document.querySelector('atlatl-visual')
await visual.analytics.ready()
visual.analytics.setMetaData({
userId: 'a-b-c' // Replace with your user's unique ID here
})
})
Tip

Set this custom metadata as early as possible once Dopple Visual loads on your page, in order to avoid having a window of time where a user may take an action that triggers analytics events before this metadata is set.

Another more complex use case of custom metadata is for campaign tracking. For example, say a user comes to your page from a link in a social media campaign and the link to your page includes the following UTM parameters:

http://www.example.com/product.html?utm_source=linkedin&utm_medium=social&utm_campaign=bigpromotion

The utm_source, utm_medium, and utm_campaign parameters can be extracted from the URL and passed as metadata to Dopple’s analytics:

// Returns the value of a specified parameter (param) in the page's URL
const getURLParameter = (param) => {
const pageURL = window.location.search.substring(1)
const URLVariables = pageURL.split('&')
for (var i = 0; i < URLVariables.length; i++) {
const parameterName = URLVariables[i].split('=')
if (parameterName[0] == param) {
return parameterName[1]
}
}
}

// Set the marketing campaign data in the metadata for Dopple's analytics
window.addEventListener('load', async () => {
const visual = document.querySelector('atlatl-visual')
await visual.analytics.ready()
visual.analytics.setMetaData({
campaign: getURLParameter('utm_campaign'), // bigpromotion
medium: getURLParameter('utm_medium'), // social
source: getURLParameter('utm_source') // linkedin
})
})

Now, any analytics events sent to Dopple will also include metadata with the marketing campaign info. This data may be useful for seeing which campaigns are having the greatest success with user interaction on your 3D products.

Viewing your analytics data

Analytics data for your products will soon be viewable within the Dopple platform; in the meantime, we’ll work with you directly to provide the data you need!