Getting started

Where can I find my Rokt Account ID?

Your Rokt Account ID uniquely identifies your Rokt account when setting up API and SDK integrations, including the Event API and the Web SDK.

To find your Rokt Account ID:

Log in to my.rokt.com.
Look at the URL for your account. Your Account ID is the number immediately following my.rokt.com/accounts/.
- For example given the URL: https://my.rokt.com/accounts/106/campaigns?startDate=2021-08-17T00:00:00.000&endDate=2021-08-24T13:34:28.463&timezone=89&currency=AUD, the Account ID is 106.

Add Rokt to your site

Adding a Rokt placement to your site is the first step for Rokt Ecommerce partners. Placements are flexible iframes that are used to display any type of Rokt campaign.

To set up a placement on your website, you can use the Rokt Web SDK (instructions below). Rokt also offers a range of mobile SDKs to set up placements on native Android, iOS, React Native, and Flutter applications.

Shopify stores can set up a Rokt placement in seconds using the Rokt Ecommerce app — no coding needed!

Single page applications

This guide is meant for websites built as multipage applications. If your site is a single page application, you should follow these instructions.

1. Load Rokt onto your page

Your account manager can provide your integration code, or you can find it in my.rokt.com.

Your integration code includes a customer identifier (we recommend raw email customer address) and contextual data. Read more about why Rokt asks for personal identifiers and contextual attributes.

Sample integration code

Loading the integration

The first step to integrate with Rokt is to load Rokt's Integration Launcher into your site. For the best performance, we encourage you to load Rokt script directly into your HTML head element by adding the following script tag.

Google Tag Manager

If you are using Google Tag Manager, please make sure the document.write field is checked and see the recommended implementation steps.

caution

If you are copying the below example, ensure roktAccountId is replaced with your account's unique ID. See Where can I find my Rokt ID? for instuructions.

<script type="module">
  const target = document.head || document.body;
  const script = document.createElement("script");
  script.type = "text/javascript";
  script.src = "https://apps.rokt.com/wsdk/integrations/launcher.js";
  script.fetchpriority = "high";
  script.crossOrigin = "anonymous";
  script.async = true;
  script.id = "rokt-launcher";
  target.appendChild(script);
  await new Promise((resolve) =>
    window.Rokt
      ? resolve()
      : document
          .getElementById("rokt-launcher")
          .addEventListener("load", () => resolve())
  );

  const launcher = await window.Rokt.createLauncher({
    accountId: "rokt-account-id",
    sandbox: true,
  });
  await launcher.selectPlacements({
    attributes: {
      email: "",
      firstname: "",
      lastname: "",
      mobile: "",
      confirmationref: "",
      amount: "",
      currency: "",
      paymenttype: "",
      ccbin: "",
      zipcode: "",
      country: "",
      language: "",
    },
  });
</script>

You should opt in for one of these methods and ensure it executes only once.

2. Enable the preparative iframe

Choose a page that occurs earlier in the customer journey, ideally where a customer might spend a little more time. A shipping or payment details page works well.

Add this code snippet anywhere in the page HTML:

<iframe
  aria-hidden="true"
  src="https://apps.rokt.com/wsdk/preload/index.html"
  sandbox="allow-scripts allow-same-origin"
  style="border: 0px; width: 100%; display: none;"
></iframe>

This snippet will load and cache Rokt assets earlier in the customer journey. Then when you are ready to show a Rokt placement, Rokt assets will be ready to go, resulting in a faster load time. Rokt’s preparative iframe is secure, and has no access to your page or site data.

You can read more about the benefits of the preparative iframe here.

3. Add the Rokt integration code to your site

Add the Rokt integration code from Step 1 between the HTML <head></head> tags of any page where you want to display a Rokt placement.

When you add the integration code to your page, make sure to populate customer and transactional data. Make sure you configure customer email address so that Rokt can identify customers and choose a relevant offer.

Populate any contextual attributes about the transaction to help Rokt better personalize what offers the customer sees.

note

Rokt recommends a direct integration as a best practice, but the option to integrate with a tag manager is available.

4. Set up pages and placements

The Rokt team will set up relevant pages and placements for you in One Platform. We can customize your placement to match your brand guidelines and UX needs.

Embedded placements

If you are planning to add an embedded placement to your site, you need to specify the HTML element that the placement should be anchored to. For example: <div id="rokt-placeholder"></div>. Let the Rokt team know what element the placement should target.

5. Test your integration

Ensure that the Rokt Web SDK is loading on the right page and includes the correct attributes.

Read our guide on testing your integration.

More information

Native mobile app integrations

Add a Rokt placement to your iOS, Android, React Native, or Flutter mobile applications.

Report conversions

Setting up automatic conversion reporting helps Rokt Ads clients measure the impact of your campaigns on your business. Rokt offers a variety of ways to integrate your conversion data. For greatest accuracy, we recommend using the Rokt Web SDK or Event API. The instructions for each method are listed below.

Though less accurate, we also support conversion reporting through third-party measurement tools, file transfer, and manual upload.

No-code conversion reporting

Shopify store owners can install the Rokt Ecommerce app with one click to start reporting conversion data. Contact your account manager if you'd like to explore the Shopify option.

Web SDK

The Rokt Web SDK is a JavaScript library that lets you automatically report conversions from the frontend of your website.

Add the Rokt Web SDK

Get your unique integration code from your Rokt account manager, or generate it yourself in my.rokt.com.
1. Log-on to my.rokt.com.
2. Click your account.
3. Click Integrations.
4. Click Integrations.
5. Click Set up the Snippet.
6. Select Record conversions.
7. Choose a customer identifier so that Rokt can correctly match campaign events to conversions. We recommend using raw or hashed (SHA-256) customer email address as an identifier.
  note
  As an alternative to hashed or raw email, you can use the Rokt Tracking ID (passbackconversiontrackingid) as an identifier. This method takes more work from your development team, but doesn’t require any personally identifiable information.
8. Add relevant contextual attributes. Contextual data helps Rokt learn more about what campaigns and audiences are most effective for your business. We use these learnings to optimize for acquisition and help your campaigns perform better in the future.
  Your integration code will look something like this:

<script type="module">
  const target = document.head || document.body;
  const script = document.createElement("script");
  script.type = "text/javascript";
  script.src = "https://apps.rokt.com/wsdk/integrations/launcher.js";
  script.fetchpriority = "high";
  script.crossOrigin = "anonymous";
  script.async = true;
  script.id = "rokt-launcher";
  target.appendChild(script);
  await new Promise((resolve) =>
    window.Rokt
      ? resolve()
      : document
          .getElementById("rokt-launcher")
          .addEventListener("load", () => resolve())
  );

  const launcher = await window.Rokt.createLauncher({
    accountId: "roktAccountId",
  });

  await launcher.selectPlacements({
    attributes: {
      //customer identifier - at least one required
      email: "john.smith@gmail.com",
      emailsha256: "",
      passbackconversiontrackingid: "",

      //recommended contextual attributes
      firstname: "",
      lastname: "",
      conversiontype: "",
      amount: "",
      currency: "",
      quantity: "",
      paymenttype: "",
      margin: "",
      confirmationref: "",
    },
  });
</script>

The explanation of the various parts of the code example can be found in Web SDK Library documentation.

caution

If you are copying the above example, ensure roktAccountId is replaced with your account's unique ID before continuing to the next step. You can get your roktAccountId from your account manager or from my.rokt.com.

Add the integration code to your confirmation page.
1. You should place the integration code on any page that immediately follows a conversion event, typically a confirmation or thank you page. Paste the integration code directly into the HTML on the page, between the <head></head> tags.
2. Ensure that the integration records all conversions on your site. Rokt can then handle the attribution process to determine what conversions resulted from a Rokt campaign event.
  Tag managers
  You can add the Rokt integration code to your site using a tag manager, but it may result in reduced performance due to some conversion events being dropped. For best results, we recommend the direct integration described on this page.
Populate your data attributes. Ensure that at least your customer identifier (email or Rokt Tracking ID) is populated with the correct data. Also configure any contextual attributes.
1. If you want to use hashed email address as an identifier, you can use Rokt’s pre-built hashing function. You can find additional information on the Two Step Data Integration page.
Test that the integration is engaging and contains the correct data. View testing instructions.

For optimal performance, consider integrating both the Event API and Web SDK. Using both methods creates redundancy and helps identify any anomalies that may occur in the browser or on your server.

Event API

The Event API offers another options for advertisers looking to integrate conversion data with Rokt. Using the Event API, your backend server can securely connect to Rokt's, transmitting conversion data in real time.

Using the Event API as a standalone integration for conversion data provides multiple benefits:

Speed: Enables a fully automated, near-real time data exchange, maximizing the potential of Rokt’s automated optimization tools.
Coverage: Permits integration of events across all channels and devices, resulting in coverage for conversions across web, mobile, and in-store.
Reliability: As a server-to-server integration, the Event API is not susceptible to any interference by web technologies such as browser or ad blocking. It also supports error handling, ensuring that data is never lost.

Add the Event API

Make sure you can log in to Rokt's my.rokt.com and obtain your Account ID. If you don't have an account, reach out to your account manager.
Get your App ID and App Secret from my.rokt.com. You need this information in order to authenticate the Event API. View steps to retrieve your credentials.
Assemble your payload for the Event API. You can use the POST /v1/events endpoint to send any type of conversion event to Rokt.
1. For this use case, always set eventType to conversion so that Rokt knows to trigger the conversion attribution process.
2. Include relevant key-value pairs in the objectData. Providing relevant contextual data helps Rokt better optimize your campaigns in the future.
  Rokt requires at least one of email (email), SHA-256 hashed email (emailsha256), or Rokt Tracking ID (passbackconversiontrackingid) so that Rokt can identify the customer. Suggested objectData fields are available in the table below.
Full endpoint reference
View full reference details for the Event API.

Sample

POST /v1/events
{
    "accountId": "12345",
    "events": [
        {
            "clientEventId": "ff3bd69c-ca74-4337-af91-4d5d0bd00e38",
            "eventTime": "2020-05-22T10:21:29.339Z",
            "eventType": "conversion",
            "objectData": [
                {
                    "name": "email",
                    "value": "email123@emailserver.com"
                },
                {
                    "name": "transactionid",
                    "value": "123456789"
                },
                {
                    "name": "amount",
                    "value": "99.80"
                },
                  {
                    "name": "currency",
                    "value": "USD"
                },
                {
                    "name": "quantity",
                    "value": "2"
                },
                {
                    "name": "conversiontype",
                    "value": "hotel_booking"
                },
                {
                    "name": "margin",
                    "value": "10"
                },
            ]
        }
    ]

Suggested `objectData` fields

The objectData object is made up of key-value pairs that contain metadata about the event. In order to properly attribute conversions, you must include one of email (email), SHA-256 hashed email (emailsha256), or Rokt Tracking ID (passbackconversiontrackingid) in objectData so that Rokt can identify the customer.

For the conversion reporting use case, we recommend you include the following attributes.

Field name	Description	Example
`email`	Email passed as plain text, lowercase and without trailing spaces	`john@email.com`
`emailsha256`	SHA256 hash of email address. Prior to hashing, lowercase and without trailing spaces.	`fab1e2e699b3b927cbf875046a64f222` `5df02d5cb306f3857424c2bbb87be61f`
`passbackconversiontrackingid`	Also known as Rokt Tracking ID. A Rokt-generated ID used to match conversion events to the originating click. Requires a separate integration.	`1bc29b36f623ba82aaf6724fd3b16718`
`amount`	Value of the transaction (allows decimal points)	`100.25`
`currency`	Currency code	`USD`
`quantity`	The quantity (integer) of item within the specific conversion	`4`
`conversiontype`	Used to differentiate between different conversion events. Note: Only applicable if the default conversion event type is provided.	`ticketpurchase`, `seatupgrade` `signup`
`productname`	The name of the product(s) purchased. You can separate multiple items with a comma.	`Maroon 5 t-shirt, Warriors vs. Raptors`
`sku`	The identifier of the product purchased (Note: Only accepts one SKU)	`230847`, `tshirt-blue-39487`, `398fhdnff`
`paymenttype`	The payment method used during the transaction	`VISA`, `American Express`
`margin`	Profit margin of conversion	`10`
`transactionid`	Transaction ID, used to identify a unique transaction. Note: If provided, Rokt uses this identifier to deduplicate conversion events across channels.	`ABC789`
`confirmationref`	Confirmation reference ID. Alternate identifier that may be used to identify a unique transaction and/or track order confirmations. Note: If provided, Rokt uses this identifier to deduplicate conversion events and `transactionid` is unavailable.	`XYZ123`
`firstname`	Customer's first name	`John`
`lastname`	Customer's last name	`Smith`
`mobile`	Mobile phone number of converting customer	`3053211654`, `+1 (323) 867-5309`
`ipaddress`	Customer's IP address	`172.3.51.182`

Custom attributes

Rokt has a data mapping system that allows us to map provided field names to our internal data fields, however we have some recommended field names and formatting requirements later in this article. If you would like to use alternate field names, let us know, and we will ensure your fields are managed accordingly. Additionally, we can accept any additional fields if you would like to provide them for reporting purposes.

Premium integration: Combining the Web SDK and Event API

If possible, we recommend setting up conversion reporting through both the Web SDK and Event API. This helps identify any anomalies and provides redundancy if there are any issues on the frontend or backend.

If you choose to set up both integrations, ensure you populate one of transactionid or confirmationref in both the Web SDK and Event API integrations. Rokt can then deduplicate incoming your conversion events using these variables, ensuring your reporting is accurate.

Integrating your cart with Rokt

Subscribe to Rokt placement cart changes

The in-transaction/cart integration notifies your frontend whenever a customer selects a Rokt upsell opportunity, allowing for the change to be reflected in a customer's cart. This is achieved by listening to the V2_CART_ITEM_UPDATED message of a placement, which is triggered every time a customer makes changes to selected items on the Rokt side.

You can subscribe to that message by using the Selection.on method which allows you to listen for messages from any selected placement. The payload of those messages is described in UpdateCartItemPlacementMessageBody.

Additionally, you can provide extra information by passing attributes to better tailor an offers' selection to a customer. In some cases, depending on your catalog provider, additional information may be required for Rokt to retrieve catalog items.

// (...) loading Rokt script and creating Integration Launcher instance

const selection = await launcher.selectPlacements({
  attributes: {
    // attributes required by Rokt to retrieve the catalog items
    eventId: "eventId",
    venueName: "venueName",
    // any additional attributes
    email: "email",
  },
});

selection.on("V2_CART_ITEM_UPDATED").subscribe((event) => {
  // Below you should provide your code to reflect changes to your cart
  clientCart.updateCart(event.body.cartItem, event.body.oldCartItem);
});

Update Rokt placement cart from your cart

In the scenario where your cart changes need to be reflected on the Rokt side, you can send messages to the Placement to do so. For your convenience, you can send a message to each placement in selection by using the Selection.send method. The affected Rokt placement will listen and action accordingly. The payload of this message is described in UpdateCartItemPartnerMessageBody.

note

Please be advised that certain changes will not be performed if the configuration does not allow it. For instance, if a forced upsell has a minimum quantity of 1, and the placement receives a message from the partner to remove that selection, the placement will not action it.

Be sure though, there is always a message sent back to the partner from the placement, to close the loop and share the Rokt placement cart state to the partner, to ensure both carts are aligned (please see section above).

const selection = await launcher.selectPlacements({
  attributes: {
    // attributes required by Rokt to retrieve the catalog items
  },
});

selection.send("V2_UPDATE_CART_ITEM", payload);

Checking placement availability

This extension involves your backend issuing a call to Rokt to check if any placements are available. You can then decide if your upsell page should be displayed or skipped. In this scenario, your pages have most likely already been generated on the backend, and you have already included customer and transaction data to Rokt in the initial call. Since that call may have already generated your session ID, the Rokt JavaScript API requires you to include your session ID in the Rokt.createLauncher method so both interactions can be paired together for identification and performance reasons.

// (...) loading Rokt script

const launcher = await Rokt.createLauncher({
  accountId: "roktAccountId",
  sessionId: "uniqueSessionId", // session ID generated by Rokt backend
});

// (...) the rest of the integration logic

Checking placement is valid

Some Rokt offers contain fields the customer must complete before moving on in the transaction flow. An example of this is filling out a form or selecting yes/no on an offer.

These types of offers contain validation messaging that displays a warning to the customer indicating the action they must take before proceeding.

The behavior is optional and needs to be enabled through IntegrationLauncher.use() method before making a selection. Once the partner validation module is obtained you can check if the current placements are valid using the getValidationStatus method. The method 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

const partnerValidation = await launcher.use('PartnerValidation');

const selection = await launcher.selectPlacements({
    attributes: {
        /* ... */
    },
});

// When the customer clicks this button, you check the validation status of the placements
document.querySelector("button.check-validation").onclick = async () => {
  await selection.ready();  
  const result = await partnerValidation.getValidationStatus();

  // Quickly determine if the placements contain an invalid placement
  console.log(result.isValid);

    // Loop through
  for (const placement of result.placements) {
    console.log(
      "element is: " +
        element.getBoundingClientRect().top +
        "px from the top of the page"
    );
    console.log("placement has: " + placement.errors.length + " errors");

    for (const [i, error] of placement.errors.entries()) {
      console.log("placement error: " + i + " is " + error);
    }
  }
};

Detecting anomolies for partners

For Rokt Ecommerce partners, placement performance makes up a key component of the ecommerce experience, providing value to your customers and generating significant value for your bottom line. Ensuring the Rokt placement is displayed as often as expected is key to maximizing the value Rokt can deliver.

Technical integrations, such as Rokt’s Web SDK, iOS SDK, or Android SDK, can be impacted by small changes to the many moving parts in the ecosystem including website updates, third-party integrations (e.g., tag managers and optimization systems), customer-installed applications (e.g., browser extensions), or even new browser versions. The severity of the impact can range significantly depending on the type of change, but even small errors affecting a tiny percentage of sessions can have significant impacts to customers—as well as the bottom line—if they linger undetected.

By default, Rokt uses a range of tools, alerts, and reporting to track these types of issues. For example, all deployments are set up with automated alarming on major drops in placement impressions. However, small deviations from the norm may be perceived as noise, so smaller errors (e.g., an error affecting some versions of Safari) may go unnoticed. To get the most accurate picture of performance, we need a trusted secondary data source that is independent of browser functionality. This secondary data source allows Rokt to run comparisons between actual placement impressions and events where a placement should have been displayed. When this data is made available, discrepancies can be quickly identified, diagnosed, and fixed.

Anomaly detection involves setting up both the Rokt Web SDK along with the Event API. While the Web SDK is integrated into your frontend, the Event API talks to your backend systems, providing a server-to-server version of the truth.

Before you begin

Follow the steps to add the Rokt Web SDK to your site.

Make sure you can log in to my.rokt.com and obtain your Account ID. If you don't have an account, reach out to your account manager.
Get your App ID and App Secret from my.rokt.com. You need this information in order to authenticate the Event API. View steps to retrieve your credentials.
Assemble your payload for the Event API. You can use the POST /v1/events endpoint to send any type of conversion event to Rokt.
1. Include relevant key-value pairs in the objectData. Providing details about the customer device, browser, and operating system helps Rokt troubleshoot any anomalies that might appear. Suggested objectData fields are available in the table below.

Full endpoint reference

View full reference details for the Event API.

Sample

POST /v1/events
{
    "accountId": "12345",
    "events": [
        {
            "clientEventId": "ff3bd69c-ca74-4337-af91-4d5d0bd00e38",
            "eventTime": "2020-05-22T10:21:29.339Z",
            "eventType": "transaction",
            "objectData": [
                {
                    "name": "email",
                    "value": "email123@emailserver.com"
                },
                {
                    "name": "transactionid",
                    "value": "123456789"
                },
                {
                    "name": "ipaddress",
                    "value": "172.3.51.182"
                },
                {
                    "name": "DeviceType",
                    "value": "Mobile"
                },
                {
                    "name": "os",
                    "value": "iOS"
                },
                {
                    "name": "osversion",
                    "value": "14.5"
                },
                {
                    "name": "browser",
                    "value": "Safari"
                },
                {
                    "name": "browserversion",
                    "value": "11.1"
                }
            ]
        }
    ]

Suggested `objectData` fields

Field name	Description	Example
`email`	Email passed as plain text, lowercase and without trailing spaces	`john@email.com`
`transactionid`	Transaction ID, used to identify a unique transaction. Note: If provided, Rokt uses this identifier to deduplicate conversion events across channels.	`ABC789`
`confirmationref`	Confirmation reference ID. Alternate identifier that may be used to identify a unique transaction and/or track order confirmations. Note: If provided, Rokt uses this identifier to deduplicate conversion events and `transactionid` is unavailable.	`XYZ123`
`ipaddress`	Customer's IP address	`172.3.51.182`
`useragent`	Browser user agent of converting customer	`Mozilla/5.0 (Windows NT 6.1; Win64;x64; rv:47.0) Gecko/20100101 Firefox/47.0`
`DeviceType`	Type of device	`Desktop` `Mobile` `Tablet`
`os`	Device operating system	`iOS`
`osversion`	Operating system version	`8.1`
`browser`	Browser	`Safari`
`browserversion`	Browser version	`11.1`

Where can I find my Rokt Account ID?​

Add Rokt to your site​

1. Load Rokt onto your page​

Sample integration code​

Loading the integration​

2. Enable the preparative iframe​

3. Add the Rokt integration code to your site​

4. Set up pages and placements​

Embedded placements​

5. Test your integration​

More information​

Report conversions​

Web SDK​

Add the Rokt Web SDK​

Event API​

Add the Event API​

Sample​

Suggested objectData fields​

Custom attributes​

Premium integration: Combining the Web SDK and Event API​

Integrating your cart with Rokt​

Subscribe to Rokt placement cart changes​

Update Rokt placement cart from your cart​

Checking placement availability​

Checking placement is valid​

Detecting anomolies for partners​

Before you begin​

Sample​

Suggested objectData fields​

Custom attributes​

Where can I find my Rokt Account ID?

Add Rokt to your site

1. Load Rokt onto your page

Sample integration code

Loading the integration

2. Enable the preparative iframe

3. Add the Rokt integration code to your site

4. Set up pages and placements

Embedded placements

5. Test your integration

More information

Report conversions

Web SDK

Add the Rokt Web SDK

Event API

Add the Event API

Sample

Suggested `objectData` fields

Custom attributes

Premium integration: Combining the Web SDK and Event API

Integrating your cart with Rokt

Subscribe to Rokt placement cart changes

Update Rokt placement cart from your cart

Checking placement availability

Checking placement is valid

Detecting anomolies for partners

Before you begin

Sample

Suggested `objectData` fields

Custom attributes