Audience Integration Guide

For Mobile Measurement Platforms (MMPs) and Advertisers

Introduction

To better facilitate the automation of the entire data transfer process, AdColony has implemented an Audience Segments API for Mobile Measurement Platforms (MMPs) and Advertisers. AdColony’s goal is to assist in making a fast, easy and reliable mobile advertising segmentation solution.
By exposing API endpoints for the ingestion of data, you can help deliver better targeting and re-engagement, without compromising on data transfer concerns. This is accomplished by enabling the following capabilities:

  • adding/removing device IDs to/from each audience container
  • getting an indication of the actual audience size for a given audience Container ID
  • getting a list of all the audiences for a specific user

Versions

Version Date Description
0.1 09-27-2018 Initial document
0.2 10-02-2018 Document revisions (format and content)
0.3 10-15-2018 Updates to S3 Path Definitions
0.4 10-16-2018 Corrections to the S3 path definition. Updated response for /Create API to reflect that the audience id is returned.

 

Registration

To integrate a new MMP or Advertiser, AdColony requires a unique Name for that MMP or Advertiser. AdColony will provide credentials for accessing AWS S3 and making HTTP requests using the REST API for the new MMP/Advertiser upon request.

Shared Items Description
api_key The key used for all REST API calls for the MMP or Advertiser
s3_path The AWS S3 base path unique to the MMP or Advertiser for all Audience Container file uploads
access_key The AWS S3 access key for the MMP or Advertiser / s3_path pair
secret_key The AWS S3 secret key for the MMP or Advertiser / s3_path pair

Authentication

Users will authenticate themselves in the partner’s audiences platform before being able to sync the data to the AdColony with API Key. An example of one such platform is the Appsflyer Audiences Platform.

Access method Credentials required
REST API “api-key”
S3 AWS S3 access id & secret Key

 

Deployments

Base URL Description
http://mmp.adcolony.xyz/api/v1 Production
http://mmp-alpha.adcolony.xyz/api/v1 Alpha / Test

 

API Endpoints

REST API Endpoints

Name Endpoint Description
Create /api/v1/create Creates an Audience Container (i.e. a Segment)
(up to 10M device-ids)
List /api/v1/list Returns the count of users in Audience Container(s)
Delete /api/v1/delete Deletes an Audience Container (optional)

S3 Bucket Base Path

S3 Bucket Base Path Description
s3://adcolony-mmp-segments/production/to_adcolony/ Base S3 path for uploading Production audience container / segment files
s3://adcolony-mmp-segments/alpha/to_adcolony/ Testing: Base S3 path for uploading Test audience container / segment files

 

REST API Details

Create API

Capable of returning an Audience ID unique to AdColony with App ID metadata.

Request Definition

Parameter Description Type
name The name of the Audience Container (Segment)

required

String (max: 50)
api_key The API-Key of the Vendor for the new Audience Container

required

String

Response Definition

Parameter Description Type
audience_id The ID of the Audience Container (Segment) that was created. This value is expected to be used as part of the S3 path for files UUID

Example Request / Response

HTTP Request
  • Endpoint: http://mmp.adcolony.xyz/api/v1/create
  • Method: POST
JSON body
{
"name": "USA Audience",
"api_key": "9257671d-4980-492f-a454-1d798c861140"
}
Status Response: 201 Created
{
"audience_id" : "2dd3688a-2324-45ad-bf6d-fd6697fa136c”
}

List API

Capable of sending an indication of the actual audience size for a given audience Container ID or for all the audiences of a specific user. This is used to verify that the upload process was successfully completed.

Request Definition

Parameter Description Type Requirement
api_key The API-Key of the Vendor for the Audience Container ID(s) requested String Mandatory
audience_ids A list of Audience Container ID(s) to retrieve the user count of List[String] Optional

 

Response Definition

Parameter Description Type
audience_counts List of Audience Container IDs & user counts List[AudienceCount]

Audience Details

Parameter Description Type
audience_id The ID of the Audience Container (Segment) String (max: 50)
count The number of non-expired users (unique device-ids) included in the Audience Container Integer

Example Request / Response

HTTP Request
  • Endpoint: http://mmp.adcolony.xyz/api/v1/list
  • Method: GET
JSON Body
{
"api_key": "9257671d-4980-492f-a454-1d798c861140",
"Audience_ids":
[
"USA_Audience-1",
"USA_Audience-2"
]
}
Status Response: 200 OK
{
"audience_counts": [
{
"audience_id": "USA_Audience-1",
"count": 14334
},
{
"audience_id": "USA_Audience-2",
"count": 784
}
]
}
JSON Body [All Audiences]
{
"api_key": "9257671d-4980-492f-a454-1d798c861140",
"Audience_ids": []
}
Status Response: 200 OK [All Audiences]
{
"audience_counts": [
{ "audience_id": "",
"Count" : 14334 }
]
}

S3 Bucket Details

Audience Containers (Segments) files are formatted with a single device-id per line. The audience container file will be uploaded to the Vendor specific S3 bucket path each time the Audience Containers (Segments) is updated.

The file defining the Audience Container can be uploaded multiple times for the same audience on a single day. For that reason, AdColony will always overwrite every audience based on the device-ids included in the last uploaded file to S3.

The following details are required for each Audience Container file upload:

  • S3 Bucket Path for this specific MMP or Advertiser
  • S3 Access id Key
  • S3 Secret Key

S3 Path Definition

<s3_bucket_base_path>/<partner_name>/<audience_id>/YYYY/MM/DD/timestamp

S3 Path part Description
s3_bucket_base_path The base S3 path as defined in section S3 Bucket Base Path
partner_name The unique Partner name provided by AdColony during the Registration Process
audience_id The audience id from the response of the /Create API
YYYY The year
MM The month (01, 02, …12 ) [2 digit]
DD The day (01, 02, .. 31 ) [2 digit]
timestamp The file containing the list of device-ids defining the Audience Container. (audience_container_id)
File name format: Epoch timestamp in seconds.
File contents: Unquoted device ids – one device id per line, newline delimited

 

Example S3 Path

s3://adcolony-mmp-segments/production/to_adcolony/mmp-partner-appsflyer/2dd3688a-2324-45ad-bf6d-fd6697fa136c/2018/09/27/1620911144.txt

Example file content:

Definitions

  • Audience Container is a segment or a unique group of users