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
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 EventDescription
$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:

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

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:

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

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
let orderData = {
    productName: 'T-Shirt',
    totalPrice: 1599, // $15.99
    size: 'medium',
    color: 'red',
    hasPocket: true,
    // etc.
}

Then, when a user takes an action that triggers a custom analytics event, such as clicking a “Buy Now” button, you can include this order data in an event sent to Dopple’s analytics:

// Call `await sendOrderEvent()` when the user clicks the "Buy Now" button
async function sendOrderEvent() {

    // IMPORTANT: replace this with your Dopple client ID
    const clientId = 'a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5'

    // Get the user's token
    const tokenData = localStorage.getItem(`client:${clientId}`)
    if (!tokenData) {
        return
    }
    const { token } = await (
        await fetch('https://api.dopple.io/auth/v3/refresh', {
            method: 'POST',
            body: JSON.stringify({token: JSON.parse(tokenData).token}),
            headers: {'content-type': 'application/json'},
        })
    ).json()

    // Record the order data in Dopple's analytics
    await fetch('https://api.dopple.io/analytics/v1/events', {
        method: 'POST',
        body: JSON.stringify({
            component: 'order-component',
            eventType: 'setOrderDetails',
            metaData: {custom: {$source: 'order-component'}},
            properties: orderData, // Your `orderData` object from above
            sequenceId: 1,
            timestamp: Date.now(),
        }),
        headers: {
            'content-type': 'application/json',
            Authorization: `Bearer ${token}`,
        }
    })
}

Now, you can simply call sendOrderEvent() anytime you’re ready to send the order data to Dopple’s analytics. This will typically be triggered either by some user action on the page, such as clicking a “Confirm Purchase” button, or by the Checkout/Order Confirmation page itself when it loads.

// Example: send the order data to Dopple's analytics when "Confirm Purchase" is clicked
const confirmPurchaseButton = document.getElementById('confirm-purchase-button')

confirmPurchaseButton.addEventListener('click', () => {
    sendOrderEvent()
})

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.

Tip

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 will soon be viewable within the Dopple platform; in the meantime, we’ll work with you directly to provide the data you need!