Integration guide for E-commerce Platforms

This guide is intended for e-commerce Platforms that are interested in automating the configuration of AdRoll for their customers. In this guide, you’ll learn how to use the AdRoll API to access your store owner’s AdRoll account and place their AdRoll Pixel. Properly placing the AdRoll Pixel is a big hurdle for non-technical users and must be done properly to ensure optimal performance. High performing campaigns means more sales for your stores.

If you’re interested in partnering with us, send us a note. If you have any API questions, you can contact the API team.

Get to know the AdRoll API

Before you start building your integration, it helps to have a basic understanding of AdRoll and the AdRoll API:

Get Started with the AdRoll API will help you make your first API call.

Get to know AdRoll provides an overview of the AdRoll object structure and defines common terminology.

Overview

For every store that wants to setup AdRoll, you’ll need to do the following steps:

  1. Connect to AdRoll using OAuth
  2. Retrieve the Pixel
  3. Place the Pixel
  4. Link to Onboarding Flow on AdRoll

If the user wants to disconnect AdRoll from their store, you can simplify remove the AdRoll Pixel from their website.

Connect to AdRoll using OAuth

AdRoll uses OAuth 2.0 to allow users to grant you access to their accounts. Our OAuth 2.0 implementation works with most OAuth 2.0 libraries. We recommend using the Authorization Code Grant.

For the technical details see Get Started with OAuth 2.0.

Retrieve the Pixel

The AdRoll Pixel is a JavaScript snippet that you place on every page of the store’s website.

To retrieve a Pixel:

  1. Call GET /api/v1/organization/get_advertisables to retrieve the list of Advertisables (there should be only one at this point). You’ll need the value of the eid field for the next step
  2. Call GET /api/v1/advertisable/get_pixel and specify the advertisable parameter.

The code field of the returned JSON object will contain the HTML to embed on the user’s website. The HTML snippet consists of a <script> tag containing JavaScript for the AdRoll Pixel. The returned HTML contains HTML entities, so you’ll need to decode the HTML entities before rendering.

Place the Pixel

The AdRoll Pixel should be place on every page of the store’s website. If you have cart and checkout pages on separate domains, be sure to render the store’s Pixel there as well. The Pixel loads asynchronously so it won’t affect the page load time.

Within the rendered HTML page, we recommend placing the AdRoll Pixel just before the closing body tag (</body>).

In addition to placing the Pixel code, we recommend providing additional information to the Pixel:

Enhanced Conversion Tracking

Optional

When recording a conversion (aka purchase), AdRoll allows you to pass information about the order such as the order value, currency, and order ID.

To record the order value and currency, set the adroll_conversion_value and adroll_currency variables.

To save custom attributes for the order, use the adroll_custom_data object. The keys in adroll_custom_data are user-defined. Everything you provide is made available to users in their Granular Conversion Reports.

For example:

<script type="text/javascript">
  adroll_conversion_value = 1337.21;
  adroll_currency = "USD";
  adroll_custom_data = {"ORDER_ID": "W", "USER_ID": "Z"};
</script>

In addition to sending this data via the AdRoll Pixel, users will need to setup a conversion segment for the page that this code is rendered on. You should tell the user which URLs to setup as conversion segments when you Link to Onboarding Flow on AdRoll.

See also:

Cross Device Targeting

Optional

AdRoll can recognize visitors across devices. When you provide a cross-device ID to AdRoll, ads will display on other devices that your visitors use.

To enable cross-device targeting, set adroll_email, adroll_user_identifier, or both when calling the AdRoll Pixel.

The value of adroll_email is the plaintext or MD5 hashed email address for the user (if you have one).

The value of adroll_user_identifier is your custom identifier for the user (if you have one).

For example:

<script type="text/javascript">
  adroll_email = "test@example.com";
  adroll_user_identifier = "C9470D4D067EF94A7721BA";
</script>

Conclusion

That’s all that’s needed for a basic setup. This gets users over the first hurdle of Pixel placement that is often done wrong when placed manually.

A deeper integration would automatically setup conversion Audiences and product feed of their store items. If that sounds interesting to you, send us a note about partnering.