JS API

Cloudflare Rocket Loader WarningFor any on page scripts using the Content Ignite JS API, it is important that you exclude the script from Rocket Loader (if used), which defers JS and in the case of the examples below, can prevent them from running altogether. Our JS API is a simple and fast way to queue the passing of information to our Publisher Tag, and as a result of the code not running immediately, has nil impact on page performance. Read more

Passing data to ID/Signal providers

Definition

.passSignalData(type: 'email'|'phone', value: string)

When passing us PI for use by id/signal providers, ensure you pass it on every page load that the PI is available. For email, the obvious one is on login and every page load while logged in, but a secondary important scenario is newsletter sign up! In this case, you are looking to pass the email address at every opportunity.

PrivacyIt is worth noting that any PI passed through using this method never reaches the Content Ignite servers. We do not store this data in any way, we simply act as the “pipes” to pass it to the ID vendors you’ve configured in Fusion, all handled client side.

Example

window.__ciads = window.__ciads || { cmd: [] };
window.__ciads.cmd.push(() => {
  window.__ciads.passSignalData("email", "jamie@contentignite.com");
});

Setting targeting

Definition

.setTargeting(key: string, values: string | string[])

This method allows you to pass custom page targeting directly to our tag, this could be data returned by your CMS for example.

It is against our terms of service, and Googles, to pass in Personal Information via this feature, things such as email addresses, age, gender etc are forbidden.

Example

window.__ciads = window.__ciads || { cmd: [] };
window.__ciads.cmd.push(() => {
  window.__ciads.setTargeting("tags", ["news", "politics"]);
});

Mergeing vs Overwriting vs deleting key-values

When you call .setTargeting() with a string value, it will merge that value with any existing values for that key. If you call it with an array value, it will overwrite any existing values for that key. To delete targeting values for a given key, call .setTargeting() with the value NULL.

Config/Slot level targeting

Definition

.setTargeting(key: string, values: string | string[], slotId: string)

The optional third parameter of .setTargeting() allows you to pass targeting for a specific slot, identified by either the config ID, unit type or parent container ID. If not passed, the targeting will be applied at the page level.

Example

window.__ciads = window.__ciads || { cmd: [] };
window.__ciads.cmd.push(() => {
  window.__ciads.setTargeting("tags", "news", "12345"); // targeting for config with id of 12345
  window.__ciads.setTargeting("tags", "news", "in-image"); // targeting for all in-image units
  window.__ciads.setTargeting("tags", "news", "div-gpt-ad-1611935295857-0"); // targeting for the unit with the parent container ID of 'div-gpt-ad-1611935295857-0'
});

Targeting Macros

When passing targeting values, you can also use macros to pass dynamic values. The macros available are:

{CONFIG_ID} The config ID as it is in Fusion; e.g. 1234
{INSTANCE_COUNT} The instance count for repeating units; e.g. 1, 2, 3 etc
{UNIT_TYPE} Unit type from Fusion; e.g. in-image, adhesion, iab etc

Simply include the macro in the value string and it will be replaced with the relevant value for each ad unit when the tag processes the targeting.

Example

window.__ciads = window.__ciads || { cmd: [] };
window.__ciads.cmd.push(() => {
  window.__ciads.setTargeting("pos", "ad-{INSTANCE_COUNT}"); // will pass pos: ad-1 for the first instance of a unit, pos: ad-2 for the second instance etc
});

IAB Taxonomy (reserved keys)

We support two different IAB taxonomy types, which you can pass in via .setTargeting() by use of their reserved keys, these are:

IAB_AUDIENCE_1_1 - IAB Specification, List of Values
IAB_CONTENT_2_2 - IAB Specification, List of Values

For example, to pass the content taxonomy of “Automotive”, you’d call:

Example

window.__ciads = window.__ciads || { cmd: [] };
window.__ciads.cmd.push(() => {
  window.__ciads.setTargeting("IAB_CONTENT_2_2", [1]);
});

Note that if you enable contextual inside of Fusion for a given publisher, then the IAB_CONTENT_2_2 taxonomy is already passed for you!

SPA reloads

Definition

.reload()

Strictly for use in SPA’s (Single Page Applications). This will cause a new page impression to register and all existing ads to be destroyed and re-built.

Example

window.__ciads = window.__ciads || { cmd: [] };
window.__ciads.cmd.push(() => {
  window.__ciads.reload();
});

Tag Events

For custom development, there are several JavaScript events that are triggered throughout an ads life cycle. You can hook into these as needed to perform additional follow-up actions. These are standard JavaScript events, available on the window the tag was deployed into. For example, for a direct tag-on-page deployment, you can listen to an event with the following:

Example

window.addEventListener("ci_al", function (e) {
  console.log(e.detail);
});

Depending on the event, a detail object is returned with the following optional fields:

detail.config_id - STRING - The id of the ad unit the event was triggered from
detail.msg - STRING - Further details of the event
detail.targeting - OBJECT - The key-value targeting applied to the slot for the ad request. Only present on the ci_al and ci_am events (see Reading slot targeting below).

The following events are available:

Event Name	Description
Audience Push `ci_ap`	Fired when an audience is matched and will be pushed into Ad Manager. Fired once per ad unit.
Ad Impression `ci_ai`	Fired when an ad has had a viewable impression (50% of the ad’s pixels are visible in the browser window for a continuous 1 second.)
Page Impression `ci_pi`	Fired once for each page once the tag has loaded
Ad Unit Load `ci_aul`	Fired once an ad unit has been loaded. Once user consent has been received (if applicable) and an ad has been served. For in-view units, this will be once the in-view event was detected.
Ad Load `ci_al`	Fired once an ad unit has been loaded. Once user consent has been received (if applicable) and an ad has been served. For in-view units, this will be once the in-view event was detected. For refresh units, this will fire once per refresh.
Ad Miss `ci_am`	Fired if an ad unit did not receive an ad (either ad_load or ad_miss will be triggered for each ad and any subsequent refreshes)
Consent Denied `ci_cd`	Fired when user consent is required but was not given
Tag Error `ci_te`	Fired on an unexpected tag error

Reading slot targeting

The ci_al (Ad Load) and ci_am (Ad Miss) events include a detail.targeting object containing all of the key-value targeting that was applied to that slot for the ad request — in other words, everything that was sent to the ad server. This includes any values you set via .setTargeting(), the tag’s own key-values, and the header-bidding keys applied during the auction (such as hb_pb, hb_size, amznbid and amznsz). Each value is returned as an array of strings. This lets you react to the outcome of the auction — for example the winning size and price — from your own page code, without needing to read from Prebid or Amazon directly.

Example

window.addEventListener("ci_al", function (e) {
  console.log(e.detail.config_id); // e.g. "12345"
  console.log(e.detail.targeting);
  // {
  //   "hb_pb": ["7.00"],
  //   "hb_size": ["970x250"],
  //   "amznsz": ["970x250"],
  //   "pos": ["ad-1"]
  //   // ...plus any other key-values applied to the slot
  // }
});

Getting started

Integrations

Publishers & Tags

Audiences

Orgs & Users

Reporting & Alerts

Passing data to ID/Signal providers

Setting targeting

Mergeing vs Overwriting vs deleting key-values

Config/Slot level targeting

Targeting Macros

IAB Taxonomy (reserved keys)

SPA reloads

Tag Events

Reading slot targeting

​Passing data to ID/Signal providers

​Setting targeting

​Mergeing vs Overwriting vs deleting key-values

​Config/Slot level targeting

​Targeting Macros

​IAB Taxonomy (reserved keys)

​SPA reloads

​Tag Events

​Reading slot targeting

Passing data to ID/Signal providers

Setting targeting

Mergeing vs Overwriting vs deleting key-values

Config/Slot level targeting

Targeting Macros

IAB Taxonomy (reserved keys)

SPA reloads

Tag Events

Reading slot targeting