Getting started with Depict Performance Client
DPC handles performance tracking to enable the Depict AI to optimize recommendations and product listings.
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 app.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
UI package
If you’re using one of our UI packages, DPC is already included.
Initializing
DPC is automatically initialized when loaded through the Depict Tag, or the usePerformanceClient hook in @depict-ai/react-ui.
If you are using yarn or npm you must initialize it yourself:
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.
The initial market. Should be specified if the market is known at the point of intializing DPC.
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 are rendering product cards through one of Depict’s UI packages, this is already handled for you.
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. This way you can send events from anywhere in your code, even without a reference to the DPC instance. If you do have a DPC instance, it can also be used to send events directly.
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.
📘 External tag managers
To ensure that window.dpq is available when calling it from a different context such as Google Tag Manager, it can be initialized using:
((e,n)=>{e.dpq||((n=e.dpq=function(){n.send_event?n.send_event.apply(n,arguments):n.queue.push(arguments)}).queue=[])})(window);
Events added to the queue will be sent once DPC itself is initialized.
Available DPQ events
| Event name | Description | Event Data |
|---|---|---|
| setProductId | Sets the product id after navigating to a PDP. | string - a product id |
| addToCart | Sends an add to cart event to Depict. | string - the product id that was added |
| 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 |
| setSessionId | Sets the session_id for a user to get personalized recommendations. | string - an id you use to identify a logged in user or a session |
Tracking Product Details Page (PDP) views
After navigating to a page representing a product on your website, send a setProductId event to register which product id is currently viewed.
📘 Using the correct Product ID
For attribution of purchases to work properly, the product ID used in
setProductId and addToCart events must be the same type of id that is
returned in the displays by our API as product_id. For an example of valid
product IDs, see the bottom table on the “Tracking status” tab on
app.depict.ai.
Tracking add-to-cart
For Event Attribution of add-to-cart-events, there are two main methods. Either imperitavely sending addToCart events, or automatically by marking add-to-cart buttons in the DOM with the depict-add-to-cart class.
Sending add-to-cart events imperatively
Whenever a product was successfully added to the cart anywhere on your website (including surfaces not directly related to Depict), send an addToCart event with the corresponding product id. If you implement imperative tracking, skip the automatic tracking section below.
Mark up your add-to-cart buttons for automatic tracking
Add the depict-add-to-cart class to all add-to-cart buttons on your website, including product cards and product detail pages. Depict will automatically track clicks as necessary, and attribute them to the corresponding products for add-to-cart buttons inside product cards.
<button class="depict-add-to-cart">Add to cart</button>
Purchase events
A purchase is an event that tracks when a user has gone through the checkout process and paid for a set of products. The transaction_id should be whatever you use to identify the purchase in your system. The item_id in the items array should be the SKU of the product. The price should be the final price of the product, after any taxes, discounts, etc have been applied.
Setting the current market (Optional)
If your website can change markets without doing a full page reload, you’ll need to inform DPC when the market changes.
Informing Depict of logged in users (Optional)
To get better personalisation for logged in users, you can set sessionId to the id you use to represent them in your system. Send this event when a user logs in or if they are already logged in and the page refreshes.
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.
Please beware that the id needs to stay the same during the journey of a user, starting from them seeing a product card to purchasing it.
Debugging
To view debug logging from DPC, set localStorage.debug = true in your browser console and reload the page.
Was this page helpful?