AppsFlyer support for custom audience management through the Android Protected Audience API

Overview

The Protected Audience API (PAAPI) on Android (formerly known as FLEDGE), part of the Android Privacy Sandbox, is Android’s new framework for custom audience targeting that is not reliant on cross-app device IDs such as the Google Advertising ID (GAID).

AppsFlyer enables advertisers and ad platforms (on the advertiser’s behalf) to create, manage, and access on-device custom audiences for personalized ad targeting.

This is made possible with the use of the AppsFlyer SDK, designated ad partner integrations, and the AppsFlyer Audiences platform, as detailed below.

Who is this document for?

This document is for ad tech platforms that want to build their integration to receive advertiser-side Android custom audiences for ad targeting, and Android app developers who want to have a better understanding of how custom audience targeting is achieved within this new privacy-preserving framework.

AppsFlyer Audience management API for Partners

1. Create Custom Audience API

This API endpoint enables AppsFlyer ad partners to create audiences on behalf of advertisers and make them available for targeting using PAAPI. An audience created by an ad platform through the Create Custom Audience API will only be available for targeting by the audience creator.

Audience rules:

The audience rules schema is described as a tree of set operations and formatted as a JSON string.

The basic element of the criteria is the rule. 

Rules are grouped into rulesets and multiple rulesets can be grouped to describe the criteria.

Here’s a representation of a criteria containing two rulesets, each ruleset is comprised of two rules:

Operator (between rulesets)

and (operator between rules)

  Rule 1

  Rule 2

and (operator between rules)

  Rule 3

  Rule 4

The following operators are available between rulesets:

• or – user corresponds to either ruleset1 or ruleset2
• diff – user corresponds to ruleset1 minus ruleset2
• and – user corresponds to ruleset1 and ruleset2 

An audience can hold up to 12 rulesets.

Audience rules examples:

• Audience criteria structure examples:

{
  "or": [
    {
      "and": // Ruleset A Filters
[
        
      	]
    },
    {
      "and": // Ruleset B Filters
[
               ]
    }
  ]
}
// All the users of ruleset A OR ruleset B

{
  "diff": [
    {
      "or": [
        {
          "and": // Ruleset A
[
            
          	]
        },
        {
          "and": // Ruleset B
[
               
]
        }
      ]
    },
    {
      "and": // Ruleset C
[
              ]
    }
  ]
}
// All the users of (ruleset A OR ruleset B) EXCLUDE users of ruleset C

• Rulesets examples:

{
      "and": [
        {
          "filter": "launch",
          "date": {
            "type": "last",
            "value": 30
          },
          "quantifier": "at_least",
          "times": 1,
          "app_id": "com.appsflyer.android_privacy_sandbox_sample"
        }
      ]
}

{ 
      "filter": "app_version",	
      "predicate": "is",
      "values": [
        "5.20.0"
      ],
      "app_id": "com.appsflyer.android_privacy_sandbox_sample"	
}

• Audiences criteria real life example:

{
  "diff": [
    {
      "and": [
        {
          "filter": "launch",
          "date": {
            "type": "since_first"
          },
          "quantifier": "at_least",
          "times": 1,
          "app_id": "com.appsflyer.android_privacy_sandbox_sample"
        }
      ]
    },
    {
      "and": [
        {
          "filter": "launch",
          "date": {
            "type": "last",
            "value": 30
          },
          "quantifier": "at_least",
          "times": 1,
          "app_id": "com.appsflyer.android_privacy_sandbox_sample"
        }
      ]
    }]}

Audience filter  definition 

Date field

Did Event filter

Filter based on event done by the user

Event value structure

Did not do event filter

Filter based on event not done by the user in a specific date range

Dimension filter

Filter based on a dimension like device_model, os version etc..

Attribution filter

Filter based on the attribution type (organic or retargeting)

Revenue filter

Filter based on the revenue 

Event occurrences filter

Filter based on the following events occurrences 

Event occurrences filter

Filter based on the following events occurrences 

2. Audience verification token

The Audience verification token includes a UUID (dsp_audience_id) that is set by the ad platform and forwarded to AppsFlyer to allow the ad platform to identify the audience in API calls received from Android’s PAAPI.

Audience verification token would be in the following structure:

DSP Audience ID ; Appsflyer ID ; timestamp

• DSP Audience ID – 128 bit UUID generated by the DSP
• Appsflyer ID – An AppsFlyer ID is automatically created by AppsFlyer for every new install of an app
• Timestamp – current unix epoch in seconds as unsigned 64 bit integer.

This will be hashed using a symmetric key that will be provided in the onboarding phase in AES128 hashing methodology and then turned to Base64.

Ad platform integration and testing

AppsFlyer support for custom audience management through the Android Protected Audience API is currently in testing stages. We welcome ad partners to test against AppsFlyer and Android APIs, validate their solutions and provide feedback to help shape our future integrations.
Testing is being done with the use of our partner facing APIs, and our testing app that imitates both the advertiser app for audience management and the publisher app for ad selection.
To begin testing, please follow the next steps.

• Apply for AppsFlyer’s PAAPI testing
  • Testing is available for AppsFlyer ad partners that are already integrated with the AppsFlyer platform (for either Attribution or Audience management) 
  • To join AppsFlyer Protected Audience API testing, please reach out to your Partner Devepment Manager 
  • Once approved,  you will be granted access to the Create Custom Audience API. To authenticate, please use the AppsFlyer API Token V2 that is available within your AppsFlyer account login. 
• Get Symmetric key for Audience verification token encryption and App Testing Key
  • Once approved, AppsFlyer will provide ad partner with two keys that are required for testing:
    • Symmetric key for encryption and decryption of the Audience verification token
    • App Testing Key that is used as an input within your testing app and identifies your test devices as belong to a specific ad partner
• Implement Android’s Protected Audience APIs (FetchURI, DailyUpdateURL, etc..)
  • Please follow Android dev documentation for details
• Share FetchURI with AppsFlyer
  • The FetchURI will be sent by the AppsFlyer SDK together with fetchAndJoinCustomAudience calls, to call the ad platforms servers for required audience data such as ads and bidding information
• Download the AppsFlyer PAAPI Test app