Audiences guide

At a glance: Audiences enables you to segment app users, using rules, to precisely focus your remarketing efforts improving retention and increasing engagement. The audience is updated daily and sent to selected partners to populate retargeting campaigns. 



  • Audiences are defined using rulesets that filter and select app users from the app user population or by importing lists of user IDs (advertising IDs) generated by your other systems.
  • Audience live size estimation and overlap visualization widget. 
  • Audience lists are updated daily. You can split the audience between connected partners as follows:
    • Send the entire audience list to all connected partners.
    • Split the audience and allocate a portion to each partner and optionally send a portion to a control group.
  • Send copies of the audience list, split by partner and control group to an Amazon S3 bucket.

Tip! See MAMA board video - Winning a Facebook audience strategy

About the ruleset builder


The rule builder user interface is designed for interactive rule building. Tip! Familiarize and experiment with the rule builder before reviewing this article in detail.

Example - two rulesets with size estimation and overlay visualization


  • A ruleset consists of  a mandatory primary rule and optional secondary rules
  • Combine rulesets using operators: and, or, exclude.
  • As rules are defined the estimated audience size is displayed
  • Where an audience consists of multiple rulesets, use the live size estimation overlap visualization widget. 
  • The user identifier used to evaluate rules is either advertising ID [default] or customer user ID (CUID). The audience list always contains advertising IDs. 
  • Ruleset examples

Rules explained

Primary rule

The primary rule has the following filter types:

  • App 
  • Engagement type
  • Engagement time frame
  • Engagement frequency

 Example: Primary rule


Primary rule filter options
Filter type Filter  Filter parameter
App Users of the app Any app in the account. The team member defining the audience needs permission for all apps being filtered. 
Engagement type Who have launched the app  
Engagement type Who have viewed an ad  
Engagement type Who have clicked an ad  
Engagement type Who installed the app  
Engagement type Who launched the app  
Time frame In the last n days n= number of days from 1-9999
Time frame Between start date and end date Start date, End date
Time frame At any time None
Frequency Used the app at least n times n=number of times from 1-100
Frequency Used the app exactly n times n=number of times from 1-100
Frequency Used the app at most n times n=number of times from 1-100

Secondary rule

  • Secondary rules:
    • Filter (reduce) the population selected
    • Are optional
  • Each rule has a unique filter type as follows:
    • Event 
    • Device
    • Attribution
  • Filter types have different filter parameters associated with them as shown in the table that follows.

 Example: Secondary rule with in-app event


  • In-app events can be filtered by using the Did event or Did not event 
  • The in-app event list updates Daily
  • In-app events, having more than 100 attributes (unique values) by default aren't recorded. If you need these events recorded, reach out to your CSM or send an email to
  • Where the Did event is selected, and the in-app event has attributes associated with it, you can filter by in-app-event attribute value. See the example that follows. 

 Example: Secondary rule with in-app event filter


Secondary rule filter types
Filter type Filter  Filter parameter Remark
Event Installed the app Time frame and Frequency   
Event Did not install the app  Time frame and Frequency   
Event Launched the app Time frame and Frequency   
Event Uninstalled the app Time frame and Frequency   
Event Launched the app Time frame and Frequency   
Events  Did event: in-app event Time frame and Frequency  Select in-app event and where relevant in-app attribute
Events  Did not do event: in-app event Time frame and Frequency  Select in-app event 
Event  Total revenue generated  Is or greater than or lower than
  • The value is in USD.
  • The value is the total value of all events reported from a device using the af_revenue parameter.
Event Location  Is or Is not 
  • The combination of Country, state, city.
  • Where multiple countries are selected, you can't select the state.
  • The same is true for states and cities. 
Event Metro code Is or Is not   
Device Device brand Is or Is not   
Device Device model  Is or Is not   
Device  App version Is or Is not   
Device  OS version Is or Is not   
Device  Carrier Is or Is not   
Attribution Organic True or False  
Attribution  Retargeting True or False  

Combining rulesets

Using the and, or, exclude operators create audiences that consist of:
  • Multiple rulesets 
  • Rulesets and existing audiences together

If you need to combine a ruleset with an Import Audience do so as follows:

  1. Create the audience; for example, A.
  2. Create the import audience, for example, Import_B
  3. Create a combined audience using Select from my Audiences and combine A with Import_B using the operators.

Ruleset examples


Users who installed the app during the last seven days, and spent $1


Users from New York who uninstalled the app in the last month


Remarketing examples

Using clicks and views for effective remarketing with audiences. Remarketing is a method of advertising to audiences who have viewed or clicked on your ads but who did not convert. To convert these users, all that is needed is a little extra convincing or a gentle reminder. These users have a high chance of converting, so remarketing to them can produce significantly better results than advertising to new audiences.

You can create precise audiences for remarketing based on the clicks and impressions data collected by AppsFlyer.

Build an audience of potential users that clicked on an ad, but did not install in the last two days.


These are users who, in the recent past, were sufficiently interested in your mobile app to click on your ad, but for some reason did not install the app, or installed the app but did not launch it. Some users just need a reminder (push) to install it. Others may need to see more screens or features of your app to finally convert. Therefore, if you have a primary creative you use on new audiences, it is might be better to use a different creative for audiences that clicked but did not install.

User identifier (advanced setting)

Audience rule evaluation is performed using an app user identifier. Select from:

  • [Default] Advertising ID: Ruleset compliance is assessed using the advertising ID. When compliant with the ruleset, the Advertising ID is added to the audience list. Note: Advertising ID means GAID, IDFA, or equivalent.
  • Customer User ID (CUID):


    • Ruleset compliance is assessed by grouping advertising IDs (devices) associated with the same CUID together. If the group complies with the ruleset, then the advertising IDs comprising the group are added to the audience. Note: The CUID itself is not part of the audience list.
    • CUID implementation considerations:
      • Ensure that your data is populated with valid CUIDs.
      • App users (devices) without a CUID are ignored.
      • When an advertising ID, is matched to a CUID, historical audience data for the user is updated retroactively and included in audience builds going forward. Note: No change is made to raw data. 
      • If an advertising ID is associated with two different CUIDs, the  CUID most recently associated is used (wins.)

 Example Advertising ID vs. CUID

Raw data for example
CUID Purchase $
A 99 1
A 99 2
B 77 1
B 77 5
C 99 3
D None 50
Users who purchased at least $5
Ruyle evaluated by Advertising IDs included in the audience Explanation
Advertising ID B, D, E A and C are not included - the spend was less than $5
  • A and C have the same CUID (99) - the combined spend is $6. 
  • D is ignored - there is no CUID


Use the procedures that follow to create and manage audiences. If this is your first Audience, you need complete defining audience rulesets and connecting to partners

Defining audience rulesets

Audiences can be defined using one of the following:

  • Create a new ruleset
  • Use an existing audience ruleset 
  • Import an audience from your other systems by file upload or API 

Define the audience using one of the methods that follow.

New ruleset

Rulesets consist of one primary rule that defines the global population with optional secondary rules that further filter the population. 

To create a primary rule:

  1. Go to Integration > Audiences.
    The Audiences window opens. 

  2. Click Add Audience.
    The Audience window opens. The Build tab displays.

  3. Enter a unique Audience Name.

  4. Select the platform: Android or iOS.

  5. [Optional] Select Advanced settings to select the user identifier:
    • [Default] Advertising ID: evaluates rules by advertising ID only.
    • Customer user ID: evaluates rules by grouping devices using the CUID. Use this method after you verify that your data has valid CUIDs.
  6. Users of the app: Select the app.

  7. Who have select one of the following: engaged, installed, launched the app

  8.  Set the time frame filter using one of the following:

    • In the last n days: n is the number of days going backward, starting from today.

    • Between: Enter a specific data range

    • At any time: include all available dates, starting from the first date of available audience data.

  9. Do one of the following:
    • Click Save Audiences and proceed. Continue to Connect to partners procedure.
      --OR --
      Click Add Filter, to add a secondary filter and continue with the procedure that follows.

To add a secondary filter:

  1. Click Add Filer. 

  2. Complete the rule fields that display. The fields that display vary according to the filter type selected.
    Note: In-app events can be filtered by using the did use/did not use event types. See secondary rules for more details. See the example that follows this procedure.

  3. Do one of the following:
    • Add Filter to add another secondary filter and repeat this procedure.
    • Cancel.
    • Save Audience and Proceed: Continue to Connecting to partners procedure.
    • Combine this ruleset with another ruleset using an operator: AND, OREXCLUDE
      An additional ruleset panel displays. Use one of the following procedures:

 Example: Ruleset with in-app event


The ruleset above defines an audience of users that have made at least 1 purchase of 1 item, that cost over $10, in the last 120 days.

Select from my audiences

You can create new audiences by selecting an existing audience, or by combining an existing audience with new rulesets. Note: It is not possible to select an audience that already includes another audience.

  1. Go to Integration > Audiences.
    The Audiences window opens.

  2. Click Add Audience
    The Audience window opens. The Build tab displays.

  3. Enter a unique Audience Name.

  4. Select the audience platform: Android or iOS.

  5. Click Select from my Audience.

  6. Users of the audience: Select an audience. 
  7. Do one of the following:

Import audience

Use data from other systems, (BI, CRM)  to prepare lists of advertising IDs.  Imported lists can form part of a ruleset to add additional IDs to the audience or as an exclude list to prevent IDs from being included in the audience.

At the import list stage, select one of the following:

  • Overwrite the existing list
  • Add to the existing list
  • Exclude (remove) from the existing list 

Lists can be imported by file upload in the interface or by API.


Promotional retargeting 

To target users who have a birthday with promotional offers.

You can do the following:

  1. Use your other system to generate a list of users with birthdays. Export this list as a list of advertising IDs
  2. Upload the list to AppsFlyer and send it to the audience partner of choice
  3. Setup up a campaign in the audience partner to target the audience accordingly

Acquiring additional users

Your app development studio acquires another studio. This studio has a list of users that installed their apps and you want to target these users to install your existing apps.

You can do the following:

  • Take the list of device advertising IDs that belong to the users of the studio that you acquired
  • Import this list to AppsFlyer and upload it to your audience partner of choice
  • Target these users to install your apps

Import audience by uploading a CSV file


Prepare a CSV file with the following format and schema:

  • One column
  • No heading row
  • No blank rows
  • Rows contain a single advertising ID
  • Maximum number of rows:10 million.
  • If you prepare the file using Excel, save it as a CSV (Comma delimited) (*.csv) file. Select the file type as shown in the figure that follows.


Example CSV file:


To upload the audience CSV file

  1. Go to Integration > Audiences.
    The Audiences window opens.

  2. Click Add Audience.
    The Audience window opens. The Build tab is displayed.

  3. Enter a unique Audience Name.

  4. Select the audience platform: Android or iOS.

  5. Select Import Audience.
  6. If it's a new audience:
    • Enter an Audience Name.
    • Click Save.
  7. Click CSV Upload.
  8. Choose what to do with the imported audience:
    • Add new devices: adds the list of device ids to the existing audience
    • Overwrite all existing devices: replace the entire audience with the uploaded list
    • Exclude from existing device list: remove devices in the upload list from the audience.
  9. Chose the CSV file to upload.
  10. Click Upload
    Wait for the confirmation message Uploaded successfully.
  11. Click Save Audience and Proceed.
  12. .Select a partner to select to.
  13. If necessary, follow the instructions connect to partners
  14. Click Close.
    The list is not immediately available. Lists are processed with a data freshness of Daily

Upload confirmation messages 

Message Cause What to Do
Uploaded successfully  The data will be available with a data freshness of daily  
Seems like your device list is empty. Add some device IDs to it and try again The CSV file is empty

Make sure that the CSV contains at least one device ID

We couldn’t understand one or more of your device IDs
  • The CSV format is incorrect
  • The file you uploaded is not a CSV file
  • The CSV file was edited and saved by a program other than a valid CSV editor (i.e. Microsoft Excel)
  • One or more device IDs is in the wrong format
  • Make sure that the CSV is in the required format
  • The CSV should contain one column and one device ID per row. The CSV should contain no headers.
  • Make sure that all device IDs are in the correct GUID format
  • If you used Excel, save the file as a CSV file as shown here. 
  • CSV.jpg

See table above for the correct formats

We just had a temporary connection problem and couldn’t upload your file. You can try again now Possible network error Try to upload the CSV file again

Import an audience using the API

The import audience API is used to either add or remove devices from an audience. The API has the structure shown in the example. Use the procedure that follows to generate the API request URL and the API requirest body.

API request URL{action}?api_token={api_token}
Parameter Description Mandatory
  • add devices: add
  • remove devices: remove

The account-specific API token


API request body

"import_key": "{mport_key}",
"platform": "{plaform}",
"devices": [
Parameter Description Mandatory
{import_key} Unique key that identifies the audience. Note: Use the same import_key for both the add and remove endpoints.   Yes

Android or ios

  • Unique device IDs
  • The maximum number of devices in one call 10,000.

 Before you begin:

  • Ensure that you have created the audience in AppsFlyer.

To prepare an API request URL:

  1. Go to Integration > Audiences.
    The Audiences window opens.

  2. Click Add Audience.
    The Audience window opens. The Build tab is displayed.

  3. Enter a unique Audience Name.

  4. Select the audience platform: Android or iOS.

  5. Select Import Audience.
  6. Click API.
  7. Select API Action
    • Add Devices: add additional device advertising IDs to an existing audience. 
    • Remove Devices: Remove a list of device advertising IDs from an existing audience.
      Note: Choosing an API Action changes the endpoint path referenced. It doesn't persist after you save the audience. When you want to add or remove devices from an audience, you can specify the action using the necessary path. 
  8. Copy the API Request URLthe API token is already included in the URL.
  9. Copy the API Request Body.
  10. Click Save Audience and Proceed.
  11. (optional) Connect your audience to partners.
  12. Prepare the API inclduing the devices ids and post the API to Appsflyer as shown in the example above. 

Sample request to add devices

Accept: application/json
Content-Type: application/json
body: {
     "platform": "android", 
     "devices": [
Code Message Description


The request was successful Audience successfully imported
400 Seems like your device list is empty. Add some device IDs to it and try again

The request body contains an empty list of devices.

You must provide at least 1 device ID per request.

400 Cannot process more than 10,000 devices per request (x devices counted in this request) The request body contains a list of more than 10,000 device IDs
400 We couldn’t understand one or more of your device IDs Some device IDs are not valid IDFA / GAID
400 Invalid audience platform, this audience is already configured for Android/IOS. To use a different platform, please create a new audience in the UI The platform specified in the request body doesn't match the platform specified when creating the audience
403 Forbidden Incorrect or missing import key
500 Could not parse request

Invalid request body format.

See the request sample above.

API limitations

  • You can only add devices to one audience per request
  • You can only remove devices from one audience per request
  • Batch requests (multiple audiences) are not supported
  • You can send up to 10,000 device IDs per request

Connecting to partners

  • The audience is sent by upload to one or more selected partners.
  • The audience is updated daily and replicated to the partner. AppsFlyer either sends a new list to the partner or notifies the partner which devices to add/delete. The methodology differs from partner to partner but the end result is the same. 
  • The following sending options are available:
    • Send the entire audience list to all connected partners.
    • Split the audience and allocate a portion to each partner.
    • Split the audience and allocate a portion to each partner and a portion to a control group.
  • (Optional) Send a copy of split audience groups, to an Amazon S3 bucket. This includes the control group where applicable. Note: This is not the same as defining Amazon S3 as a connected partner.
  • Download audience lists: The audience list can be downloaded to a CSV file. You can use the CSV file, for example, to send to partners who are not integrated with AppsFlyer.

To connect an audience to a partner:

  1. In the Audience builder window, select the Connect tab.
    The list of partners displays. 

  2. Select a partner.
    The connect to partner window displays.

  3. Do one of the following:
    • Select Existing Connection.
      --OR --
    • Select Add a new connection and follow the partner-specific instructions for the selected partner. 
  4. Select one or more connections for the partner. Selecting multiple connections means that the audience is sent to the partner multiple times. 

  5. Click Save Connections.
    The partner is added to the list of partners. 

  6. Do one of the following:

    • To select an additional partner, repeat this procedure.

    • Split Audience: To split the audience with optional control groups follow the instructions in the section that follows.
    • CloseThe connection is complete. The audience is sent to the partners daily. Note: In this configuration, the entire audience is sent to all connected partners daily. 

Splitting an audience and control groups

Split audience

Split Audience enables advertisers to split the audience from two to ten partners. Each partner is allocated a unique part, by percent, of the audience. When Split Audience is enabled, it means that a user is uploaded to only one partner.

Advertisers split audiences for a variety of reasons like A/B testing, target a user from a single channel, etc.

You can modify split audience configurations after creation, meaning that you can change the allocation between partners, remove, and add partners. Take into consideration that allocation modifications can impact the validity of A/B or other test measurements. For this reason, we display an alert message, before you can make a modification.

Control groups

A portion of the audience can be sent to a control group. The control group is not sent to any partner. Use the control group to compare the behavior of targeted users relative to the control group. 

Send copies of split audience lists to S3 

CSV files containing the split audience lists and control group can be sent to an Amazon S3 bucket. The directory and file name structure is as follows:

  • Directory structure
  • Filename: The name of the partner or control group. Note: If the connection to the partner fails, and the file is not uploaded then the parnter_name will have the suffix failed. Example: partner_name_failed.csv 

Creating a split audience configuration and control group

Before you can split the audience:

To create a split audience configuration:

  1. Click Split Audience.
    The Set Audience Percentages window displays.
  2. Enable Split audience
  3. (option) To enable a control group: Select Enable Control Group 
  4. Fill in the audience allocation, in percentage, for each partner and if needed for the control group. 
  5. Click Apply.
    The percentage allocated to each partner is displayed. 


  6. (Optional) Send split groups to S3: Sends the audience list in CSV files to an Amazon S3 bucket. (See above for details.) 
  7.  Click Close.
    AppsFlyer sends the split audience to the designated partners once a day.

Modifying split audience configurations

You can modify the split audience allocation as follows:

  • Modify the current allocation 
  • Remove a partner
  • Add a partner

When you modify the allocation between partners, the entire audience is redistributed between the partners. Note that this could impact the validity of A/B or other test measurements. In addition, modification resets the existing audience allocation.

To modify a split audience configuration:

  1. Go to Integration > Audiences.
  2. Select the audience to be modified.
  3. Go to the Connect tab.
    The split audience allocation displays.
  4. Select one of the following:

Modify the current allocation 

  1. Click Split Audience.
    An alert displays.
  2. Click Continue to proceed.
  3. Fill in the audience allocation, in percentage, for each partner.
  4. Click Apply.
    The percentage allocation to each partner displays. The modification is complete.
  5. Click Close.

Remove a partner

  1. Select the partner you want to remove.
    An alert displays.
  2. Click Got it to proceed.
    The partner's connection list displays.
  3. Clear the checkbox on one or more of the existing connections.
  4. Click Save Connections.
    The partner is removed.
  5. Click Split Audience.
    The Set Audience Percentages window displays.
  6. Switch Enable Split Audience on.
  7. Fill in the audience allocation, in percentage, for each partner.
  8. Click Apply.
    The split audience is enabled. The percentage allocation to each partner displays.
  9. Click Close.

Add a partner

  1. Select a partner to add.
    An alert displays.
  2. Click Cancel or continue to configure using the partner configuration instructions.

Viewing and managing audiences

Go to IntegrationAudiences to view and manage your Audiences.

In the Audiences window, you can view information about audiences, add an audience, use the actions and bulk actions controls. These features are described here. 

In the Audiences window you can view the following information: 

  • Audience name
  • Size: number of users in the audience
  • App name 
  • Upload to: names of partners to whom the audience is sent. 
    • If split audiences are enabled the icon SplitAudiences.pngdisplays next to the list
    • If a control group is enabled this is indicated by the control group icon. ControlGroup.png
  • Upload Status has the following indicators:
    • Success and the last upload time 
    • Failure, click View Details to see the reason the upload failed

Actions control 

Select an audience Action control to perform one of the following: 

  • View history displays the upload history of that audience. Audience updates daily, you can view the size differences of the user list throughout its lifecycle:
  • Upload now sends the audience to the connected partners
  • Download as CSV to download the audience device ID list in a CSV file.
    • There is a separate file for each partner.
    • The download file is available after the audience has been calculated. It can take some time for this to happen after you create or modify an audience. 
    • Download files are limited to 5 million records. For larger files, write the file to an S3 bucket or use SFTP
  • Duplicate allows you to make a copy of the selected audience definition. (Option) remove one or more of the existing partners. Note: Audience names do not have to be unique. When you duplicate an audience you should give it a unique name. 

  • Delete

Bulk actions

The Bulk actions control enables you to carry out the same action on multiple audiences. To use Bulk actions, select two or more audiences and a Bulk action: 

  • Upload now sends the audience to the connected partners.
  • Show audience overlap: displays the audience overlap between the selected audiences,
  • Delete the selected audiences 


The Audience user base is updated daily. It contains user information up to and including the previous day. That means yesterday and all the days before it.

Traits and Limitations


Audiences traits
Trait  Supported Remarks 
Ad networks  x  
Agencies  x  
Agency transparency  x  
App-specific time zone N/A  
App-specific currency  N/A  
Size limitations N/A  
Organic data Included
Non-organic data Included
Data freshness Daily UTC
  • Updates are pushed to partners on a daily basis
  • The in-app event lists in the rule-builder update Daily. 
Historical data See data freshness
Team member access
  • Some functions, like CSV download, setting S3, SFTP, and Slack partner connections require team member access to raw data
  • As a security measure, where the account of the team member, who created an audience is deleted, AppsFlyer stops uploading audience data to the advertising partner. To check the upload status of your audiences, go to Integration > Audiences. To reactivate the audience, in the Audiences window, duplicate the audience, and configure the split audience settings.


  • One positive condition is required to create the base audience. It can then be reduced by further negative conditions. For example, installed the app AND did not do af_purchase event.
  • Windows Phone not supported.
  • Audience names cannot be changed on the connected partners’ side.
  • Nested event values not supported.
  • When creating an audience, at times, not all the events appear. Only the top 100 are displayed. However, when you begin entering an event name, all the events are shown.
  • In-app events having more than 100 attributes by default aren't recorded. Contact your CSM if more attributes are required.
  • Clicks and impressions data only contain devices which have an advertising_id/idfa on their original click URL. The devices of users from SRNs, which don't use external attribution links, are not included in the clicks data for audiences.
  • When using the Total Revenue filter within the query builder, the Estimated Audience Size is not available. This does not affect the Audience creation and the Audience list.
  • You cannot combine audiences created by import with other audiences or rulesets.  
  • Download file size limited to 5 million records.
Was this article helpful?