Audiences guide

At a glance: Audiences enables you to select app users, using rules, to generate a focused audience list. The audience is updated daily and sent to selected partners to populate your retargeting campaigns. 

audiences_example.png

Audiences main features

  • Audiences are defined using one of the following:
    • Rulesets: Filter app users using rules to select the audience from the app user population. 
    • Import: By uploading lists of user IDs generated by your other systems. Do this by file upload in the user interface or by API. 
  • Audience live size estimation and overlap visualization widgets. 
  • Audience lists are updated daily and sent to connected partners using one of the following:
    • 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.
  • Send a copy of the audience list, broken down by partners and the control group to an Amazon S3 bucket.

Setting up audiences

Setting up audiences consists of:

  • Defining the audience
  • Connecting to partners

See the procedures section on how to do so.

 Tip

See the MAMA boards video on building a winning Facebook audience strategy

 

Ruleset builder

Audiences are defined using the Audiences builder. The rule builder user interface is designed for on line rule building. We suggest that you first familiarize and experiment with the rule builder before reviewing this article.

Two rulesets with size estimation and overlay visualization

AudienceBuilder.png

  • Rulesets consist of one mandatory primary rule and optional secondary rules 
  • Rulesets can be combined using the operators: AND, OR, EXCLUDE
  • Using operators, you can combine a ruleset with imported user lists 
  • As you define the rules, the audience size is displayed
  • Where an audience consists of multiple rulesets, use the live size estimation overlap visualization widget 
  • See ruleset examples

Primary rule

The primary rule has the following filter types: 

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

 Example: Primary rule 

PrimaryRule.png

The table below contains the list of filter options. For each filter type, a single filter can be selected. 

Filter type Filter  Filter parameter
App Users of the app App name
Engagement type Who have launched the app  
Engagement type Who have viewed an add  
Engagement type Who have clicked an add  
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:
    • Reduce the population selected using the primary rule.
    • Are optional, but where used, can consist of one or more rules.
  • Each rule has a unique filter type as follows:
    • Event 
    • Device
    • Attribution
  • The filter types have different filter parameters associated with them as shown in the table that follows.

 Example: Secondary rule

Secondary_rule.png

Secondary rule with in-app event

In-app events can be filtered by using the Did event or Did not event 

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

SecondRuleInApp.png

Secondary rule filter types and filters

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 you can create audiences that consist of:
  • Multiple rulesets 
  • Rulesets and existing audiences

If you need to combine a ruleset with an Import Audience this needs to be performed as follows:

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

Ruleset examples

 Example

Users who installed the app during the last 7 days, and spent $1audiences_new_21.png Example: Users from New York who uninstalled the app in the last month

audiences_new_22.png

 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. It may be that 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 2 days.

Remarketing_example.png

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.

Procedures

The sections that follow contain the procedures to use Audiences.

To create a new audience, complete the defining an audience ruleset procedure followed by the connecting to partners procedure.

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 audience platform: Android or iOS.

  5. Users of the app: Select the app.

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

  7.  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.

  8. 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 Connect 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:
    • Cancel
    • Save Audience and Proceed: Continue to Connect 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:

Import audience

Use the data in your own systems, for example, BI, CRM, to prepare lists of device IDs. You can use imported lists as 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, you can select to:

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

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

 Examples

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 device 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

Prerequisites:

Prepare a CSV file with the following format and schema:

  • The file contains one column.
  • There is no heading row.
  • Each row contains a single device ID.
  • The maximum number of rows is 10 million. 

Example CSV file:

d5e97b54-5ded-4570-ad87-fe9b42f18820
c2595c12-9110-4c09-a80e-34cf6c0caf61
ae2fbdf8-82f1-46a8-8a84-13d6da7e2c7c
7a1e87b9-b4c2-4869-a55e-5bf1d1278476

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, click Upload
  10. Wait for a confirmation message. 
  11. Follow the instructions connect to partners

Upload confirmation messages 

Message Cause What to Do
Uploaded successfully    
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

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

https://hq1.appsflyer.com/audiences-import-api/{action}?api_token={api_token}
Parameter Description Mandatory
{action}
  • add devices: add
  • remove devices: remove
 Yes
{api_token}

The account-specific API token

Yes

API request body

{
"import_key": "{mport_key}",
"platform": "{plaform}",
"devices": [
"{device}",
"{device2}",
"{devicen}"
]
}
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
{platform}

Android or ios

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

 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

HTTP POST 
https://hq1.appsflyer.com/audience-import-api?api_token=
Accept: application/json
Content-Type: application/json
body: {
     "import_key": "EKFH2UMC5PPCU8J7M5QQCBPKIH89E6NCOB7XQFWMC",
     "platform": "android", 
     "devices": [
      "a23416b8-a21a-4051-a62f-5d3cb85e16ed",
      "09a14a6b-cce8-44f3-8f77-62eff8b5aa4f",
      "289da41f-0473-4977-89ae-8fc92234a921"
     ]
}
Code Message Description

200

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 download the file: In the Audiences window, hover-over Actions, select Download CSV

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.
    Connect2Window.png

  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
     \YYYY-MM-DD\audienceID_audienceName_timestamp\
  • 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. 

    ControIcon.png

  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. Because the 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. 
  • 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 

 Note

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.

Limitations

  • At least one positive condition is required to create the base audience, which can be reduced by further negative conditions (Example installed the app AND did not do af_purchase event).
  • Windows Phone is not supported.
  • Audience names cannot be changed on the connected partners’ side.
  • Nested event values are 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.
  • 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.
  • 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.
Was this article helpful?
2 out of 2 found this helpful