Getting started with Depict Performance Client
DPC handles performance tracking to enable the Depict AI to optimize recommendations.
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.
Option | Type | Default | Description |
---|---|---|---|
market | string | undefined | The initial market. Should be specified if the market is known at the point of intializing DPC. |
autoObserve | boolean | true | If we should observe for recommendations on creation. If false, you must call trackRecommendationCard manually. |
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 withnew DPC(...)
. It will then be globally available on thewindow
object. It can be accessed by simply callingdpq(...)
(without specifyingwindow
) from anywhere in your code that executes on the browser after thenew DPC(...)
call.
Available DPQ events
Event name | Description | Event Data |
---|---|---|
setProductId | Sets the product id after navigating to a PDP. | string - a product id |
purchase | Sends a purchase event to depict. | object - a purchase object |
setMarket | Sets the currently active market used in all tracking events. | string - a market |
setUserId | Sets the user_id for a logged in user to get personalized recommendations. | string - an id you use to identify a logged in user |
setSessionId | Sets the session_id for the current browser to match with tracking events from other sources than DPC. | string - an id you use to identify the current browser session |
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.
Updated about 1 month ago