Embedding an individual poll

A basic implementation of an individual poll into a webpage or app can be achieved by adding the embed code below.

<cortex-poll id="{poll-ID}" client-id="{client-ID}" server="{server}"></cortex-poll>
<script type="text/javascript" src="https://poll.cortextech.io/index.js"></script>

In which:

{poll-ID} needs to be replaced with the poll ID for the specific poll you wish to run. You can get the poll ID from three places:

• The Cortex platform
• The data provided by the poll block in an article.
• The poll API.

More on each of these methods is detailed below.

{client-id} needs to be replaced with your organisation’s client ID. This will have been assigned to you as part of your initial account setup.

{server} needs to be replaced with either us if the poll was produced in the Cortex USA environment, or standard if the poll was produced in the Cortex standard environment. If server="{server}" is omitted, the default is standard

For example:

<cortex-poll id="a5363ca3-b1ed-3807-89c7-0cb2f426d269" client-id="DEMO" server="standard"></cortex-poll>
<script src="https://poll.cortextech.io/index.js"></script>

If using the Cortex staging environment:

If the poll was produced in the Cortex staging environment, stage must be included within <cortex-poll>, like so:

<cortex-poll id="{poll-ID}" client-id="{client-ID}" server="{server}" stage></cortex-poll>
<script type="text/javascript" src="https://poll.cortextech.io/index.js"></script>

Obtaining the poll ID

Obtaining the poll ID from the Cortex platform

The easiest way to get the poll ID is as follows:

1. Open the Cortex platform, and navigate to Polls in the left-hand sidebar.
2. Find the poll you want to embed from the list of polls, and click the three dots on the right-hand side.
3. Click View embed code. A popup containing the embed code is displayed.

Note that this method returns the entire embed code, including the poll ID and an appropriate environment declaration and client ID for this poll

Obtaining the poll ID from a poll block in an article

When a poll block is added to an article, the JSON for that article will include the poll ID. For example, in a demo article, the entire poll block looks like this:

{
  id: "6e265370-bd4f-4e1e-be6f-4763bb63bb0a",
  contentType: "POLL",
  sponsor: { },
  pollId: "9a59cb9b-222d-3468-8499-588ad957300f"
}

The website or app can then inherit the Poll ID from the article and use it to populate the embed code using this pollId.

Note that, using this method, a content author does not have to add the embed code for each use, they just have to add a poll block to their article. This method is recommended for any website powered by the Cortex CMS.

Obtaining the Poll ID from the API

All poll data, including poll IDs, can be obtained via API from the following API call:

💻

GET {environment-id}/v2/polls?clientId={clientId}&size={size}&page={page}&sort={sortField}&tags={tags}&linkedIds={linkedIds}&from={from}&to={to}&active={active}

In which:

{environment-id} is the URL for stage (test) or production (live).

• Stage: https://polls-stage.fanscore.com
• Production: https://polls.fanscore.com
• Production (US environment): https://polls.fanscore.us

{clientId} is your client ID, assigned during onboarding.

{page} is the index of the page to return. The default is page=0, meaning only one page - the first page - should be returned.

{size} is the number of polls to be included on each page. So, effectively it defines the size of the result set for paginated requests.

{sortField} is a string representing the sort options. Putting a '-' in front of the parameter will sort in descending order. In practical terms, the most commonly used is -validTo.

{tags} is a comma-delimited list of tags. Adding this returns only the polls with those tags.

{linkedIds} is a delimited list of data providers and their internal data IDs. The semicolon is the delimiter. The format is SOURCE:ID,ID,ID;SOURCE:ID. For example OPTA_FOOTBALL_PLAYER:3992,3492;OPTA_FOOTBALL_TEAM:t43

{to} specifies an upper limit or endpoint for date filtering in ISO 8601 format, restricting to polls up to a specific date. For example ?to=2023-11-08T00:00:00.000Z.

{from} is a lower limit or starting point for date filtering in ISO 8601 format, restricting to polls from a particular date onwards. For example ?from=2023-11-08T00:00:00.000Z.

{active} is a Boolean indicating whether the poll is currently active, that is, published but not yet closed.

This solution is recommended for use cases where the poll should appear automatically based on the addition of a linked ID or a tag. The main example being match centres.

Enabling personalised promo assets and forms in the success message

Promo assets and forms may be included in the poll success message. Each has some personalisation features which depend on identification of the fan. This is enabled in one of two ways, depending upon whether the fan is logged in or not.

Logged-in user

Cortex’s single sign-on capability (SSO), uses JWTs (JSON Web Tokens) for authorisation. Once the user is logged in, each subsequent request in the session will include the JWT access token, allowing the user to access routes, services, and resources that are permitted with that token.

Within a poll, the access token can therefore be passed in by adding: access-token="{token}", to the poll embed, with {token} representing the user’s token.

For example:

<cortex-poll id="{poll-ID}" access-token="{token}" client-id="{client-ID}"></cortex-poll>
<script type="text/javascript" src="https://poll.cortextech.io/index.js" />

The system also supports access-token-cookie-name and access-token-callback-name as alternatives to directly passing in an access-token, by referencing a cookie or callback from which the token can be obtained.

For example:

<cortex-poll id="{poll-ID}" access-token-cookie-name="{cookie-name}" client-id="{client-ID}"></cortex-poll>
<script type="text/javascript" src="https://poll.cortextech.io/index.js" />

Initiating a callback function

Alternatively accessTokenCallbackName can be used to get the token. It is expected that this function is a property of globalThis and will return the token when called. For example:

<script>
globalThis.myFunction = () => ACCESS_TOKEN
</script>

<cortex-poll id="{poll-ID}" access-token-callback-name="myFunction" client-id="{client-ID}"></cortex-poll>
<script type="text/javascript" src="https://poll.cortextech.io/index.js" />

Other users

Users who are not logged in will be able to access the poll in exactly the same way as a logged in user, however the token will be generated by the library, which will identify the user as anonymous and grant access and resources appropriately.

Restricting users to one vote

Logged-in users will be restricted to one vote through assertion of their identity, using the method described above.

Anonymous users are restricted to one vote using a cookie. Fans can get around this (through clearing their cookies or using different browsers), so if restricting users to one vote needs to be strictly enforced then the poll should be shown only to logged-in users.

Localisation

Within the Cortex platform, within a single poll, a user can select a default locale as well as number of additional locales for a poll. For each locale added they can then configure the content of the poll separately. Additionally, hard-coded text in the poll (such as the button "Vote now"), will be translated automatically.

You might notice that this works differently to, where it’s one-locale-per-article but with relationships between articles. Polls behaves differently, with one poll having multiple locale variants. This is because it is important that there is a single vote count across all locales.

To achieve multilingual polls on the front end, you will need to specify the desired locale within the embed code, such as locale="es". Fallback locales can be achieved by including a comma-separated list of locales, such as locale="es-AR,es,en". In this example, if a poll variant exists in Argentinian Spanish, this will be provided; otherwise the embed code will attempt to load a Spanish variant if possible; otherwise an English variant. This is shown in the example below.

<cortex-poll id="{poll-ID}" access-token="{token}" client-id="{client-ID}" locale="es-AR,es,en"></cortex-poll>
<script type="text/javascript" src="https://poll.cortextech.io/index.js" />

Within Cortex, a default locale can be set. This will be used if you do not specify a locale in the embed code; or if there is no available variant matching the specified locale or fallback locales.

Configuring the share URL

The poll embed includes a share feature, enabling fans to share the poll via X, Facebook, email, or to copy a share message. A URL will be shared, and by default that URL will be whatever webpage the poll was embedded onto. You may want to adjust this behaviour, such as where the poll is embedded in an iOS or Android app, or an alternative URL is desired. To achieve this, you can add a share URL into the embed code using share-url="https://www.example.com", with example.com being replaced by your preferred URL.

<cortex-poll id="{poll-ID}" access-token="{token}" client-id="{client-ID}" share-url="https://www.example.com"></cortex-poll>
<script type="text/javascript" src="https://poll.cortextech.io/index.js" />

Initiating a callback function

Lastly, a prop can be added to the poll embed code, with which you can pass in the name of a callback function to be triggered when the ‘Vote now’ button is clicked.

The primary use case for this is tracking, i.e. you might create a function that will fire a tracking event tag, although there may be other use cases that can be served via a callback function.

For example, see on-submit in the below, in which you can replace myFunction with your function name.

<cortex-poll id="{poll-ID}" access-token="{token}" client-id="{client-ID}" on-submit="myFunction"></cortex-poll>
<script type="text/javascript" src="https://poll.cortextech.io/index.js" />