Skip to main content

JavaScript SDK

The SDK is the script that manages widgets on your page. It's in charge of getting content (whether editorial or sponsored) and place it correctly in your pages.

  • It initialises and identifies the page as yours
  • It calls our content server to check if there's content to display
  • It watches the page for changes, so that if a new slot is available, it can be filled

Installation#

Add this code right after the opening <body> tag, and replace YOUR_ACCOUNT_ID with your actual account id.

<script>
window.beOpAsyncInit = function () {
BeOpSDK.init({
account: "YOUR_ACCOUNT_ID",
});
BeOpSDK.watch();
};
</script>
<script async src="https://widget.collectiveaudience.co/sdk.js"></script>

the beOpAsyncInit is where you identify your page using the init() function, and the watch() tells the SDK to look for slots, the script below is the actual SDK, which is loaded asynchronously (meaning it doesn't block your page)

Installing on Wordpress#

It's possible that your Wordpress setup concatenates scripts, which prevents you from running an up-to-date Collective Audience SDK and creates unexpected bugs.

For that, you can use the following SDK:

<script>
(function (window, document, script) {
window.beOpAsyncInit = function () {
BeOpSDK.init({
account: "YOUR_ACCOUNT_ID",
});
BeOpSDK.watch();
};
var firstScript = document.querySelector(script);
var script = document.createElement(script);
script.async = true;
script.src = "https://widget.collectiveaudience.co/sdk.js";
firstScript.parentNode.insertBefore(script, firstScript);
})(window, document, "script");
</script>

Declaring slots#

You can declare slots, or places where widgets should appear by simply putting the following tag where you want them on your pages:

<div class="BeOpWidget"></div>

In order to ensure your slots are correctly filled, we highly recommend naming them, this way if the slot order in your page is altered, the SDK will still be able to identify them.

Example:

<div class="BeOpWidget" data-name="below-article"></div>
<div class="BeOpWidget" data-name="sidebar"></div>
<div class="BeOpWidget" data-name="homepage"></div>

You can specify if a slot is strictly for your own editorial content or for sponsored content too:

<!-- only editorial content -->
<div class="BeOpWidget" data-my-content="1"></div>
<!-- default: accept both (if your account is configured to accept ads) -->
<div class="BeOpWidget"></div>

Browser support#

We support all modern browsers.

Following Microsoft's own products, we've discontinued Internet Explorer support.

Need to check if you installed the SDK correctly?#

Come and check the Diagnostics script!

API Reference#

BeOpSDK.init(config)#

Initialises the SDK with your account.

BeOpSDK.init({
account: "abcdef1234567890abcdef12",
});

  • config.account: your Collective Audience account ID

  • config.canAccessStorage (default: true): set to false to prevent Collective Audience from storing a technical cookie in the absence of a TCF consent platform

  • config.refreshExistingSlots (default: true): set to false if your website loads new articles with an infinite scroll mechanism

  • config.prefillInformations: provide user information to ease the form/optin filling process (useful if your user is logged in on your account).

    You can provide the elements like follows (all keys are optional):

    BeOpSDK.init({
    account: "abcdef1234567890abcdef12",
    prefillInformations: {
    firstName: "Foo",
    lastName: "Bar",
    email: "[email protected]",
    phoneNumber: "+336...",
    },
    });

BeOpSDK.watch()#

Parses and watches the page for available slots.

BeOpSDK.parse()#

Parses the page for tags

caution

Deprecated: use BeOpSDK.watch(), which is reliable even when pages aren't fully loaded or blocked by a longer loading

BeOpSDK.pushEvent(event)#

Send an event to Collective Audience's server.

BeOpSDK.pushEvent({
eventName: "impression",
eventValue: "foo",
slotName: "my-slot",
currency: "EUR",
});

  • event.eventName: the name of the event. For now, only impression is supported

  • event.eventValue: the value of the event. You can pass any string here

  • event.slotName: the name of the slot where the event comes from

  • event.currency (default: Computed from the account owning the slot): the currency of the event. Only EUR and USD are supported for now

Fullsize mode#

You might want to have a Collective Audience slot to take the whole viewport (for instance in a mobile iframe). To that end, you can add a data-expand attribute to make a slot fill the window.

<div class="BeOpWidget" data-expand></div>

If you want to be able to have a close button to appear once the creative is complete, add the following right after the BeOpSDK.init call:

BeOpSDK.onPressClose((slotName) => {
// notify the webview to close itself
});

Optionnally, you can pass a timeout param to trigger the button appearance in case of inactivity (defaults to 10s):

// show the button after a 5s inactivity
BeOpSDK.onPressClose((slotName) => {
/* ... */
}, 5000);

caution

The close button will not appear unless you provide your onPressClose event listener.

SDK API inventory#

This section lists all init parameters and public functions available in the current SDK. Parameters or functions not described in detail above may be documented in other pages or reserved for specific use cases.

BeOpSDK.init(config) – parameters#

ParameterTypeDocumented aboveMore details
accountstring✅Your publisher account ID (use with publisher path).
networkstring—Your network account ID (use with network path). See Network SDK.
networkPartnerIDstring—Optional site/placement identifier for reporting. See Network SDK.
networkPublisherIDstring—Optional per-slot publisher override (network path). See Network SDK.
canAccessStorageboolean✅Default true. Cookie storage in absence of TCF.
refreshExistingSlotsboolean✅Default true. Set false for infinite scroll.
prefillInformationsobject✅firstName, lastName, email, phoneNumber.
pageUrlstring—Override page URL used for content requests (e.g. canonical URL).
onContentReceivefunction—Callback when content is received.
onHeightChangefunction—Callback when widget height changes (e.g. iframe resize).
siteUserIDstring—Optional site-specific user identifier.
waitForTCFboolean—Wait for TCF consent before init. See Consent management.
waitForEIDSboolean—Wait for EIDs before init (default true).
gdprstring—Programmatic GDPR flag (e.g. "0" / "1").
gdprConsentstring—TC string when no CMP is present.
bpsegsarray of string—Publisher first-party segments. See Network SDK (Prebid).
clickUrlPrefixstring—Optional prefix for click URLs.
prebidVersionstring—Prebid version when using header bidding.

Public functions#

FunctionDocumented aboveMore details
BeOpSDK.init(config)✅See API Reference above.
BeOpSDK.watch(rootElement?)✅Parses and watches for slots; triggers content fetch.
BeOpSDK.parse(rootElement?)✅ (deprecated)Use watch() instead.
BeOpSDK.pushEvent(config)✅eventName, eventValue, eventLabel, slotName, currency. Only impression is supported for eventName.
BeOpSDK.onPressClose(callback, timeout?)✅Fullsize mode: close button after creative complete.
BeOpSDK.subscribeToWidgetEvents(callback)—Subscribe to widget-level events (e.g. vote, interaction).
BeOpSDK.getLoginStatus(callback)—Get current login status and user ID (e.g. CrossConnect).

Page keywords (not in init)#

Keywords are not passed in init(). Set window.beOpKeywords (array of strings) before the SDK runs; the SDK reads it at request time and sends it as kwds to the content server. See Identify pages – Page keywords and Retail Media Network – Passing context.