How to display promo assets using headless integration

Introduction

Once a promo asset has been created in Cortex, there are two ways it can be displayed. Firstly, by using an embed code, meaning the content has pre-set design characteristics; and secondly, by using ‘headless integration’, meaning you use an API call to pull the content into your site or app.

The advantage of headless integration is that you decide the design according to your requirements and the specification of your website or app. You can place your promo asset into a range of different locations and you can use fields such as tags, linkedIds and categories to render the content appropriately to your site context.

This document addresses the latter of these two methods - headless integration.

Preparing to display promo assets using headless integration

Before a promo asset can be displayed, it needs to have been created in Cortex, and you will need to identify the key field values, set in Cortex, for use in the API call.

If the promo asset is not yet present in the Promo Assets area of your Cortex account, please follow the steps in the document: How to create a promo asset. (Note: This link will take you to an Academy document.)

If you need to establish the names and values of specific fields set in the promo asset for use in your API endpoint calls, please refer to the section of this article entitled: How to find the promo assets field values.

API call constructs

The application presenting the content is responsible for calling it by addressing the API endpoint using the following call constructs.

Environments

In every call, you can address either the staging (test) or production (live) environment ID:

• Staging: https://stage-promoblocks-cms-api.incrowdsports.com/
• Production: https://promoblocks-cms-api.incrowdsports.com/

Fetch and execute a promo asset

There are two phases to displaying a promo asset.

• The API ‘get’ call is structured to fetch the appropriate promo asset for your requirement.
• The execution takes place when the page is loaded by the user and the specific content, personalised to this user profile (if an authentication token is present in the header) and/or to this device ID, is pulled into the page. For more on authentication, see Associated articles, below.

To fetch a promo asset, the minimum call is like this:

curl {environment-id}/v1/{clientId}/campaigns/content/{ids}

In which:

• environment-id is the URL for stage or production, as listed above.
• clientId is your client ID, assigned during onboarding. This can also be found in Cortex (see below).
• ids is a comma-delimited list of promo asset IDs. These are found in Cortex or in the URL of the promo asset, as described in How to create a promo asset

📘

Note

In all examples, the fields which may be populated are in curly brackets "" to make them clear. These brackets should be removed when a value is assigned to a field.

Filtering options

You can extend this fetch to pull promo assets identified by implicit tags, categories, title or linkedIds, using the following construct:

curl {environment-id}/v1/clientId/campaigns/content?tags={tags}&categories={categories}&title={title}&sort={sortField}&linkedIds={linkedIds}

In which:

• environment-id is the URL for stage or production, as listed above.
• clientId is your client ID, assigned during onboarding. This can also be found in Cortex (see below).
• tags is a comma-delimited list of tags assigned to promo assets. The response will include all promo assets which have one of the specific tags set.
• categories is a comma-delimited list of categories assigned to promo assets. The response will include all promo assets which have one of the specific categories set. See section 4, below, for how to set up and find category IDs.
• title is a string that is present in the promo asset title. The response will include all promo assets which have this string in the title.
• sort is the field used to sort the content, for example, publishDate. Adding a '-' to the sort field means to sort in descending order; for example, -publishDate. (The default sort is -publishDate.)
• linkedIds is a comma-delimited list of data providers and their corresponding IDs. The response will include all promo assets which have one of the specific linkedIds set in the promo asset. The format of a list of linkedIds is: SOURCE:ID,ID,ID|SOURCE:ID|SOURCE:ID,ID and so forth.

To find any of these in Cortex, see the section, How to find the promo asset field values, below.

Get promo asset summaries

To fetch (Get) promo asset summaries, use the construct:

curl {environment-id}/v1/{clientId}/campaigns/summary

In which:

• environment-id is the URL for stage or production, as listed above.
• clientId is your client ID, assigned during onboarding. This can also be found in Cortex (see below).

📘

Note

Calling content summaries does not load the content or create the conditions to execute the content. It purely provides summary information on the content.

Filtering options

You can extend this fetch (Get) to pull promo asset summaries according to implicit fields using the following construct:

curl {environment-id}/v1/{clientId}/campaigns/summary?size={size}&sort={sortField}&page={page}&title={title}&tags={tags}&categories={categories}&active={active}&published={published}&linkedIds={linkedIds}

In which:

• environment-id is the URL for stage or production, as specified at the top of this section.
• clientId is your client ID, assigned during onboarding. This can also be found in Cortex (see below).
• size is the numeric value for the number of items to return per page.
• sort is the field used to sort the content, for example, publishDate. Adding a '-' to the sort field means to sort in descending order. for example, -publishDate. (The default sort is -publishDate.)
• page the page number to return (0-indexed).
• title is a string. It returns all promo assets where at least part of the title contains the specified string.
• tags is a comma-delimited list of tags. It returns only the promo assets with those tags.
• categories is a comma-delimited list of categories. It returns only the promo assets with those categories.
• active is a Boolean. It returns only active promo assets; that is, setting it to true captures promo assets in which today is between validFrom and validTo values; and publishDate is less than today. false captures promo assets in which publishDate is null or is in the future; OR the validFrom value is in the future OR the validTo value is in the past. If no value is passed, this entire block of logic is ignored.
• published is a Boolean which returns only published (true) or not published (false) promo assets.
• linkedIds is a delimited list of data providers and their corresponding IDs. The format is:
  SOURCE:ID,ID,ID|SOURCE:ID for example OPTA_FOOTBALL_PLAYER:3992,3492|OPTA_FOOTBALL_TEAM:t43

How to find the promo asset field values

To identify the values in the fields used in the above API call constructs, step through the following process:

1. Log in to Cortex, and in the menu down the left-hand side, click Promo Assets.

The Promo Assets screen is displayed.

2. On the far right-hand side, there are three vertical dots for each line entry.
   Click on the three-dots for your target promo asset, and select: View embed code.

3. The embed code for this promo asset is displayed.

As you can see, the embed code includes the promo asset ID (cortex-promo-asset id) and your client ID (client-id), both of which you need in addressing the endpoint to pull the promo asset down to your website.

4. Double-click the row entry for the promo asset for which you would like to find API call data; such as the title, publishing Start time and Closing time, publishing status, tags, categories and linkedIds.
   You will be presented with the editor screen for the selected promo asset.

The main screen for the selected promo asset is displayed. In the top part of the screen, note that the promo asset ID (pcb-id) is present in the URL, as highlighted. The Title of the promo asset is at the top of the main panel, and the rule base to create personalised variants is below that. The publication window Start time and Closing time are set in the top-right, and the publication Status is on the toggle switch just below that. All of these fields may play a role in your API call, as documented above.

5. Scrolling down, in the lower part of the window on the right, is the Taxonomies panel:

Here you will find any assigned categories, tags and LinkedIds for this promo asset. In the example screenshot, no categories have been set, there are two tags: AppHome1 and AppHome2 and a single linked ID has been set via Opta to the footballer, Edward Smith.

How to find category IDs

Categories are set up in the settings page of the Promo Assets section of the Cortex platform. Once they are set, they appear in the Categories drop-down list within the Taxonomies panel of a promo asset. Follow the process below to find the category IDs for use in API calls.

1. Log in to Cortex. On the left-hand side click Content or Promo Assets, as appropriate to your API call. Then click the Settings icon, as highlighted in the screenshot below.

2. You are presented with the Settings screen.

Select the Categories tab, (as numbered 1., in the above screenshot). The list of categories is displayed in the main panel. Select the Three Dots icon at the right-hand end of the category entry for which you would like the ID (numbered 2. in the screenshot).
A drop-down list is displayed, (3.). From this drop-down, select Copy ID. In this case, the Category ID for the Competition category for use in the API call is: 30305f2c-b929-5a26-a185-b0629816b2b8.

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.