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¤cy=AUD
, the Account ID is 106.
- For example given the URL:
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!
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.
If you are using Google Tag Manager, please make sure the document.write field is checked and see the recommended implementation steps.
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.
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
- General Web SDK reference
- Web SDK security
- Two-step data integration
- Encrypting attributes in transit
- Single page application 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.
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.
Log-on to my.rokt.com.
Click your account.
Click Integrations.
Click Integrations.
Click Set up the Snippet.
Select Record conversions.
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.
noteAs 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.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.
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.
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.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 managersYou 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.
- 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.For this use case, always set
eventType
toconversion
so that Rokt knows to trigger the conversion attribution process.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. SuggestedobjectData
fields are available in the table below.
Full endpoint referenceView 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.
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.- 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. SuggestedobjectData
fields are available in the table below.
- Include relevant key-value pairs in the
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 |
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.