Server-to-Server (S2S) API Overview

Note

The S2S event API is under active development. Although the API is generally stable, it may change. Event processing is not yet fully complete. Send us a message if you have questions.

Introduction

AdRoll’s Server-to-Server (S2S) Event API lets you send user events and conversions directly from your servers. The S2S Event API complements the AdRoll pixel and Mobile Measurement Partner (MMP) integrations.

Data flow

Here’s how the S2S event API integrates with your user journey starting from an ad click:

1. The visitor clicks an ad.

2. AdRoll redirects visitors to your landing page, appending a unique click ID (adct) to the URL as a query parameter.

3. You capture and store visitor identifiers, such as the click ID and first-party cookie, using one of the available methods detailed below.

4. Upon conversion (e.g., purchase or sign-up), your server sends an S2S API call to AdRoll, reporting the conversion and the relevant user identifiers.

Here’s how the S2S event API integrates with your user journey, starting from a page visit:

1. A visitor lands on your website.

2. You capture and store a visitor identifier. A first-party cookie can be retrieved from the AdRoll pixel or generated using the sample code we provide.

3. Upon conversion (e.g., purchase or sign-up), your server makes an API call to AdRoll, reporting the conversion using the relevant user identifiers.

User identifiers

You can use one or more of the following methods to identify visitors. By providing multiple identifiers for each event, AdRoll is more likely to match your events to marketing events.

Click ID (adct)

AdRoll automatically appends a unique click ID to your landing page URL when a user clicks on an ad. The query parameter name is adct. Capture this parameter from the URL and store it for future API calls.

Note

If you use a third-party click tracker in your ad click URLs, ensure you pass the adct to the final landing page URL.

Example:

https://example.com?adct=click123

First-Party Cookie

First-party cookies are placed on browsers and do not have the same restrictions as third-party cookies. This behavior makes first-party cookies more stable than third-party cookies. There are multiple ways of retrieving first-party cookies to use for events:

• Option 1: Fetch first-party cookie

• Option 2: Generate a first-party cookie

Fetch first-party cookie

You can fetch the first-party cookie directly from the AdRoll Pixel using JavaScript. The following code shows an example callback:

// Fetch first-party cookie from AdRoll pixel
adroll.get_cookie(function callback (result) {
  // `result` is the cookie value as a string
});

Generate a first-party cookie

You can generate a first-party cookie if you cannot place the AdRoll Pixel on your site. The generated cookie should be valid for one year.

The AdRoll/server-to-server GitHub repository contains code examples in several languages.

Mobile device ID

For events originating from mobile apps, include the device’s advertising identifier. This could be the Apple Identifier for Advertisers (IDFA) for iOS devices or the Google Advertising ID (GAID) for Android devices.

Email

When available, you can provide cleartext or hashed emails. If hashing emails, you can specify multiple hashes to increase the chances of matching existing identities.

When hashing, use a consistent format:

• email_sha256: SHA-256(LOWERCASE(email))

• email_md5: MD5(LOWERCASE(email))

Custom user ID

A user ID is a unique identifier you assign and manage for each user within your system. This identifier should be consistent and stable for a particular user across all their interactions with your website or app.

Using a user ID provides a consistent and reliable way to track individual user behavior across sessions and devices, enhancing your ability to understand and engage with your customers over time.