Skip to main content

Rokt Snippet (Deprecated)

note

After years of evolving, snippet.js is at the point where it can no longer handle all of our needs. Rokt no longer recommends using this integration for onboarding. Instead, please head over to the new Integration Launcher. Rokt will continue to support snippet.js to accommodate security patches but no other new features will be added.

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",
  "rokt-account-id",
  "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.
  • rokt-account-id— 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.

The Rokt object loads asynchronously so that it doesn't interfere with your page loading. 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.

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.

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

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 show placements to a customer.

In this case, Rokt relies on the partner to trigger the method. This lets us 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;
    }>;
  }>;
}>

Checking placement validity​

Some Rokt offers contain fields that customers must complete before moving on in the transaction flow--such as selecting yes or no on an offer or filling out a form. These types of offers contain validation messages. These messages display warnings to the customer indicating the action they must take before proceeding.

To check if the current placements are valid, use the rokt.getValidationStatus() method. getValidationStatus returns a JavaScript Promise that waits until the placements have resolved their first validation state as defined. The resolved value looks like:

interface PlacementValidationStatus {
  // 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;
    }>;
  }>;
}

Example usage

rokt.onLoaded(function (rokt) {
  rokt.setAttributes({
    /* ... */
  });
  rokt.init({
    /* ... */
  });
  // When the customer clicks this button, you check the validation status of the placements
  document.querySelector("button.check-validation").onclick = async () => {
    const result = await rokt.getValidationStatus();
    // Quickly determine if the placements contain an invalid placement
    alert(result.isValid);
    // Loop through
    for (const placement of result.placements) {
      alert(
        "element is: " +
          element.getBoundingClientRect().top +
          "px from the top of the page"
      );
      alert("placement has: " + placement.errors.length + " errors");
      for (const [i, error] of placement.errors.entries()) {
        alert("placement error: " + i + " is " + error);
      }
    }
  };
});
Was this article helpful?