Marketing Platforms Guide¶

This guide is intended for marketing platforms that are interested in expanding their current solutions to new channels and inventory sources. In this guide, you’ll learn how to use the NextRoll API to easily onboard your customers.

Getting 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¶

A single Organization contains all of your customer’s accounts, also known as Advertisables. When onboarding a customer, you will create a new Advertisable for them.

To begin, you’ll start the initial setup:

Organization Setup

After that, your customers will go through the following lifecycle:

Onboarding a Customer
Campaign Management
Offboarding a Customer

Organization Setup¶

After you successfully create a user account an Organization and Advertisable are automatically generated for you.

To create accounts for your customers, therefore generate customer-specific Advertisables, you’ll need your Organization EID. This can be found in the eid field returned by GET /api/v1/organization/get.

Onboarding a Customer¶

The following steps are needed to onboard a new customer.

Creating an Advertisable¶

First, you’ll create an Advertisable for the customer. This establishes an Advertisable 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 customer. 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

Pixel Setup¶

The Pixel is a snippet of JavaScript that you place on all of your customer’s webpages and can be configured by setting JavaScript variables.

You can retrieve the Pixel using the API call GET /api/v1/advertisable/get_pixel and specify the advertisable parameter using the EID returned when creating the Advertisable.

The JavaScript snippet should be placed right before the closing </body> HTML tag.

Enhanced Conversion Tracking¶

Optional

To enable revenue tracking or the tracking of custom values such as order IDs, user IDs, and more please review Setting Up Enhanced Conversion Tracking.

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 (Recommended)

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

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 campaign.

Define Audiences¶

Audiences or segments represent a set of people who will be targeted or excluded from Campaigns. There are many different types of Audiences, please review Creating Audiences to learn more about creating them. The most common audience type is based on the URLs visited. These URL based audiences can be used to target visitors to specific pages such as a cart or conversion page.

Launching a Campaign¶

Once you’ve successfully created your ads and audiences, you can create a Campaign by calling POST /activate/api/v2/campaign. By default, it will start spending right away, but you can also specify a start date.

For example, this call will create a campaign with one AdGroup containing a single ad and audience:

{
  "advertisable_eid": "MY_ADVERTISABLE_EID",
  "name": "My First Campaign",
  "objective": "convert",
  "budget_settings": {
    "budget_type": "daily",
    "goal": 200.0
  },
  "adgroups": [
    {
      "name": "My AdGroup",
      "kpi_metric": "CPC",
      "kpi_goal": 5.0,
      "ad_type": "static",
      "ads": [
        {
          "eid": "MY_AD_EID",
          "status": "live"
        }
      ],
      "targeting_features": {
        "positive_segment_eids": [
          "MY_SEGMENT_EID"
        ]
      }
    }
  ]
}

Campaign Management¶

Below you can find the day to day operations of a live customer.

Pausing the Campaign¶

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

{
  "status": "paused"
}

Resuming the Campaign¶

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

{
  "status": "live"
}

Generating Reports¶

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

Example query:

query AllAdvertisables {
  advertisable {
    byEIDs(eids: ["MY_ADVERTISABLE_EID"]) {
      eid
      name
      metrics(start: "2019-12-09", end: "2019-12-10") {
        byDate {
          date
          cost
          impressions
          clicks
        }
      }
    }
  }
}

Offboarding a Customer¶

To offboard a customer, you should:

Pausing the Campaign
Remove the Pixel from their website