Integration Guide for Marketplaces

We use the term Marketplace loosely to mean a service provider that hosts multiple businesses that want to advertise independent of each other. The campaigns would target subsets of the overall users to the marketplace’s website. Reporting is specific to each business rather than aggregate for the entire website.

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.

Terms

We’ll make references to the following terms that are specific to this guide:

Marketplace
A service provider that hosts multiple businesses that want to advertise independent of each other
Merchant
A business that participates in the Marketplace that will advertise independent of other businesses
Master Advertisable
Advertisable that owns the Pixel that is placed on the Marketplace’s website
Merchant Advertisable
Advertisable that belongs to a merchant

Overview

A single Organization contains all of your Advertisables. There is a Master Advertisable that owns the AdRoll Pixel. This Pixel is placed on your site and you identify which merchant a page view belongs to. When you on-board a merchant, you will create a new Advertisable for them.

If this setup doesn’t quite match your needs, one of the Variations might. We’re also happy to chat about your needs.

To begin, you’ll do some initial setup:

  1. Organization Setup
  2. Pixel Setup

After that, merchants will go through the following life cycle:

  1. On-board a Merchant
  2. Strategy Management
  3. Off-board a Merchant

Organization Setup

An Organization is automatically created for you when you create an AdRoll account. An initial Advertisable will also be automatically created. This first Advertisable will serve as your Master Advertisable.

You’ll need to your Organization EID when creating Advertisables. This can be found in the eid field returned by GET /api/v1/organization/get.

Pixel Setup

The AdRoll Pixel is a snippet of JavaScript that you place on all of your web pages. The Pixel can be configured by setting JavaScript variables.

For most AdRoll users, they will install a Pixel for each Advertisable on each of their websites. However, since Marketplaces operate on a single website, we’ll install one Pixel from the Master Advertisable. We’ll then use Marketplace Mappings to differentiate between different merchants.

You can retrieve the Pixel in one of two ways:

  1. Copy the Pixel from the AdRoll Dashboard
  2. Use the AdRolll API

To retrieve the Pixel using the API:

  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 Pixel is placed on your site. If each merchant has their own website, see the Web Site per Merchant variant.

Marketplace Mapping

Required

Since you are deploying a single pixel but running multiple Advertisables, we need to make sure that AdRoll can identify which merchant was visited.

On merchant pages that are enrolled in the program, please set the adroll_shop_id parameter to your internal ID for the merchant. If you don’t specify the marketplace mapping, the visits will be attributed to the Master Advertisable.

For example:

<script type="text/javascript">
  adroll_shop_id = "Tv4xh0cB50VCdCeHzb3csA"; // Your ID for the merchant
</script>

Enhanced Conversion Tracking

Optional

For information on recording conversion values and other user attributes, please review Setting Up Enhanced Conversion Tracking and Send Additional Visitor Data to Your AdRoll Pixel.

For example:

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

Cross Device Targeting

Optional

To enable cross device targeting, set adroll_email and/or adroll_user_identifier 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>

On-board a Merchant

The following steps need to be made to enroll a new merchant.

Create a new Advertisable

First you’ll create an Advertisable for the merchant. This establishes an AdRoll EID that will be used for subsequent API calls.

Call POST /api/v1/advertisable/create with the following parameters:

  • organization — EID for your Organization
  • name — Name of the merchant. This can be returned in the GraphQL Reporting API when generating reports
  • country_code - ISO-3166 2-Letter country code the Advertisable is registered in

Setup Marketplace Mapping

We need to establish a mapping between your internal ID for the merchant sent in the AdRoll Pixel and the AdRoll Advertisable you just created.

Call POST /api/v1/marketplace/create with the following parameters:

  • source_advertisable — EID for your Master Advertisable
  • dest_advertisable — EID for the Merchant Advertisable that you created in the previous setup
  • shop_id — Your internal ID for the merchant that matches what will be sent in the adroll_shop_id Pixel parameter

Add a Product Feed

If you plan to run Dynamic Creative, you’ll need to setup a product feed for the Merchant. If you don’t have a product feed in a standard format, we can work with you to configure our system to parse your feed.

Call POST /api/v1/feed/autoconfigure with the feed URL we can access on an ongoing basis. AdRoll will automatically recognize the feed configure the rest.

AdRoll will periodically re-fetch each feed to update the product catalog. Ideally you host your feeds at a publicly accessible URL, but we can fetch them using (S)FTP if needed.

See Setup Product Feeds for Dynamic Creative for additional information.

Create Ads

Depending on where you’ll run campaigns, review these guides for how to create ads:

When creating ads, be sure to keep track of the EIDs returned. You’ll need to specify them when launching the strategy.

Define Audiences

Audiences (aka Segments) represent sets of people who will be targeted or excluded from Campaigns. There are many different types of Audiences see Creating Audiences for how to create them.

Launch an Automated Campaigns Strategy

Call POST /activate/api/v1/strategy to launch a new strategy. This will handle Campaigns and AdGroups creation automatically. By default all strategies are created in the live state and will begin spending immediately.

The positive_segments field is a list of segments that should be targeted by the campaigns. If you’d like to exclude segments, you can specify them by EID in the negative_segments field.

The body of the request will look like:

{
  "currency": "USD",
  "budget": 1000.0,
  "kpi_metric": "CPC",
  "kpi_goal": 5.0,
  "start_date": "2017-01-01",
  "end_date": "2017-02-01",
  "products": [
    "web"
  ],
  "positive_segments": [
    "SEG_EID"
  ],
  "negative_segments": [
    "SEG_EID"
  ],
  "ad_eids": [
    "AD_EID"
  ]
}

Strategy Management

This is the day to day operations of an enrolled merchants.

Pause the Strategy

Call PUT /activate/api/v1/strategy to pause a strategy. The body of the request will look like:

{
  "status": "paused"
}

Resume the Strategy

Call PUT /activate/api/v1/strategy to resume a strategy. The body of the request will look like:

{
  "status": "live"
}

Generate Reports

You can use the AdRoll GraphQL Reporting API to retrieve reporting metrics.

Example query:

query AllAdvertisables {
  advertisable {
    byEIDs(eids: ["YIKANJKZCRAGNP37O6P374"]) {
      eid
      name
      metrics(start: "2017-12-09", end: "2017-12-10") {
        byDate {
          date
          cost
          impressions
          clicks
          cpm
          cpc
          conversions
          cpa
          roi
        }
      }
    }
  }
}

Off-board a Merchant

To off-board a merchant, you can:

  1. Pause the Strategy
  2. Stop attributing website visits to a merchant by not setting the adroll_shop_id Pixel parameter for the merchant

Variations

Web Site per Merchant

For some marketplaces, each merchant has their own website on a different domain. If that’s your setup, you can place the Pixel attached to the merchant’s Advertisable on their website. You can also skip the Marketplace Mapping API call and setting the adroll_shop_id Pixel parameter.