Depict Performance Client (DPC) handles the performance tracking of our products. DPC is designed to be as easy as possible to set up and allows our Product Discovery Platform to get better over time. Once DPC is live on your site you can also view our performance on beta.portal.depict.ai.

Installing

Depict Tag (CDN)
If you load Depict with a script tag, DPC will automatically be included.

NPM Package
DPC is available as a public npm package. You can install it via yarn or npm

npm i @depict-ai/dpc

yarn add @depict-ai/dpc

Initializing

DPC is automatically initialized when loaded through the Depict Tag.

If you are using yarn or npm you must initialize it yourself:

import {DPC} from "@depict-ai/dpc

const dpc = new DPC("MERCHANT_ID", {market: "se"})

import {DPC} from "@depict-ai/dpc

// Initialize with explicit defaults.
// Unless you change the values there's no difference to "Basic Usage"
const dpc = new DPC("MERCHANT_ID", {autoObserve: true, market: undefined})

useEffect(() => {
  import("@depict-ai/dpc").then(({ DPC }) => {
    const dpc = new DPC("MERCHANT_ID", {market: "se"})
  })
}, [])

When constructing the DPC it takes two arguments. The first is your Merchant ID. The second argument is an optional object with extra configuration. If the market is known at this point, it should be specified. If you initialize DPC before you know which market is active, use dpq.

Config values

All config values are optional.

Tracking Product Cards

Once initialized, DPC watches elements with a data-recommendation_id attribute in the DOM. The recommendation_id is unique for each recommendation and is all that is needed to track Impression and Click events.

If you have an add-to-cart button in your product card, add the depict-add-to-cart class to your button and DPC will automatically track it as well.

Example Product Card HTML

This is a simple example where the two things relevant to DPC is the data-recommendation_id attribute and the depict-add-to-cart class on the add to cart button.

<div class="product-card" data-recommendation_id="10b77279-0295-4f3d-9d4c-67d95ee2f05d">
  <img src="...">
  <h2>Product Title</h2>
  <span>$100</span>
  <button class="depict-add-to-cart">Add to cart</button>
</div>

Depict Queue - The main API for DPC

The Depict Queue (DPQ) is the main way to interact the Depict Performance Client (DPC) and is globally available under window.dpq after initializing DPC.

dpq("[eventName]", eventData)

window.dpq is a function that takes two arguments. The first argument is always a string specifying the name of the event to send to DPC. The second argument contains the data, this can be a string or an object depending on the event.

📘

A note on window.dpq availability

window.dpq is set when first initializing DPC with new DPC(...). It will then be globally available on the window object. It can be accessed by simply calling dpq(...) (without specifying window) from anywhere in your code that executes on the browser after the new DPC(...) call.

Available DPQ events

Mark up your Product Details Page (PDP)

After navigating to a page representing a product on your website, use dpq to register which product id is currently viewed. This is required for Event Attribution of add-to-cart events.

dpq("setProductId", "[PRODUCT_ID_FOR_CURRENT_PDP]");

📘

Using the correct Product ID

For add to cart tracking to work the Product ID used in the setProductId event must be the same type of id that is used when querying our API for recommendations based on a product. The ID to use will be made clear when we have started to compute recommendations for your products.

Tracking add-to-cart events from your PDP

Add the depict-add-to-cart class to your add-to-cart button so that Depict is able to track this event.

For example:

<button class="depict-add-to-cart">Add to cart</button>

If the class is added to a button, DPC will ensure clicks on the button are tracked.

Purchase events

A purchase is an event that tracks when a user has gone through the checkout process and paid for a product. To track a purchase event on the frontend use window.dpq

dpq("purchase", {
  transaction_id: "YOUR_TRANSACTION_ID",
  items: [{ item_id: "white-socks-xl", price: 89.9, quantity: 12 }],
  currency: "SEK",
});

Where price is the final unit price, after any taxes, discounts, etc have been applied.

Purchase events can also be sent from your backend via our Rest API. See Create Events V2 route.

Configuring the active market

Use window.dpq to inform DPC which market is currently active on your website.
This should be done as early as possible, both when your page is loaded and when the market is updated.

dpq("setMarket", "se");

Informing Depict of logged in users

To get better personalisation for logged in users you must inform Depict of their ID. Send this event when a user logs in or if they are already logged in and the page refreshes.

dpq("setUserId", "[UNIQUE_USER_ID]");

Browser sessions

If tracking events are sent to the Depict API from other sources than the performance client, such as server-to-server tracking, a common identifier needs to be set to match attribution between the different tracking sources. Set a shared browser session ID on DPC to be the same as the one used in the events you send directly to the API.

dpq("setSessionId", "[UNIQUE_SESSION_ID]");

Debugging

To view debug logging from DPC, set localStorage.debug = true in your browser console and reload the page.