Device Tracking

Ravelin’s Device Identification & Tracking API for web browsers, written in JavaScript, sends user activity directly from your website to Ravelin. This includes information about the device, pages viewed, and actions taken. Custom events can be tracked to ensure any subtleties are tracked.

The tracking library requires a Public API Key which can be sent to users’ browsers. The Public API Key is a write-only authorisation token which cannot be used to read data from Ravelin.

Authenticating Requests

First, acquire a publishable API Key from the developer section in your dashboard.

Getting Started

Embed the script with your Public API Key by including the following script snippet at the bottom of your HTML pages:

<script>
(function(r,a,v,e,l,i,n){r[l]=r[l]||function(){(r[l].q=r[l].q||[]).push(arguments)};i=a.createElement(v);i.async=i.defer=1;i.src=e;a.body.appendChild(i)})(window,document,'script','https://cdn.ravelin.net/js/rvn-beta.min.js','ravelin');
ravelin('setApiKey', 'your-api-key');
// ravelin('setCustomerId', '$CUSTOMER_ID'); (See below).
// ravelin('setCookieDomain', '.$MYDOMAIN'); (See below).
</script>

The following configuration options are supported:

  • ravelin('setCustomerId', '$CUSTOMER_ID') will file tracked events under a particular customer account. This is not required to track anonymous activity, but is expected when the customer is logged in. Should be set before calling any track methods on every page where we know the customer.
  • ravelin('setCookieDomain', '.$MYDOMAIN') will store the cookies under the named domain so that it can be shared between subdomains.

Tracking

With the script installed and configured we are now ready to send events to Ravelin. The following events should be triggered by your app:

  • ravelin('trackPage', {meta}) to indicate when the user hits a new page. You are encouraged to add metadata to describe the page that the user has landed on (such as search terms), especially if the URL does not contain that information.
  • ravelin('trackLogin', {meta}) to indicate that the user has just authenticated themselves. Separate setCustomerId calls should remain.
  • ravelin('trackLogout', {meta}) to indicate when the user has signed out of their session.

And from the checkout page we should call:

ravelin('fingerprint')

Custom Events and Metadata

The track method can be used to log notable client-side events:

ravelin('track', 'eventName', {meta})

Where the URL of a page does not fully describe the data contained within, custom track events can be used to provide Ravelin with that information. On a search results page reached with form POST, for example, you can send the user query with:

ravelin('trackPage', {query: "user's search query"});

Synchronising with Server-Side API

Ravelin’s device ID is made available to your server, and should be used as the deviceId in server-side requests made for the current session. This allows Ravelin to identify which customer orders were made from which device.

Beta Guarantee

Note that the library snippet included above is using rvn-beta.min.js - the beta release of Ravelin’s page-tracking. The API is intended to be released as-is when shipped as latest, but this is not guaranteed.

Upgrading from Live Version

  • The ravelinUuid cookie is being renamed to ravelinDeviceId.
  • The ravelin('send') call should be replaced with ravelin('fingerprint').