Integration guide for E-commerce Platforms

This guide is intended for e-commerce platforms that are interested in automating the setup for their users. In this guide, you’ll learn how to use the NextRoll API to access your store owner’s account and place their Pixel. Properly placing the Pixel can be a hurdle for users and must be done properly to ensure optimal performance. High performing campaigns means more revenue for your platform.

Get to know the NextRoll API

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

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

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

Overview

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

  1. Connect using OAuth

  2. Retrieve the Pixel

  3. Place the Pixel

  4. Link to Onboarding Flow

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

Connect using OAuth

The NextRoll API 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 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 Pixel. The returned HTML contains HTML entities, so you’ll need to decode the HTML entities before rendering.

Place the Pixel

The 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 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), we allow 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 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.

See also: Setting Up Enhanced Conversion Tracking.

Cross Device Targeting

Optional

We can recognize visitors across devices. When you provide a cross-device ID to us, 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 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.