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.
inViewport	✅	✅	Triggered when a user causes Visual to be visible (e.g. by scrolling).
outOfViewport	✅	✅	Triggered when a user causes Visual to be hidden (e.g. by scrolling).
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.
$conversion	Denotes that the user completed the primary conversion action on a page (such as clicking Buy Now, Checkout, etc.).
$softConversion	Denotes that the user completed a conversion action other than the primary action on the page (such as clicking Try Before You Buy, Find a Local Shop, Contact Dealer, etc.).

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

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.

Adding marketing campaign data to your custom events

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.

Adding order data to your custom events

A powerful way to connect your 3D product analytics data with your sales data is to include your customers’ order data in the metadata for your custom events, typically from a Checkout or Order Confirmation page.

For example, your page may keep track of the customer’s product conifguration in an object.

// Include any custom fields you want to record as key/value pairs here
const productConfig = {
    productName: 'T-Shirt',
    total: 15.99, // $15.99
    size: 'medium',
    color: 'red',
    hasPocket: true,
    // etc.
}

First, include the analytics utilities package on your page.

<script type="module" src="https://builds.dopple.io/dopple-utilities/releases/current/index.js" defer></script>

Then, when a user takes an action that triggers a custom analytics event, such as clicking a “Buy Now” button or visiting an Order Confirmation page, you can include this order data in an event sent to Dopple’s analytics using the sendOrderEvent() method.

// Replace with your client ID
const clientId = 'a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5'

const orderData = {
    // Required fields
    orderId: 'hWt7xo9', // Replace with your order ID
    subtotal: 25.99, // $25.99
    total: 27.81, // $27.81
    timestamp: Date.now(),
    // Optional: include any custom fields you want to record here
    currency: 'USD',
    productName: 'T-Shirt',
    size: 'medium',
    color: 'red',
    hasPocket: true,
    // etc.
}

// Asynchronously send the order data to Dopple's analytics
await window.Dopple.sendOrderEvent(clientId, orderData)

Note

Be sure to include the orderId, subtotal, total, and timestamp fields in your order data. These fields are required for the order data to be properly reported for you in Dopple’s analytics dashboard.

• orderId — A unique ID for the order.
• total — The order total (for example, the subtotal value plus any extra costs/discounts, such as shipping or tax). For example, if the total is $72.99 then pass 72.99.
• subtotal — The order subtotal. If this does not apply or if you wish to only track total order values, you may optionally pass either 0 or the same value used for total.
• timestamp — The timestamp of the order in milliseconds since the Unix epoch (learn more). Use either Date.now() or a custom timestamp value for the order.

As an example with a “Buy Now” button, you may wrap this call inside of the button’s click event listener.

// Get the "Buy Now" button
const buyNowButton = document.getElementById('buy-now-button')

// Send the order data to Dopple's analytics when "Buy Now" is clicked
buyNowButton.addEventListener('click', async () => {
    const clientId = 'a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5'
    await window.Dopple.sendOrderEvent(clientId, orderData)
})

With this in place, you’ll be able to view your analytics data in Dopple’s platform to see which product configurations are most popular with your customers, and which configurations are most likely to lead to a sale.

This order data event can be triggered even on pages without Dopple Visual (i.e. pages without a 3D product), such as on a checkout page or post-payment page. The order data will only be sent if the user has previously been to a page with Dopple Visual and has a valid token stored in their browser.

Viewing your analytics data

Analytics data for your products are viewable within the Dopple platform at app.dopple.io.