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