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.

Event	Direct API	Visual Component	Notes
arSceneCreated			Triggered when a user accesses AR.
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.
productReady			Triggered by manually (or automatically by the Visual Component) calling new Atlatl.Product(…) and the Product being ready.
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.

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 Event	Description
$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:

Visual Component

// 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')
})

Direct API

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

// Initialize Dopple Visual and load the product
let visual
const renderCanvas = document.getElementById('my-canvas')

window.addEventListener('load', async () => {
    visual = new Atlatl.Visual(renderCanvas)
    await visual.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5')
    const template = new Atlatl.ProductTemplate(visual, 'my_namespace', 'my_product_name')
    await template.load()
    myProduct = new Atlatl.Product(template)
    await myProduct.ready()
    visual.loadingScreen.hide()
})

// Send the custom analytics event to Dopple when "Add to Cart" is clicked
myButton.addEventListener('click', () => {
    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.

Visual Component

// 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.'
    })
})

Direct API

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

// Initialize Dopple Visual and load the product
let visual
const renderCanvas = document.getElementById('my-canvas')

window.addEventListener('load', async () => {
    visual = new Atlatl.Visual(renderCanvas)
    await visual.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5')
    const template = new Atlatl.ProductTemplate(visual, 'my_namespace', 'my_product_name')
    await template.load()
    myProduct = new Atlatl.Product(template)
    await myProduct.ready()
    visual.loadingScreen.hide()
})

// Send the custom analytics event to Dopple when "Add to Cart" is clicked
myCustomButton.addEventListener('click', () => {
    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.

Visual Component

// 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
    })
})

Direct API

// Initialize and load Dopple Visual
let visual
const renderCanvas = document.getElementById('my-canvas')
const loadVisual = async () => {
    const renderCanvas = document.getElementById('my-canvas')
    visual = new Atlatl.Visual(renderCanvas)
    await visual.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5')
}

// Load the 3D product and hide the Dopple loading screen once loading is complete
const loadProduct = async () => {
    const template = new Atlatl.ProductTemplate(visual, 'my_namespace', 'my_product_name')
    await template.load()
    myProduct = new Atlatl.Product(template)
    await myProduct.ready()
    visual.loadingScreen.hide()
}

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

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:

Visual Component

// 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
    })
})

Direct API

// 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]
        }
    }
}

// Initialize and load Dopple Visual
let visual
const renderCanvas = document.getElementById('my-canvas')
const loadVisual = async () => {
    const renderCanvas = document.getElementById('my-canvas')
    visual = new Atlatl.Visual(renderCanvas)
    await visual.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5')
}

// Load the 3D product and hide the Dopple loading screen once loading is complete
const loadProduct = async () => {
    const template = new Atlatl.ProductTemplate(visual, 'my_namespace', 'my_product_name')
    await template.load()
    myProduct = new Atlatl.Product(template)
    await myProduct.ready()
    visual.loadingScreen.hide()
}

// Set the marketing campaign data in the metadata for Dopple's analytics on page load
window.addEventListener('load', async () => {
    await loadVisual()
    visual.analytics.setMetaData({
        campaign: getURLParameter('utm_campaign'), // bigpromotion
        medium: getURLParameter('utm_medium'), // social
        source: getURLParameter('utm_source') // linkedin
    })
    await loadProduct()
})

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!