Skip to main content

Rokt

The Rokt object provides the entry point to integrate with Rokt's solution.

Overview#

The Rokt object provides the entry point to integrate with Rokt solutions. It is available as a global variable under a name specified in your snippet script. Your snippet script should resemble the following:

(function (r, o, k, t, n, e, w, a, _) {  r._ROKT_ = n;  r[n] = r[n] || {    id: t,    h: w,    lc: [],    it: new Date(),    onLoaded: function (c) {      r[n].lc.push(c);    },  };  a = o.createElement("script");  a.type = "text/javascript";  a.async = !0;  a.src = k;  if (e) {    a.integrity = e;    a.crossOrigin = "anonymous";  }  _ = o.getElementsByTagName("script")[0];  _.parentNode.insertBefore(a, _);})(  window,  document,  "https://apps.rokt.com/wsdk/integrations/snippet.js",  "roktAccountid",  "rokt");

Please notice the following important parameters in the arguments list above:

  • https://apps.rokt.com/wsdk/integrations/snippet.js—is the URL pointing to the latest version of the Rokt object.
  • roktAccountid—your unique Rokt Account ID and should be replaced with the correct value.
  • rokt—the name under which this object will be exposed on your window object. In this case it will be accessible using window.rokt or simply rokt.

So as to not interfere with the loading of your page, the Rokt object loads asynchronously. This means that at the time of running the initialization snippet, the full functionality of the Rokt object is not available. Only the Rokt.onLoaded function is immediately available, while the rest of the functionality is added when the Rokt object has been fetched and completely loaded. To receive notification when the integration is ready, you can add a callback function to Rokt.onLoaded.

rokt.onLoaded(function (rokt) {  rokt.setAttributes({    email: "",  });});

Methods#

closeAll#

closeAll(): void

Closes or unloads all placements on a page.

Returns: void


getPlacements#

getPlacements(): Promise‹Array‹Placement››

Returns a list of selected placements.

Returns: Promise‹Array‹Placement››


hashString#

hashString(value: string): Promise‹string›

Convenient method to hash a string using SHA-256.

Since Rokt manipulates the string before hashing, it is recommended to use the provided method instead of implementing on your own.

Parameters:

NameTypeDescription
valuestringstring to hash

Returns: Promise‹string›


init#

init(configuration: Configuration): void

Sets the information that allows Rokt to identify your customer.

see Configuration on details of available parameters.

Parameters:

NameTypeDescription
configurationConfigurationConfiguration object

Returns: void


onFailure#

onFailure(failureCallback: function): void

Accepts a callback which is triggered if the Rokt object fails to load/cannot be displayed correctly.

For example, this scenario can happen if you encounter a very old browser that is not supported by Rokt.

example

rokt.onFailure((reason) => {  // Use this hook to display error or navigate to another page});

Parameters:

failureCallback: function

Callback to be triggered when the Rokt object is ready.

▸ (reason: string): void

Parameters:

NameType
reasonstring

Returns: void


onLoaded#

onLoaded(onLoadedCallback: function): void

Accepts a callback which is triggered once the Rokt object has been loaded and is ready to use. The callback is triggered immediately if the Rokt object is ready.

You can invoke this method multiple times, each time executing a unique callback. Once the Rokt object is ready to integrate, they are executed in the order in which they were executed.

This approach may be useful in the case of single page applications that have multiple integration points.

example

rokt.onLoaded((rokt) => {  // Now you can interact with Rokt object});

Parameters:

onLoadedCallback: function

Callback to be triggered when the Rokt object has been loaded.

▸ (rokt: Rokt): void

Parameters:

NameType
roktRokt

Returns: void


setAttributes#

setAttributes(attributes: Attributes): void

Sets the attributes that allow Rokt to better tailor an offer to a customer. Attributes may include email, first name, last name, etc.

Depending on your catalog provider, additional information may be required by Rokt to retrieve catalog items. For example, eventId is required for ticketing events.

Rokt.setAttributes performs a shallow merge of passed attributes into the existing attributes.

Since Rokt requires browser user agent as an attribute, the value is stored in the userAgent property by default.

default

{  userAgent: 'Mozilla/5.0 (...)', // window.navigator.userAgent value}

Parameters:

NameTypeDescription
attributesAttributesDictionary with data such as first name, last name, email, etc.

Returns: void


setFulfillmentAttributes#

setFulfillmentAttributes(attributes: Attributes): void

Sets attributes that remain unknown by Rokt until the customer accepts an offer.

Rokt.setFulfillmentAttributes performs a shallow merge of passed attributes into the existing attributes.

Parameters:

NameTypeDescription
attributesAttributesDictionary with data such as first name, last name, email, etc.

Returns: void


triggerPageChange#

triggerPageChange(options: TriggerPageChangeOptions): void

Re-triggers placement selection for a new page.

For single page application integrations, Rokt's solution may be displayed on multiple pages or loaded on a page which does not initially shows placements to a customer.

In this case, Rokt relies on the partner to trigger the method to let Rokt know when a customer reaches the page where we need to display placements.

Parameters:

NameTypeDescription
optionsTriggerPageChangeOptionsOptions for new page.

Returns: void


getValidationStatus#

getValidationStatus(): Promise‹ValidationResult›

Method to determine if the visible placements are valid.

Will return a list of placements with their current validation statuses and references to the relevant iframe elements.

Returns:

Promise<{  // Allows you to quickly determine if there are any errors  isValid: boolean;  // This is the list of placements with validation  placements: Array<{    // This is the element of the placement containing an error,    // allowing you to scroll to it if an error is present    element: HTMLIFrameElement;    // Placements will show their error own messages but this is an    // array that provides you with the error messages should you    // want to repeat them somewhere. It will be empty if valid    errors: Array<{      message: string;    }>;  }>;}>
Was this article helpful?