The Clickstream API allows operators to pass event information to the Opti-X platform from web front ends including page views and key customer interactions such as game launches, login events, etc. Operators will often already be sending this information to web analytics platforms so the API makes it relatively easy to pass this information to us.

The clickstream API has been developed based on Segment.io’s open source Analytics.js scripts so has been designed to have a limited effect on page load, small footprint and automated retries. Detailed documentation from Segment is available here but if in doubt just ask.

API Usage

A code snippet will be prepared specifically for the brand/operator that allows the graphyte script to be downloaded, similar to the following:

window.graphyte||(window.graphyte={}),window.graphyte_queue||(window.graphyte_queue=[]),function(){for(var e=['identify','track','trackLink','trackForm','trackClick','trackSubmit','page','pageview','ab','alias','ready','group','on','once','off'],t=function(t){return function(){var e=Array.prototype.slice.call(arguments);return e.unshift(t),graphyte_queue.push(e),window.graphyte;};},a=0;a<e.length;a++){var r=e[a];window.graphyte[r]=t(r);}}(),graphyte.load=function(t){var e=document.createElement('script');e.async=!0,e.type='text/javascript',e.src='https://cdn.graphyte.ai/graphyte.min.js',e.addEventListener?e.addEventListener('load',function(e){'function'==typeof t&&t(e);},!1):e.onreadystatechange=function(){'complete'!=this.readyState&&'loaded'!=this.readyState||t(window.event);};var a=document.getElementsByTagName('script')[0];a.parentNode.insertBefore(e,a);},graphyte.load(function(){for(graphyte.initialize({graphyte:{apiKey:'api_key_provided_by_graphyte',brandKey:'brand_key_provided_by_graphyte'}});0<window.graphyte_queue.length;){var e=window.graphyte_queue.shift(),t=e.shift();graphyte[t]&&graphyte[t].apply(graphyte,e);}}),graphyte.page();

The script also contains logic to queue any events that happen before the script is fully ready to send to Opti-X. Once the script has loaded these will be sent. If there are any issues with connectivity retries will be handled with an exponential backoff.

Event tracking

The script will automatically send an initial page view message with relevant information to our servers. Depending on the architecture of the site additional (virtual) page views can be sent using the API.

Events are sent using the script in a similar way to how they would be sent to other 3rd parties such as Google Analytics. Detailed event structures should agreed as part of technical workshops: samples are below.

Events

Page View

As above page view events are automatically sent on loading the Opti-X clickstream. For single page applications additional page view events may need to be sent. These can be sent as below. Contextual page info will be automatically picked up by the API.

<!-- graphyte page tracking -->
<script type="text/javascript">
graphyte.page([category], [name], [properties], [options], [callback]);
</script>
<!-- graphyte page tracking ends -->

All parameters are optional:

category: Description of the category of the page

name: Page name

properties: A dictionary of properties of the page. url, title, referrer and path are populated automatically

options: Not used

callback: Function to call after sending the page view event

Identify

By default the API creates a persistent anonymous identifier for a user and stores this locally in a cookie for subsequent requests. In order to map this to a real user identifier the Identify command can be called which will populate all subsequent calls with the real ID.

<!-- graphyte identify tracking -->
<script type="text/javascript">
graphyte.identify([userId], [traits], [options], [callback]);
</script>
<!-- graphyte identify tracking ends -->

All parameters are technically optional although typically the userId would always be included:

userId: Identifier for the user from the back end system

traits: Dictionary of data about the user e.g. loyaltyId. Please consult Opti-X before populating anything in here to avoid sharing PII

options: Unused

callback: Function to call after sending event

Track

Additional events can be sent to Opti-X to identify game play, logins, deposits, withdrawals, registrations, etc. The schema is consistent for all events but please consult with Opti-X to identify the mapping for each event name. An example GAME_PLAY event has been shown below:

<!-- graphyte event tracking -->
<script type="text/javascript">
graphyte.track("GAME_PLAY", {
    "event_type": "gaming",
    "event_uuid": "",// uuid v4 
    "event_ref_id": "",// a reference to the game session
    "event_ref_type": "casino_game_id",
    "event_datetime": "2020-02-28T11:51:00Z", // event 
    "event_value": "10.00", // stake if you have it
    "event_info_1": "" // game code 
    "event_info_2": "Rainbow Riches", // game name
    "event_info_3": "Slots" // game category
    "event_value_2": "", // ignore unless you have ggr
    "event_value_3": "", // ignore unless you have num bets
    "event_country": "GB",
    "event_platform": "website.com",
    "event_ccy": "GBP",
    "event_language": "en",
    "event_location": "Most Popular" // list from where the game was launched,
    "event_location_index": 2 // 1-based index of where in the list it was placed
}, [options], [callback]);
</script>
<!-- graphyte event tracking ends -->

Parameters:

event_name: Name of the specific event e.g. GAME_PLAY

properties: Dictionary of event information. Discuss mapping with Opti-X.

options: Unused

callback: Function to fire after sending the event.

Non-Javascript Integration

The Clickstream SDK is a javascript wrapper for a set of API calls that map to each event type. These can be called directly if required, for example if integrating from a non-web based platform like native apps. If in any doubt seek guidance from your Integration Manager but the below shows how to map to URL responses directly:

NB One of the main benefits of the JS wrapper is its creation and persistence of anonymous user IDs and mapping to real IDs via the Identify call. This does not work in quite the same with if calling endpoints directly as cookies will not be set locally so the use of Identify here is redundant. This means that this integration type would not be able to support Opti-X ReTarget.

Endpoint:

https://api.graphyte.ai/clickstream/v1

e.g.

/p (e.g. https://api.graphyte.ai/clickstream/v1/p) = Page View

Example call:

curl 'https://api.graphyte.ai/clickstream/v1/p' \
  -H 'x-brand-key: YOUR_BRANDKEY' \
  -H 'content-type: text/plain' \
  -H 'x-api-key: YOUR_APIKEY' \
  --data-raw '{
    "context":{
      "page":{
        "path":"",
        "referrer":"",
        "search":"",
        "title":"",
        "url":""
        },
      "userAgent":"Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.69 Mobile Safari/537.36",
      "library":{"name":"graphyte.js","version":"2.11.0"}},
      "integrations":{},
      "properties":{
        "path":"",
        "referrer":"",
        "search":"",
        "title":"",
        "url":""
      },
      "anonymousId":"ANONYMOUS_USERID",
      "timestamp":"2021-11-22T15:03:21.944Z",
      "type":"page",
      "writeKey":"YOUR_APIKEY",
      "userId":"123456",
      "sentAt":"2021-11-22T15:03:21.948Z",
      "messageId":"UUID_OF_MESSAGE"}' \
  --compressed

/t = Track

curl 'https://api.graphyte.ai/clickstream/v1/t' \
  -H 'x-brand-key: YOUR_BRANDKEY' \
  -H 'content-type: text/plain' \
  -H 'x-api-key: YOUR_APIKEY' \
  --data-raw '{
  "integrations":{},
  "context":{
    "page":{
      "path":"",
      "referrer":"",
      "search":"",
      "title":"",
      "url":""
    },
    "userAgent":"Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.69 Mobile Safari/537.36",
    "library":{
      "name":"graphyte.js",
      "version":"2.11.0"
  }},
  "properties":{
    "event_type":"gaming",
    "event_uuid":"ae448afa-8987-4558-8683-6a4ffab7edca",
    "event_ref_id":"",
    "event_ref_type":"casino_game_id",
    "event_datetime":"2021-11-22T11:51:00.000Z",
    "event_value":"10.00",
    "event_info_1":"rainbowriches",
    "event_info_2":"Rainbow Riches",
    "event_info_3":"Slots",
    "event_value_2":"",
    "event_value_3":"",
    "event_country":"GB",
    "event_platform":"website.com",
    "event_ccy":"GBP",
    "event_language":"en"
    },
    "event":"GAME_PLAY",
    "anonymousId":"ANONYMOUS_USERID",
      "timestamp":"2021-11-22T15:03:21.944Z",
      "type":"track",
      "writeKey":"YOUR_APIKEY",
      "userId":"123456",
      "sentAt":"2021-11-22T15:03:21.948Z",
      "messageId":"UUID_OF_MESSAGE"}' \
  --compressed