Impression tracking metrics for promo assets

📘
Note
This document applies to tracking impressions in promo assets using headless integration. It is not applicable to promo assets using an embed code. For details on tracking with an embed code, please refer to: How to display promo assets using an embed code

What is impression tracking?

Cortex provides the capability to deliver web impression metrics for promo assets. When a user scrolls the whole way through a content block that has been wrapped in the impression tracking code, an impression is counted.

There are two areas within the Promo Assets area of Cortex where these metrics are displayed: in the Impressions column, and in the Tracking panel. To find these, follow these steps:

Open Cortex, and in the menu down the left-hand side, select Promo Assets. A list of your organisation’s promo assets is displayed, and against each row entry, there is a column entitled Impressions listing the number of impressions logged against that promo asset.
Alternatively, click on the row of your choice. The detail for that promo asset is displayed. As you can see, there is a panel entitled Tracking on the right-hand side, showing the number of logged impressions. The number of clicks can also be displayed in the tracking panel.

How to implement website impression tracking

After a request for a promo asset returns with a status of ‘success’, then the tracking function (see below) can be called, which will track the request for this block. The tracking function will send an event with associated data to a tracking Cortex API endpoint, and the impression will be counted in Cortex.

How to set up the tracking function

In the code snippet below, you can see the tracking function that uses Cortex settings to send events with the required data. Use this code along with the notes that follow:

const baseUrl = 'ENVIRONMENT-ID'
const clientId = YOUR_CLIENTID
fetch(${baseUrl}/${clientId}/events,
{
    method: 'POST',
    body: JSON.stringify({ events: YOUR_ARRAY_OF_EVENTS}),
    headers:
     {
        'X-API-KEY': YOUR_API_KEY,
        'X-REALM': clientId,
        'X-APP-ID': 'web'
    }
}

At the initialisation of the front-end code you need to set the baseUrl environment variable for Stage or Production. To achieve this, replace the ENVIRONMENT-ID with one of the following:

For Stage use: https://ctr-stage.incrowdsports.com/v1
For Production use: https://ctr.incrowdsports.com/v1

Replace the placeholder YOUR_CLIENTID with your own client ID and YOUR_API_KEY with your API key. These were both issued to you by Cortex as part of your initial account setup.

Creating an event

An Event is a Javascript object that contains data from the promo asset itself, along with the date and a generated ID. The key to these fields follows this code snippet.

{
  "eventId": "D37882D6-56DF-58A8-A3AB-26BD84250632",
  "eventType": "REQUEST",
  "createdTimestamp": "2020-08-12T13:00:52.531Z",
  "sentTimestamp": "2020-08-12T13:00:52.531Z",
  "deviceId": "123",
  "appVersion": "1.2.4",
  "authId": 123,
  "sourceSystem": "PROMOBLOCKS",
  "sourceSystemId": "123-456-900-001",
  "campaignCodes": [
    "de8e6695-5f8d-44ea-9a62-070aa12a0034",
    "4ee8a0f1-ddc5-424f-8139-7db01e6eb045"
  ],
  "metadata": {
    "language": "en",
    "promoBlockName": "Test Campaign",
    "rulesetId": "5ece7bc30a892d37b4c16a8e",
    "rulesetName": "Ruleset name here",
    "promoBlockVersion": 1,
    "contentType": "IMAGE"
  }
}

Code Fields

Note that some fields are optional.

Field Name	Type	Required	Description
eventId	string (uuid rfc4122)	true	Event ID in UUID RFC4122 format. Generated on the client device, allowing clients to retry if the call fails.
eventType	string	true	Type of event that is being tracked. REQUEST, VIEW, OPEN, DEEP_LINK_CLICK.
createdTimestamp	timestamp (ISO8601)	true	Timestamp event recorded on the client device
sentTimestamp	timestamp (ISO8601)	true	When the event was sent by the device
deviceId	string	false	Device unique identifier
appVersion	string	false	App version
authId	long	false	User’s authentication ID from their JWT (JSON Web Token)
sourceSystem	string	true	Source system in which the event occurred. Currently, supported - PROMOBLOCKS, POLL, ARTICLE, OTHER
sourceSystemId	string	true	Source system ID; in the above example, this is the article ID within the source system
campaignCodes	[]string	false	List of optional campaign codes associated with the content
metadata	map[string]T	true	Metadata of any map type. For promo assets rulesetId is a required field.

Examples

Below is an example of how you can create an event object from data contained in the promo asset:

const currentDate = (new Date()).toISOString();
const event = {
    eventId: uuid(), // we use this popular JS library to create ids on the client side
    eventType: 'REQUEST',
    createdTimestamp: currentDate,
    sentTimestamp: currentDate,
    sourceSystem: 'PROMOBLOCKS',
    sourceSystemId: PCBContentData.campaign.id,
    metadata: {
        language: 'en',
        promoBlockName: PCBContentData.campaign?.description,
        rulesetId: PCBContentData.rulesetId,
        rulesetName: PCBContentData?.rulesetName,
        promoBlockVersion: 1,
        contentType: PCBContentData.contentType
    }
};

Below is an example of data for delivering a metric on impression of image in a promo asset:

{
    "contentType": "IMAGE",
    "content": "",
    "image": "https://media-cdn.cortextech.io/12eb3436-80f3-4d17-a173-a9b62dbc7562.png",
    "link": "https://ctr.cortextech.com/track
hash=4315f35e45646a7cd8f2382d765117cac4b7e67e075bc14024b09d01ab425d11ba6bd4f41ddc9832ecd3e99d99d100627e773908a4d29bfe93e1a53985bec425&t=1667387940&url=eyJjbGllbnRJZCI6IkJJUk1JTkdIQU1GQyIsInNvdXJjZVN5c3RlbSI6IlBST01PQkxPQ0tTIiwic291cmNlU3lzdGVtSWQiOiJlMjM0OGFmNC1kM2UwLTU1NjgtOWUxNi1kZjMxYWYxYTBjOTEiLCJvcmlnaW5hbFVybCI6Imh0dHBzOi8vYmx1ZXMuY2x1YnN0b3JlLmNvLnVrL2F3MjIiLCJhdXRoSWQiOjM0NzYsIm1ldGFkYXRhIjp7InByb21vQmxvY2tOYW1lIjoiQXV0dW1uIENhbXBhaWduIChMYW5kc2NhcGUpIiwicHJvbW9CbG9ja1ZlcnNpb24iOjIsInJ1bGVzZXRJZCI6IkRlZmF1bHQgY29udGVudCIsInJ1bGVzZXROYW1lIjoiRGVmYXVsdCBjb250ZW50In19",
    "pollId": null,
    "formId": null,
    "campaignCodes": [
        "de8e6695-5f8d-44ea-9a62-070aa12a0034",
        "4ee8a0f1-ddc5-424f-8139-7db01e6eb045"
    ],
    "tags": null,
    "categoryIds": null,
    "articleIds": null,
    "linkedIds": null,
    "feedUrl": null,
    "isHtml": null,
    "campaign": {
        "id": "e2348af4-d3e0-5568-9e16-df31af1a0c91",
        "validTo": null,
        "publishDate": "2022-09-28T12:13:57.573Z",
        "campaignCodes": null,
        "tags": [],
        "categories": [{
                "id": "f6b408ba-33d0-5597-adf8-946ef09e7994",
                "text": "ExampleTV 2"
            },
            {
                "id": "80490f4c-8d15-54c1-b287-f2d17768d340",
                "text": "Homepage 1"
            },
            {
                "id": "149ed2fb-9f34-5915-a2b3-e07825a98b0b",
                "text": "News 1"
            },
            {
                "id": "dd2c327d-bc79-5042-8e7f-6f840edbcead",
                "text": "Contact-Us"
            },
            {
                "id": "949e5abd-f63b-5d09-876d-f9e3ce8fc1ef",
                "text": "Matches 1"
            },
            {
                "id": "4a9a689f-c8ac-5ae4-9bbd-bcd558d6dafc",
                "text": "Teams 1"
            }
        ],
        "description": "Autumn Campaign (Landscape)",
        "linkedIds": [],
        "targetDescription": null,
        "locationDescription": null,
        "impressions": {
            "count": 0,
            "limit": null
        },
        "clicks": {
            "count": 802,
            "limit": null
        }
    },
    "rulesetName": "Default content",
    "rulesetId": "Default content"
}

Impression tracking with an embed code

An API tracking key can be used to enable impression tracking when displaying a promo asset using an embed code using event-tracking-key:

<cortex-promo-asset id="PCB-ID" client-id="CLIENT-ID" server="standard" event-tracking-key="YOUR KEY" stage></cortex-promo-asset>
<script src="https://promo-asset.cortextech.io/index.js"></script>

Note that YOUR KEY is issued by Cortex and its use is optional. Contact your Cortex administrator or account manager if you do not know your API tracking key. For more on this, please see

Was this page helpful?

If you need further assistance, or would like to suggest improvements or provide feedback, we would love to hear from you. Please contact us via the Help centre.

📘Note

What is impression tracking?

How to implement website impression tracking

How to set up the tracking function

Creating an event

Impression tracking with an embed code

Was this page helpful?

📘
Note