Overview

Once a promo asset has been created in the Cortex platform, there are two ways it can be displayed. Firstly, by using an embed code, meaning the content has pre-set design; and secondly, by using what is called ‘headless integration’, meaning you decide the design according to your needs and the nature and form of your website or app.

This document addresses the first of these topics - using an embed code. If you would like to know more about setting your own display characteristics, see How to display promo assets using headless integration

For more on creating promo assets, see How to create a promo asset). (Note: This link will take you to an Academy document.)

Registering the custom element

Firstly, the following JavaScript needs to be loaded in order to register the custom element:

<script src="https://promo-asset.cortextech.io/index.js"></script>

Once the script is loaded, the custom element <cortex-promo-asset> will be available.

Attributes

The <cortex-promo-asset> custom element supports the following attributes:

id

Optional ID of the promo asset.

locale

Optional locale code to be passed down when the promo asset will display a poll. It supports comma-separated values for fallback locales, e.g. es,fr,it

client-id

Required ID of the client.

stage

Optional Boolean, if set to true, the web component will talk to the Cortex stage backend.

server

Optional string. If the poll was produced in the Cortex USA environment, you need to set server to us.

access-token

Optional string for passing in a Cortex JWT token. It is advised to not use this attribute to pass in the token on the web as it will be observable in the DOM tree.

access-token-cookie-name

Deprecated as it is advised to not store the token in a cookie, but it is implemented for backward compatibility.

Optional, when provided, it will be used to get the token from the specified cookie.

access-token-callback-name

Optional string, when provided, it will be used to get the token from the specified callback function. It is expected that this function is a property of globalThis and will return the token when called. Supports nested properties, e.g. globalThis.myObject.myFunction.

event-tracking-key

Optional string, when provided, it will be used to track the REQUEST event. The event won't be tracked if the key is not provided or if trackingEnabled (a campaign property) is false.

tags

Optional string, which will be used for fetching promo assets with the specified tag, if provided.

categories

Optional string, which will be used for fetching promo assets in the specified category, if provided.

linked-ids

Optional string, which will be used for fetching promo assets with the specified linked ID, if provided.

consent

Boolean, which defaults to true. If set to false, the web component will not track any event or set any cookie.

cookie-domain

Optional string, when provided, it will be used to set the cookie domain.

device-id-cookie-name

Optional string, default is cortex_device_id. It will be used to get a device ID from the specified cookie.

device-id-callback-name

Optional string, when provided, it will be used to get the device ID from the specified callback function. It is expected that this function is a property of globalThis and will return the device ID when called. Supports nested properties, e.g. globalThis.myObject.myFunction.

Usage

<cortex-promo-asset id="PROMO_ASSET_ID" client-id="CLIENT_ID"></cortex-promo-asset>

You will be given a client ID at your initial account setup.

You can get the promo asset ID from:

• The Cortex platform
• The data provided by the promo asset block in an article.

If using the Cortex staging environment:

If the promo asset was produced in the Cortex staging environment, stage must be set:

<cortex-promo-asset id="PROMO_ASSET_ID" client-id="CLIENT_ID" stage></cortex-promo-asset>

Embed codes using other properties

The above example uses the promo asset ID to determine which promo assets should be displayed by the embed code; however tags, linked IDs and categories can also be used, as follows:

Using the tags property:

<cortex-promo-asset client-id="CLIENT_ID" tags="tag1,tag2"></cortex-promo-asset>

Using the categories property:

<cortex-promo-asset client-id="CLIENT_ID" categories="categoryID1,categoryID2"></cortex-promo-asset>

Multiple properties in the same API call must be comma-delimited, as shown in the above examples.

Using the linked-ids property:

<cortex-promo-asset client-id="CLIENT_ID" linked-ids="PROVIDER-AND-TYPE:3992,3492"></cortex-promo-asset>

A linkedIds entry may be comma-delimited within itself, like this:

PROVIDER-AND-TYPE:ID,ID,ID

For example: OPTA_FOOTBALL_PLAYER:1234,5678,9876

However, there may be multiple such entries, in which case the format is:

PROVIDER-AND-TYPE:ID,ID|PROVIDER-AND-TYPE:ID|PROVIDER-AND-TYPE:ID,ID and so on.

📘

Note

If there are multiple promo assets with the same category, tag or linked ID, the web component will always retrieve the one with the most recent published time.

Where are these properties set?

The above properties are set up in the Taxonomies and Linked IDs area of the promo asset creation screen in Cortex. Please refer to the document: How to create a promo asset for details.

Impression tracking

To enable impression tracking when using the embedded web component, three specific conditions must be met for successful tracking implementation:

1. The consent must be set to true, which is the default value so can be ignored
2. The event-tracking-key must be provided
3. Tracking must be enabled in Cortex

An API tracking key called the event-tracking-key is issued by Cortex and can be used to enable impression tracking within the embed. See YOUR_KEY in the example below.

<cortex-promo-asset id="PROMO_ASSET_ID" client-id="CLIENT_ID" event-tracking-key="YOUR_KEY"></cortex-promo-asset>

Note that using the event-tracking-key is required. Contact your Cortex administrator or account manager if you do not know your API tracking key.

Adding an access token

To enable some features, for example, to personalise based on data associated with a single sign-on account, the access token needs to be passed. While it is possible to pass in the token directly or pass in a cookie name as described in the above Attributes section. It is advised to use access-token-callback-name instead:

<script>
  globalThis.myFunctionToGetToken = (context) => {
    return 'ACCESS_TOKEN'
  }
</script>
<cortex-promo-asset
  id="PROMO_ASSET_ID"
  client-id="CLIENT_ID"
  access-token-callback-name="myFunctionToGetToken"
></cortex-promo-asset>

If the access token is not included, the session will be executed anonymously. However, if there is a device ID, the system will use historical information gathered against this device ID to provide promo assets. If the device ID is not present, a new one will be assigned and data gathered against it in order to provide promo assets to the anonymous user.

Global configuration

You can configure the web component globally by setting properties on globalThis.cortextech object.

globalThis.cortextech = {
  clientId: 'CLIENT_ID',
  accessTokenCallbackName: 'cortextech.myFunctionToGetToken',
  myFunctionToGetToken: (context) => {
    return 'ACCESS_TOKEN'
  }
}

Values set directly on the custom element will take precedence over global configuration. The following properties are available to be set globally:

• locale
• clientId
• server
• accessTokenCookieName
• accessTokenCallbackName
• eventTrackingKey
• cookieDomain
• deviceIdCookieName
• deviceIdCallbackName