At a glance: Are you an ad network? Find answers to frequently asked questions about Audiences partner connections.
API key and Partner pull key
What are the API key and testing API key used for?
The API key is a unique key issued by the partner to each advertiser. The API key identifies the advertiser in each API call and is usually a long hexadecimal string (e.g., d41ac239b3b918e28fa0c). In the testing process, we will need you to provide us with a testing API key, which we will use to test your audience integration.
What is the PARTNER_PULL_KEY?
The PARTNER_PULL_KEY is a key generated by AppsFlyer and given to each partner. This is then used by the partner in the template variable located in the URL {{PARTNER_PULL_KEY}} to download the segment file.
How and when do we receive the PARTNER_PULL_KEY?
The AppsFlyer Audiences team will send you a PARTNER_PULL_KEY when we test your /sync endpoint in a later phase.
Audience file, size, and limitations
Is there a limitation on segment size?
We upload the data in a multipart upload to AWS S3. For AWS limits, see: supports:https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html
How large are the files?
We support large files. At the end, they are CSV files stored in AWS S3. For AWS limits, see: supports:https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html
Is there an upper limit for device ID rows?
The maximum number of rows is dependent on the AWS 5T file-size limit.
Can we use a direct Amazon AWS path/bucket for the audience API?
Yes, we will provide an AWS bucket and we’ll send a pre-signed URL to a path in AWS where the file is located.
Is the file compressed?
No.
Does the audience have a default validity period?
An audience doesn’t expire. Once an audience is created and connected, it is uploaded every day. An audience can be deleted though, in which case it would no longer be uploaded.
Is the file format line-break separated (or comma separated)? Is the first line a heading like advertiser_id?
It is line-break separated, and the first line is a heading such as advertiser_id_sha256 (based on the identifier being uploaded).
Will each /sync request have URLs to all 3 files (for example, ADID, email, and phone)?
Every /sync request will contain the URLs to the files the integration supports. If you support ADID, email, and phone, it will contain those 3 URLs.
As a result of step 3 (/sync), we get a link to download an audience file. Is it possible to generate and share such URL templates without an API synchronization?
At the moment, no. The URLs are generated based on your unique PARTNER_PULL_KEY. In the testing phase, the URLs will be provided and can be tested.
Here’s an example URL:
https://audiencespull.appsflyer.com/{{PARTNER_PULL_KEY}}/12cjv4dq1zyxz3nh-HASHED.csv?X-Amz-A lgorithm=AWS1-HMAC-SHA256&X-Amz-Date=20190503T091923Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=AKIB22QYTATEGB2HBFJR%2F20190603%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=c8287819a21d2f7832154df609c55ab8c0afe53540d542918b2739a9234923a
What do we need container_id for?
We will send the audience device IDs to your specified container ID by API. Audience container creation is mandatory for audience integration development.
API calls, responses, and status codes
When should we return a response?
/validate: When the API key matches the one provided to you.
/create: When the container was created on your side.
/sync: We expect to receive a response after you receive our call and can reach the file. You can download and process the file after returning the response. The link is available for download within a 2-hour timeframe.
How should we handle failed requests?
Through status codes:
200 - when the request succeeded
401 - for invalid API key - authentication
We don't support other cases out of the box. In these cases, the advertiser will see that an upload failed due to a general error. If there are recurring issues, contact us to discuss these cases.
When are our endpoints called by AppsFlyer?
/validate: AppsFlyer will call this endpoint once whenever an advertiser creates a new connection to you.
/create: This endpoint is called only once per container, meaning that for every new audience first connected to you, we call the /create endpoint and store the container ID. We expect to get back a different container ID for each /createcall. We separate platforms and audience names on our side (in other words, each platform will have its own audience on our side and will initiate a /create call).
/sync: This endpoint is called whenever an upload is initiated: either during the daily process that performs a scheduled upload of all AppsFlyer audiences, or whenever an advertiser initiates a manual upload through our UI or API call.
Are /sync requests made only once or will AppsFlyer rerun the requests later?
The /sync request is made whenever an upload is initiated. This occurs during the daily process that performs a scheduled upload of all AppsFlyer audiences, or whenever an advertiser initiates a manual upload through our UI or API call.
How often does AppsFlyer send out calls to the /sync endpoint?
It depends on the number of advertisers you work with and the number of audiences they upload. For each audience uploaded, the /sync endpoint will be called. This occurs during the daily process that performs a scheduled upload of all AppsFlyer audiences, or whenever an advertiser initiates a manual upload through our UI or API call.
If we have high traffic, can we maintain multiple API endpoints (for example, multiple routes or even domains)?
The preferred solution is to ensure that the current API can handle relatively high traffic. An API modification is available; however, this could result in delays of weeks or months to complete the integration.
Naming rules
In the /validate interface, is the api_key field a string or string array?
It is a string.
In the /create interface, must the name field (audience name) support only English characters, or does it need to support other character sets? What are the validation rules for names?
The Audience name is identical to the name in the AppsFlyer UI.
- It must be a unique name between 2-100 characters
- All languages supported
- Special symbols supported (i.e., $, %, ^, @ etc.)
In the /create interface, must the container_id be only numbers, or can it support English characters?
Both numbers and English characters are supported.
SHA256 and hashed URL
Why did our attempt to decode the Audiences SHA256 GAID/IDFA fail?
SHA256 is not meant to be decoded. This mechanism is designed for you and AppsFlyer to encode the device ID (making it possible for you to match encoded values if you have access to the original device ID).
Does AppsFlyer provide us with non-hashed identifiers?
No, non-hashed device IDs are only available to advertisers. To ensure data privacy, we hash the advertiser IDs in the segment files using the SHA256 algorithm. Advertiser IDs will be sent using this key in the request payload: url_adid_sha256.
If all GAIDs are hashed, how can we know which GAIDs we received?
If you have a plain GAID from the app and a hashed GAID from AppsFlyer, you can hash the plain GAID with SHA256, and then match it with the hashed GAID from AppsFlyer.