Javascript SDK

The Da Vinci Signal Javascript SDK lets you interact with the Signal API in an easy-to-use manner on your website. The JavaScript SDK will let you:

Track users in relation to your email marketing campaigns
Add another layer of context to greatly enhance recommendations
Provide in-depth conversion tracking - automated revenue tracking for website conversions
Expose the self-service reporting UI

Quickstart

This tutorial will get you set up to start sending data from your website to the Da Vinci Signal API using our track.js library.

Install

Installing Signal is easy, just paste this snippet into the <head> tag of your website.

<script type="text/javascript">

(function(e,t){var signal=window[t]=window[t]||[];if(!signal.init)if(signal.loaded)window.console&&console.error&&console.error('Signal snippet included twice.');else{signal.loaded=!0,signal.methods=['init','debug','browser','session','identity','forget','event'],signal.factory=function(t){return function(){var e=Array.prototype.slice.call(arguments);return e.unshift(t),signal.push(e),signal}};for(var n=0;n<signal.methods.length;n++){var r=signal.methods[n];signal[r]=signal.factory(r)}t=document.createElement('script');t.type="text/javascript",t.async=!0,t.src=e;e=document.getElementsByTagName("script")[0];e.parentNode.insertBefore(t,e)}})('<https://track.coherentpath.com/v1/track.js>', 'signal');

signal.init('ACCESS_TOKEN');

</script>

Next, you must replace ACCESS_TOKEN with a token you generate within our platform interface.

To do this:

Open Settings, and select Tracking.
Click +NEW TOKEN.
Provide the token with a name, select Live and click Create token.

This will be a public type token - so it can safely be seen in plain sight on your website.

Identify users

Once the script has been made available on your website, you’ll need to set up a call to track known users. A known user can come from a variety of sources:

Clicks from an email
Logins
New user registrations
New subscribers

Identification requires an emailAddress which is provided by the marketer and represents the contact’s plain text email address. This identifier is typically utilized when identifying individuals outside the context of landing on the page from an email, which is automatically handled via cp_cid.

We generate a cp_cid when a contact is first encountered by DV. That cp_cid is permanently associated with that contact. A contact's cp_cid is held constant.

cp_cid shows up when you click through on a campaign proof. The cp_cid shown will be for the contact that got sampled for your campaign proof.

If you click on a creative proof, the cp_cid parameter will still show up on the click through; however, it will be empty because creative proofs are not associated with a specific contact.

Using a standard web templating language, here is what a basic identity call might look like:

// Requesting an identity outside the context of landing on a page from an email
signal.identity({
emailAddress: "{{ user.emailAddress }}",
source: "login",
});

// Requesting identity using data automatically supplied from query parameters. 
This is done automatically as part of script initialization
signal.identity()

The identity call is an idempotent operation - meaning you can call it on every single website page where a user is logged in. If an identity is already present - it will simply become a no-op, where no action is taken. Passing in an empty referenceID or emailAddress will also render the call a no-op. With this call in your page footer, you will successfully identify every known user that visits your website.

The identity is automatically managed as part of script initialization using an available query parameters after arriving at the landing page from an email.

Track events

Tracking website events lets Da Vinci understand the behaviors of your users. This information will be used when generating recommendations for your email campaigns as well as understanding conversions. Events can be seen as the "journey" that a customer might go through as they navigate your website.

There are a variety events that are useful to instrument:

Browsing

Page View

Products

Product Page View
Product Search

Orders

Order Completions
Order Cancelation
Order Refund

Please follow the above links to see details on how to instrument these events.

Events

Events are user-initiated actions that can be sent to Da Vinci. They are typically triggered by a user landing on specific pages or interacting with certain elements of your website.

Page view

Page views let Da Vinci understand the navigation and interests of users. The Page View event will create a new page view for the user. This can be called on all pages of your website. However, this event should be excluded when Product Page and Search Page Events are fired. A few attributes are automatically added to each pageView call. You can override these values by explicitly setting them in params passed. The code snippet below can be instrumented on every page throughout your website:

// Basic page view

signal.event("pageView");

// Page view with options

signal.event("pageView", {

title: "Blog",

});

Page view parameters

Name	Type	Description
url	String	The full url of the page visited. Defaults to the current page URL.
title	String	The title of the page visited. Defaults to the current page title.
referrer	String	The referrer of the page visited. Defaults to the current page referrer.
source	String	How the user arrived at the page.
tags	Array<String>	Additional attributes that can be assigned to the page view. This is optional. Some customers tag their products to try to group them. You could group products in relation to purchases to find them faster.
attributes	Object	Additional key-value attributes that can be assigned to the page view. This is optional. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.

Product page view

This event will create a new product page view or the user. Note, that when the Product Search event is called, the Page View event should not be fired. This should be called on individual product pages on your website. Product page views let Da Vinci understand the specific product interests of users.

Tracking product page views requires knowledge of the product details when being called. Every product requires a referenceId. This should be a unique value that represents the product in your system (like a product ID). You can also optionally include the variants of the product. A few attributes are automatically added to each productPageView call. You can override these values by explicitly setting them in params passed.

Using a standard web templating language, here is what a product view might look like:

// Basic product view
signal.event("productPageView", {
  product: {
    referenceId: "{{ product.id }}",
    name: "{{ product.name }}",
  },
});

// Product view with variants
signal.event("productPageView", {
  product: {
    referenceId: "{{ product.id }}",
    name: "{{ product.name }}",
    variants: [
      {
        referenceId: "{{ product.id }}",
        name: "{{ variant.$.name }}",
        price: "{{ variant.$.price }}",
      },
      {
        referenceId: "{{ product.id }}",
        name: "{{ variant.$.name }}",
        price: "{{ variant.$.price }}",
      },
    ],
  },
});

Product page view parameters

Name	Type	Description
product	Product	Information about the product.
url	String	The full url of the product page visited. Defaults to the current page URL.
title	String	The title of the product page visited. Defaults to the current page title.
referrer	String	The referrer of the product page visited. Defaults to the current page referrer.
source	String	How the user arrived at the product page.
tags	Array<String>	Additional detail that can be assigned to the product view for organizational purposes. This is optional. Some customers tag their products to try to group them. You could group products in relation to purchases to find them faster.
attributes	Object	Additional key-value attributes that can be assigned to the product view. This is optional. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.

Product parameters

Name	Type	Description
referenceId	String	A unique identifier of the product that is relevant to the business. *Some accounts have a notion of a parent SKU (a particular jacket) and children SKUs (jacket in particular colors.) In those cases, the referenceID would map the parent SKU.
name	String	The name of the product.
variants	Array	A list of variants associated with the product. *Some accounts have a notion of a parent SKU (a particular jacket) and children SKUs (jacket in particular colors.) In those cases, the Variant reference ID would map to the corresponding children SKUs.
tags	Array<String>	Additional list of attributes that can be assigned to the product. This is optional. Some customers tag their products to try to group them. You could group products to find them faster in relation to purchases.
attributes	Object	Additional key-value attributes that can be assigned to the product. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.

Product variant parameters

Name	Type	Description
referenceId	String	A unique identifier of the product variant that is relevant to the business.
name	String	The name of the product variant.
price	String	The price of the product variant. We allow the input of either dollars or cents, although its preferred to provide cents to avoid any ambiguity and potential conversion errors. Please note that if dollars are provided, it should be with the complete cents value (i.e. 10.00).
tags	Array<String>	Additional list of attributes that can be assigned to the product. This is optional. Some customers tag their products to try to group them. You could group products in relation to purchases to find them faster.
attributes	Object	Additional key-value attributes that can be assigned to the product. This is optional. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.

Typically, e-commerce platforms assign prices to product variants rather than the product itself, even if only one variant is available. However, we understand that situations may arise where customers are unable to provide variant data. In such cases, customers have two options which may result in duplicate data that will require cleanup. The preferred option is for customers to provide us with a single variant that accurately represents the product.

Alternatively, customers can provide the parent Product ID as well as the first variant, allowing us to retrieve the price. Although neither option is ideal, we recommend that customers who are unable to provide variant data contact their Movable Ink services team directly. Our team will work collaboratively to find the best solution for your needs.

Product search

The product search will create a new product search for the user. Note, that when the product search event is called, the page view event should not be fired. This should be called when a user performs a search on your website. Product searches let Da Vinci understand the general or specific product interests of users.

Tracking product searches requires knowledge of the search query when being called. You can also optionally include a subset of the products that have been returned from the search.

For further details, please read the [event method docs. Using a standard web templating language, here is what a product search might look like:

// Basic product search
signal.event("productSearch", {
  query: "{{ query }}",
});

// Product search with products
signal.event("productSearch", {
  query: "{{ query }}",
  products: [
    {
      referenceId: "{{ product.$.id }}",
      name: "{{ product.$.name }}",
    },
    {
      referenceId: "{{ product.$.id }}",
      name: "{{ product.$.name }}",
    },
  ],
});

Product search parameters

Name	Type	Description
query	String	The query term used for the product search.
products	Array	A list of products returned from the search. This can be a small subset of the total products.
tags	Array<String>	Additional list of attributes that can be assigned to the product search. This is optional. Some customers tag their products to try to group them. You could group products in relation to purchases to find them faster.
attributes	Object	Additional key-value attributes that can be assigned to the product search. This is optional. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.

Order completion

This event will create a new order completion for the user. This should be called on your website whenever an order/transaction is successfully completed. Order completions let Da Vinci understand the general product interests of users as well as track conversions related to your email marketing campaigns.

Tracking order completions requires knowledge of the order details including line items when being called. When possible, it's important that an identity call has been made prior to creating an order completion as this will ensure the order can be linked to a user.

For further details, please read the [event method docs. Using a standard web templating language, here is what an order completion might look like:

signal.event("orderCompletion", {
  order: {
    referenceId: "{{ order.id }}",
    subtotal: "{{ order.subtotal }}",
    items: [
      {
        referenceId: "{{ item.$.id }}",
        name: "{{ item.$.name }}",
        quantity: "{{ item.$.quantity }}",
        price: "{{ item.$.price }}",
      },
      {
        referenceId: "{{ item.$.id }}",
        name: "{{ item.$.name }}",
        quantity: "{{ item.$.quantity }}",
        price: "{{ item.$.price }}",
      },
    ],
  },
});

Order completion parameters

Name	Type	Description
order	Order	Detailed information about the order.
tags	Array<String>	Additional list of attributes that can be assigned to the order completion. This is optional. Some customers tag their products to try to group them. You could group products to find them faster in relation to purchases.
attributes	Object	Additional key-value attributes that can be assigned to the order completion. This is optional. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.

Order parameters

Name	Type	Description
referenceId	String	A unique identifier of the order that is relevant to the business, like an Order ID.
source	Enum	Where the order originated. Defaults to web.
tags	Array<String>	Additional lists of attributes that can be assigned to the order that can be assigned to the product view for organizational purposes. This is optional. Some customers tag their products to try to group them. You could group products to find them faster in relation to purchases.
attributes	Object	Additional key-value attributes that can be assigned to the order. This is optional. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.
processedAt	Integer	The timestamp when the order was processed by an ecommerce system. Defaults to the current time.
discount	String	The sum of all discounts.
subtotal	String	The sum of all line item product prices after discounts but before shipping, and taxes. We allow the input of either dollars or cents, although its preferred to provide cents to avoid any ambiguity and potential conversion errors. Please note that if dollars are provided, it should be with the complete cents value (i.e. 10.00).
items	Array	A list of line items associated with the order.

Order item parameters

Name	Type	Description
referenceId	String	A unique identifier of the product variant that is relevant to the business, like a variant ID.
name	String	The name of the product variant.
quantity	Integer	The total number of items.
discount	String	The sum of all discounts applied to the line item.
price	String	Decimal (not preferable)
tags	Array<String>	Additional detail that can be assigned to the product view for organizational purposes. This is optional. Some customers tag their products to try to group them. You could group products to find them faster in relation to purchases.
attributes	Object	Additional key-value attributes that can be assigned to the line item. This is optional. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.

Order cancelation

If you don’t have an order cancelation page or are not able to configure this one it is optional and not required for us to log purchasing events. However, if you don’t have these issues we encourage you to add this event as passing the order cancelation ensures Da Vinci maintains accurate conversions related to your email marketing campaigns.

This event will create a new order cancelation for the user. This should be called on your website whenever an order/transaction is cancelled prior to shipment.

Tracking order cancelations requires knowledge of the order details including line items when being called. When possible, it's important that an identity call has been made prior to creating an order completion as this will ensure the order can be linked to a user. The order parameters required are the same as an order completion.

For further details, please read the [event method docs. Using a standard web templating language, here is what an order completion might look like:

signal.event("orderCancelation", {
  order: {
    referenceId: "{{ order.id }}",
    subtotal: "{{ order.subtotal }}",
    items: [
      {
        referenceId: "{{ item.$.id }}",
        name: "{{ item.$.name }}",
        quantity: "{{ item.$.quantity }}",
        price: "{{ item.$.price }}",
      },
      {
        referenceId: "{{ item.$.id }}",
        name: "{{ item.$.name }}",
        quantity: "{{ item.$.quantity }}",
        price: "{{ item.$.price }}",
      },
    ],
  },
});

Order cancelation parameters

Name	Type	Description
order	Order	Detailed information about the order.
tags	Array<String>	Additional list of attributes that can be assigned to the order cancelation. This is optional. Some customers tag their products to try to group them. You could group products to find them faster in relation to purchases.
attributes	Object	Additional key-value attributes that can be assigned to the order cancelation. This is optional. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.

Order refund

This event will create a new order refund for the user. This should be called on your website whenever an order/transaction is refunded after shipment. Order refunds ensures Da Vinci maintains accurate conversions related to your email marketing campaigns.

Tracking order refunds requires knowledge of the order details including line items when being called. When possible, it's important that an identity call has been made prior to creating an order refund as this will ensure the order can be linked to a user. The parameters required are the same as an order completion.

For further details, please read the [event method docs. Using a standard web templating language, here is what an order completion might look like:

signal.event("orderRefund", {
  order: {
    referenceId: "{{ order.id }}",
    subtotal: "{{ order.subtotal }}",
    items: [
      {
        referenceId: "{{ item.$.id }}",
        name: "{{ item.$.name }}",
        quantity: "{{ item.$.quantity }}",
        price: "{{ item.$.price }}",
      },
      {
        referenceId: "{{ item.$.id }}",
        name: "{{ item.$.name }}",
        quantity: "{{ item.$.quantity }}",
        price: "{{ item.$.price }}",
      },
    ],
  },

Order refund parameters

Name	Type	Description
order	Order	Detailed information about the order.
tags	Array<String>	Additional list of attributes that can be assigned to the order refund. This is optional. Some customers tag their products to try to group them. You could group products to find them faster in relation to purchases.
attributes	Object	Additional key-value attributes that can be assigned to the order refund. This is optional. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.

Device relations

Signal supports cross-device relations. When a user first lands on your website - they are immediately assigned a unique browser ID. This serves as a long lived identifier of the device in use.

Once a unique identity call has been made on different devices (desktop, mobile, etc) - a relation between the browsers can be established. This means events generated on different devices can be used to understand the journey of a single identity.

Query String API

You can augment identity and event calls automatically based on URL query strings. This can be used to enhance email click-throughs so that automatic identification can occur.

Parameter	Description
cp_rid	This will automatically add a referenceId to any identity calls.
cp_cid	This will automatically add a Da Vinci contactId to any identity calls.
cp_src	This will automatically add a source to any method calls that use it.

For example, let’s assume we have the following URL in an email:

https://mywebsite.com/products/tshirt?cp_rid=12345&cp_src=email

Assuming the landing page is already making identity and event method calls - this would be equivalent to the following:

// Identity call
signal.identity({
  referenceId: "12345",
  source: "email",
});

// Page view event call
signal.event("pageView", {
  source: "email",
});

Once this user lands on your website - they would then automatically be identified. The source of the identification and page view would then also be attributed to an email.

The javascript will track activity on the client site. However, nothing will link any of that activity back to a DV contact and a DV campaign until the cp_cid parameter begins getting passed by our clickthroughs.

SDK API

The Signal JavaScript SDK exposes a simple API that lets you create a number of tracking events that map to our core resources. We've included a list of the available methods below.

init

This method should be run on every page that has the Signal Javascript SDK implemented. During init - the SDK will automatically attempt to create a new browser and session for the user if they have not been created already. These details are then included in subsequent requests.

Method example

signal.init("ACCESS_TOKEN", config);

You must replace the ACCESS_TOKEN with your access token.

Method parameters

Name	Type	Description
accessToken	String	A public access token provided to you by Da Vinci.
config	Config	Additional optional configuration.

Config parameters

Name	Type	Description
baseUrl	String	The Signal API server url - defaults to https://track.coherentpath.com.
currencyCode	String	The currency code used for all money types - defaults to USD.

`identity`

NOTE: Da Vinci’s javascript does not send nor store plain text data. Instead the data is hashed prior to transport and not persisted anywhere to ensure security. This identity event returns a pseudonymized identity_id that is stored locally by the javascript and is used for tracking all subsequent behavioural events.

This method will create a new identity for the user. An identity lets Da Vinci relate events to known users. An identity should be created whenever you have successfully identified a known user on your website. This could occur through something like login or registration. By default, identities are cached and automatically attached to subsequent method calls that require them. If an identity already exists - this becomes a no-op.

Method example

signal.identity({
  referenceId: "CUSTOMER-123",
  emailAddress: "test@email.com",
  source: "login",
  attributes: {
    name: "test",
  },
});

Method parameters

Name	Type	Description
identity	Identity	Attributes related to the creation of an identity.
callback	Function	An optional callback to make use of the identity response data.

Identityparameters

Name	Type	Description
referenceId	String	This is optional. Any string value that serves as unique identifier of the user that is relevant to the business.
*emailAddress	String	An email address of the user. **
*contactId	String	A unique Da Vinci contact ID.
source	String	The source of the identification.
tags	Array<String>	Additional list of attributes that can be assigned to the identity. This is optional. Some customers tag their products to try to group them. You could group products to find them faster in relation to purchases.
attributes	Object	Additional key-value attributes that can be assigned to the identity. This is optional. Some customers add attributes to their products for more detail. For example, if a product has reviews you could add the overall customer rating as an attribute.

emailAddress must be provided for this event to be instrumented. If you don’t have access or can’t provide emailAddress, Movable Ink will automatically trigger the identity event on the user’s first visit from an email using our script. No additional setup is required beyond ensuring that the core script is included.
Please note we do not send the email address in any requests. Rather - it is hashed into our contactId.

`event`

This method will create a new event for the user. Events let Da Vinci understand the navigation and interests of users. There are a number of different types of events available - each having their own specific paramater requirements. You can find more detail about these requirements in the events section.

Method example

signal.event(eventType, eventParams);

Method parameters

Name	Type	Description
eventType	Enum	One of the available event types.
eventParams	Object	Attributes related to the creation of the event.
callback	Function	An optional callback to make use of the event response data.

Event type Enum

Value	Description
"pageView"	A user viewing a web page.
"productView"	A user viewing a specific product.
"productSearch"	A user searching for a product.
"orderCompletion"	A user completing an order.
"orderCancelation"	A user cancelling an order.
"orderRefund"	A user getting a refund for an order.

`browser`

NOTE: You will likely never need to run this method since it is automatically run with init.

This method will create a new browser for the user. A browser lets Da Vinci relate user events over a long period of time. By default, browsers are cached and automatically attached to subsequent method calls that require them. If a browser already exists - this becomes a no-op.

Method example

signal.session();

Method parameters

Name	Type	Description
callback	Function<String>	An optional callback to make use of the browser ID.

`session`

You will likely never need to run this method since it is automatically run with init.

This method will create a new session for the user. A session lets Da Vinci relate user events over a short period of time. By default, sessions are cached and automatically attached to subsequent method calls that require them. If a session already exists - this becomes a no-op.

Method example

signal.session();

Method Parameters

Name	Type	Description
callback	Function	An optional callback to make use of the session response data.

`forget`

This method will remove any current identity data associated with the user. This would typically be run when a user logs out of their account. If no identity has been assigned to the user - this becomes a no-op.

Method example

signal.forget();

debug

This method will enable or disable debug mode for the Signal Javascript SDK. When debug is enabled - method calls will result in additional information being logged to the console.

Method parameters

Name	Type	Description
enabled	Boolean	A boolean representing whether debug is enabled.

Method example

signal.debug(true);

`whoami`

This method will check whether the accessToken provided with init is valid.

Method example

signal.whoami();

Method parameters

Name	Type	Description
callback	Function	An optional callback to make use of the account response data.

You can also QA if events are flowing through at a high level in the tracking UI once your script is activated by going into Settings > select Tracking and reviewing the data coming in. However, we recommend you look at your console for the details.

FAQ

What is the impact on website performance when Da Vinci's javascript SDK is placed on my website?

Your website will be uninterrupted since the script is loaded asynchronously. Our script is loaded from a CDN whenever possible and dynamic compression is enabled to limit bandwidth requirements.

For example, here are sample test load times:

Min: 31.3 ms
Median: 48.7 ms
95th percentile: 60.1 ms
99th percentile: 217.8 ms
Max: 342.2 ms

Javascript SDK

Quickstart

Identify users

Track events

Browsing

Products

Orders

Events

Page view

Page view parameters

Product page view

Product page view parameters

Product parameters

Product variant parameters

Product search

Product search parameters

Order completion

Order completion parameters

Order parameters

Order item parameters

Order cancelation

Order cancelation parameters

Order refund

Order refund parameters

Device relations

Query String API

SDK API

init

Method example

Method parameters

Config parameters

identity

Method example

Method parameters

event

Method example

Method parameters

Event type Enum

browser

Method example

Method parameters

session

Method example

Method Parameters

forget

Method example

Method parameters

Method example

whoami

Method example

Method parameters

FAQ

What is the impact on website performance when Da Vinci's javascript SDK is placed on my website?

Categories

`identity`

`event`

`browser`

`session`

`forget`

`whoami`