Guides
Start typing to search…

How to embed a poll

This article explains how to embed a poll, or multiple polls, into a web page or app.

Cortex Poll

Cortex Poll is a web component.

Registering the custom element

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

<script src="https://poll.cortextech.io/index.js"></script>

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

Attributes

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

id

Required ID of the poll.

locale

Optional locale code to be used when fetching poll. Can provide a comma-separated value 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 poll property) is false.

share-url

Optional string, which will be used for social sharing, else window.location.href will be used.

on-submit

Optional string, when provided, it will be used to find and call a function. It is expected that this function is a property of globalThis. Supports nested properties, e.g. globalThis.myObject.myFunction.

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. 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-poll id="POLL_ID" client-id="CLIENT_ID"></cortex-poll>

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

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.

Usage example:

<cortex-poll id="a5363ca3-b1ed-3807-89c7-0cb2f426d269" client-id="DEMO"></cortex-poll>

If using the Cortex staging environment:

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

<cortex-poll id="POLL_ID" client-id="CLIENT_ID" stage></cortex-poll>

Adding an access token

Promo assets and forms may be included in the poll success message. Each has some personalisation features which depend on identification of the fan. 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-poll
  id="POLL_ID"
  client-id="CLIENT_ID"
  access-token-callback-name="myFunctionToGetToken"
></cortex-poll>

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, 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.

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" client-id="CLIENT_ID" locale="es-AR,es,en"></cortex-poll>

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" client-id="CLIENT_ID" share-url="https://www.example.com"></cortex-poll>

On submit callback

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 myFunctionOnSubmit with your function name.

<script>
  globalThis.myFunctionOnSubmit = (context) => {
    console.log(context)
  }
</script>
<cortex-poll id="POLL_ID" client-id="CLIENT_ID" on-submit="myFunctionOnSubmit"></cortex-poll>

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'
  },
  onSubmit: 'cortextech.myFunctionOnSubmit',
  myFunctionOnSubmit: (context) => {
    console.log(context)
  }
}

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
  • shareUrl
  • onSubmit
  • cookieDomain
  • deviceIdCookieName
  • deviceIdCallbackName

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).

{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.

Updated about 2 months ago