Last updated

Adobe Experience Platform Integration for Advertisers

This page explains how to implement Rokt Ads using Adobe Experience Platform to close the loop by linking conversions back to your campaigns. By linking conversions back to your Ads engagement, you can enable more accurate attribution, real-time optimization, and campaign measurement.

You'll learn how to create data elements in Adobe based on your data layer, and how to create rules to initialize the Rokt SDK and log conversions.

Create your Rules

Initialize the Rokt SDK

1. Sign in to Adobe Experience Platform.
2. From a property's overview page, open the Rules tab and choose Add Rule.
3. Give your Rule a descriptive name, such as Rokt Initialization, and create your Event to make the rule fire.
   • Every site is different, but Rokt recommends including the SDK script on every page. This ensures the lowest offer delivery latency and the highest user identification accuracy.
4. Create your Action and choose Core as the Extension and Custom Code as the Action Type.
5. Choose HTML as the language and paste the following snippet:

<script>
// Enter your Rokt API key
const API_KEY = "YOUR_API_KEY";

// If you configured a first-party domain, set it as the value of DOMAIN instead of the default apps.rokt-api domain
const ROKT_DOMAIN = "https://apps.rokt-api.com";

// Set your SDK configuration settings
window.mParticle = {
    config: {
        // Specify the data environment with isDevelopmentMode:
        // Set isDevelopmentMode to true if you are still testing your integration.
        // Set isDevelopmentMode to false if your integration is ready for production data.
        isDevelopmentMode: true,
        // Identify the current user:
        // If you have the user's email address, include it in an object called `userIdentities` within `identifyRequest` as shown below.
        identifyRequest: {
            userIdentities: {
                // Make sure to replace the sample variable {email} with the variable you create to store your user's email
                email: _satellite.getVar('email'),
                // Hashed email addresses should be passed into the `other` field
                other: _satellite.getVar('hashed_email')
            },
        }
    },
};

// Load the SDK
(function(e) { window.mParticle = window.mParticle || {}; window.mParticle.EventType = { Unknown: 0, Navigation: 1, Location: 2, Search: 3, Transaction: 4, UserContent: 5, UserPreference: 6, Social: 7, Other: 8, Media: 9 }; window.mParticle.eCommerce = { Cart: {} }; window.mParticle.Identity = {}; window.mParticle.Rokt = {}; window.mParticle.config = window.mParticle.config || {}; window.mParticle.config.rq = []; window.mParticle.config.snippetVersion = 2.6; window.mParticle.ready = function(e) { window.mParticle.config.rq.push(e); }; ["endSession", "logError", "logBaseEvent", "logEvent", "logForm", "logLink", "logPageView", "setSessionAttribute", "setAppName", "setAppVersion", "setOptOut", "setPosition", "startNewSession", "startTrackingLocation", "stopTrackingLocation"].forEach(function(e) { window.mParticle[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift(e); window.mParticle.config.rq.push(t); }; }); ["setCurrencyCode", "logCheckout"].forEach(function(e) { window.mParticle.eCommerce[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("eCommerce." + e); window.mParticle.config.rq.push(t); }; }); ["identify", "login", "logout", "modify"].forEach(function(e) { window.mParticle.Identity[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("Identity." + e); window.mParticle.config.rq.push(t); }; }); ["selectPlacements","hashAttributes","setExtensionData"].forEach(function(e) { window.mParticle.Rokt[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("Rokt." + e); window.mParticle.config.rq.push(t); }; }); var t = window.mParticle.config.isDevelopmentMode ? 1 : 0, n = "?env=" + t, a = window.mParticle.config.dataPlan; if (a) { var o = a.planId, r = a.planVersion; o && (r && (r < 1 || r > 1e3) && (r = null), n += "&plan_id=" + o + (r ? "&plan_version=" + r : "")); } var i = window.mParticle.config.versions, s = []; i && Object.keys(i).forEach(function(e) { s.push(e + "=" + i[e]); }); var c = document.createElement("script"); c.type = "text/javascript"; c.async = !0; window.ROKT_DOMAIN = ROKT_DOMAIN || 'https://apps.rokt-api.com'; mParticle.config.domain = ROKT_DOMAIN.split('//')[1]; c.src = ROKT_DOMAIN + "/js/v2/" + e + "/app.js" + n + "&" + s.join("&"); var l = document.getElementsByTagName("script")[0]; l.parentNode.insertBefore(c, l); })(API_KEY);
</script>

6. Enter your configuration settings:
   • Replace YOUR_API_KEY with the API key provided to you by your Rokt account manager.
   • If you set up a custom domain for a first party domain integration, replace https://apps.rokt-api.com with your new domain.
   • If you are ready to use your tag for production data, set isDevelopmentMode to false. Leave this set to true if you are still testing your tag.
   • Make sure email is set to the data element you created to store your user's unhashed email address. In the example snippet above, you can access your data element using _satellite.getVar('email').
7. Click Keep Changes in the Action Configuration and Save.

Identify the user

You should also create a Rule that identifies the current user to Rokt. Make sure to include this Rule in your site so it is fired as soon as the user provides their email address.

1. From a property's overview page, open the Rules tab and choose Add Rule.
2. Give your Rule a descriptive name, such as Rokt Identify, and create your Event to make the rule fire.
   • Configure an Event so that this Rule is fired as soon as a user provides their email address. The Event you use will depend on your specific integration.

attention

The exact Event configuration you use for the Identify User Rule will depend on your integration. If you have questions about how best to implement this Rule so that your users are successfully identified before logging events, speak to your Rokt Account manager.

3. Create your Action and choose Core as the Extension and Custom Code as the Action Type.
4. Choose HTML as the language and paste the following snippet:

<script>
const identifyRequest = {
    userIdentities: {
        // If you're using a raw, un-hashed email, pass it into the `email` field
        email: _satellite.getVar('email'),
        // If you're using a hashed email, pass it into the `other` field
        other: _satellite.getVar('hashed_email')
    }
};
window.mParticle.Identity.identify(identifyRequest);
</script>

5. If you are sending the user's raw, unhashed email address to Rokt, set it to email. If you are sending the hashed email address, set it to other. Make sure to replace the example variable names (email and hashed-email) with the Data Element name you created to store your user's email address.
6. Click Keep Changes in the Action Configuration and Save.

Track Page Views

Advertisers should track views for each page through the conversion funnel by adding a Page View rule as soon as possible when each page is loaded.

1. From a property's overview page, open the Rules tab and choose Add Rule.
2. Give your Rule a descriptive name, such as Rokt Page View, and create your Event to make the rule fire.
   • Configure an Event so that this Rule is fired as soon as each page loads. The Event you use will depend on your specific integration.

attention

The exact Event configuration you use for the Page View Rule will depend on your integration. If you have questions about how best to implement this Rule so that pages are tracked, speak to your Rokt Account manager.

3. Create your Action and choose Core as the Extension and Custom Code as the Action Type.
4. Choose HTML as the language and paste the following snippet:

<script>
window.mParticle.ready(
  function() {
    mParticle.logPageView(
        // Page name
        "page view",
        // An object containing attributes describing the page
        {
            "url": window.location.toString(),
            "product": "Example Product Name",
            // Add any other page specific attributes as key/value pairs
            "custom-attribute-name": "custom-attribute-value"
        }
    );
  }
);
</script>

The web SDK’s logPageView method takes two arguments:

• Page Name: a string for the name of the page being loaded
• Custom Attributes: an object of key/value pairs containing information about the page

The page name field should be set to a generic page name. For example, an ecommerce website could have hundreds of product detail pages. To log these correctly, you should use a generic name (e.g. "Product Detail Page") and then log the url and other attributes of the page as attributes.

Log a conversion

In addition to creating a Rule to initialize the Rokt SDK, Rokt advertiser integrations also require a Rule to log a conversion.

1. From a property's overview page, open the Rules tab and choose Add Rule.

2. Give your Rule a descriptive name, such as Rokt Log Conversion, and create your Event to make the rule fire.

   • The next steps vary depending on whether your site is a multi-page application (MPA) or a single-page application (SPA):

   • Trigger configuration for multi-page applications

     1. Set the Event Type to Core → DOM Ready or Core → Page Bottom.
     2. Under Conditions, add a Core → Path Without Query String or Page URL condition.
     3. Enter a matching rule to identify the page where the tag should fire. For example, if your confirmation page is example.com/cart/payment/confirmation the identifying parameter can be any of cart, payment, or confirmation.

   • Trigger configuration for single page applications

     1. Set the Event Type to Core → History Change.
     2. Under Conditions, add a Core → Page URL condition.
     3. Enter a matching rule to identify the page where the tag should fire. For example, if your confirmation page is example.com/cart/payment/confirmation the identifying parameter can be any of cart, payment, or confirmation.

3. Create your Action and choose Core as the Extension and Custom Code as the Action Type.

4. Choose HTML as the language and paste the following snippet:

<script>
window.mParticle.ready(
  function() {
        var currentUser = mParticle.Identity.getCurrentUser();
        currentUser.setUserAttribute("firstname", _satellite.getVar('first_name'));
        currentUser.setUserAttribute("lastname", _satellite.getVar('last_name'));
        currentUser.setUserAttribute("zipcode", _satellite.getVar('zipcode'));
        currentUser.setUserAttribute("mobile", _satellite.getVar('mobile'));

        mParticle.logEvent(
        "conversion", // The name of the event
        mParticle.EventType.Transaction, // The event type
        {
            "conversiontype": _satellite.getVar('conversiontype'), // Type of conversion
            "confirmationref": _satellite.getVar('confirmationref'), // Transaction ID / Order ID
            "amount": _satellite.getVar('amount'), // Transaction amount e.g. 300.5
            "currency": _satellite.getVar('currency'), // Transaction currency e.g. USD
        }
    );
  }
);
</script>

5. Set each attribute you want to forward to Rokt with the variable you created based on your site's data layer.

attention

Make sure to replace the example attributes in the snippet with your own data elements.

6. Click Keep Changes in the Action Configuration and Save.

Rule Ordering

Adobe Experience Platform does not guarantee rule execution order across different rules, even if they share the same event. To ensure the subsequent events Rules are fired correctly, you can indirectly control sequencing of these rules using a Shared Custom Event.

1. In your Initialization snippet, add the following custom event:

window.dispatchEvent(new Event("roktReady"));

2. In subsequent rules, add an Event with a Custom Event Event Type
3. Set the Event Type to event name you set.
4. Add relevant conditions for your Rule

Setting up the variables in the Adobe Experience Platform

Understanding the data layer

The data layer should have been implemented on your web page by your developers.

A data layer is an object that contains all of the information that you want to share with Adobe Experience Platform's Data Elements. Information such as events or variables can be shared to Adobe via the data layer, and triggers can be set up in Adobe Experience Platform's Data Elements based on the values of variables or based on the specific events.

Adobe recommends using the Adobe Client Data Layer for new or restructured implementations. You are free to use other data layer specifications. Aligning to a consistent data layer that meets your organization’s needs is the most important.

Refer to the Adobe Experience developer guide for comprehensive details on how the data layer works.

Example of a data layer

window.adobeDataLayer = window.adobeDataLayer || [];

window.adobeDataLayer.push({
  email: "jenny.smith@rokt.com",
  user: { firstname: "Jenny", lastname: "Smith" },
  ecommerce: { transaction: { amount: "12.36" } },
  event: "page loaded",
});

Identifying your data elements

Data elements are set up in your Adobe Experience Platform and are matched to the data layer. Refer to the Adobe Experience developer guide for more details about Data elements.

The structure of your data layer on your page affects the data element name in your Adobe Experience Platform. See the following examples. If you use a data collector object as part of your data layer, simply use dot notation in the path to reference the object and property you want to capture into the data element, like _myData.pageName, or adobeDataLayer.pageName, etc.

Example data layer script 1:

window.adobeDataLayer.push({
  email: "jenny.smith@rokt.com",
});

Data layer path name: adobeDataLayer.email

Example data layer script 2:

window.adobeDataLayer.push({
  user: {
    firstname: "Jenny",
  },
});

Data layer path name: adobeDataLayer.user.firstname

Example data layer script 3:

window.adobeDataLayer.push({
  ecommerce: {
    transaction: {
      amount: "12.36",
    },
  },
});

Data layer path name: adobeDataLayer.ecommerce.transaction.amount

remarque

The JavaScript variable data element type treats array references as dots instead of brackets, so referencing the firstname data element as adobeDataLayer.user[0].firstname will not work.

Adding data elements

1. Navigate to the Data Elements tab and choose Add Data Element.
2. Name your variable and choose Core as the extension.
   • Use however your developer stored your values for Data Element Type
   • Use JavaScript Variable for in-memory values (e.g., adobeDataLayer.email)
   • Use Local Storage only if the values are persisted in the browser’s localStorage
3. Enter the path name that matches the variable name in your data layer setup by your developer.

Rokt suggests creating variables for the following attributes:

• email
• firstname
• lastname
• zipcode
• mobile
• conversiontype
• confirmationref
• amount
• currency