Custom Audiences from your Mobile App

Build audiences based on peoples' actions in your app that meet your criteria. For example, define audiences who "Passed Level 8 in the last 10 days", "Used app in the last 8 days but hasn't purchased anything". "Added to cart but not purchased", and so on.

This solution uses logged named events through our Facebook SDKs or via Mobile Measurement Partners. Examples include "Installed", "Added to Cart", "Purchased", or "Achieved a Level".

Creating an Audience

To create Custom Audiences from your mobile app, the ad account must accept the Terms of Service for Custom Audiences, in Power Editor.

  • You need to be either an Admin, Developer, or Insights User for the ad account.
  • Or the ad account should be listed as an Advertising account on your app settings.

You can create a maximum of 200 custom audiences via Custom Audiences from Your Mobile App. Make a HTTP POST to:

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

Use these fields:

name type description required

name

string

name of your Custom Audience

yes

subtype

string

Set to APP

yes

retention_days

integer

How long someone is in this audience. 1 min, 180 max.


If retention_days is 14, and on day 13, an audience member triggers an app event matching your criteria, then Facebook extends their time in the audience 14 more days. Someone is in an audience N days from the last matching event they triggered.

yes

rule

JSON Object

Rules to define the audience. See Audience Rules

yes

Audience Rules

To determine who gets added to the Custom Audience, define rules based on events in your app. A rule is a JSON object with key-value pairs and can only reference a single app event.

For example:

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;
use FacebookAds\Object\Values\CustomAudienceSubtypes;

$custom_audience = new CustomAudience(null, 'act_<AD_ACCOUNT_ID>');
$custom_audience->setData(array(
  CustomAudienceFields::NAME => 'My Mobile App Custom Audience',
  CustomAudienceFields::SUBTYPE => CustomAudienceSubtypes::APP,
  CustomAudienceFields::RETENTION_DAYS => 15,
  CustomAudienceFields::RULE => array(
    '_application' => <APP_ID>,
    '_eventName' => $event_name,
  ),
));
$custom_audience->create();
curl \
  -F 'name=My Mobile App Custom Audience' \
  -F 'subtype=APP' \
  -F 'retention_days=15' \
  -F 'rule={"_application":"<APP_ID>","_eventName":"fb_mobile_purchase"}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/customaudiences

You can define a _cumulativeRule, specifying rules for the entire audience such as "top 20% of purchasers." Or you can define rules on specific events and their parameters, such as "purchases over $20".

Facebook ignores additional parameters in events that are not in a rule. Each parameter in a rule must in the event and its value matched for a rule to succeed.

Beyond the parameters below, rules can contain any other parameters that match App Events sent by an app. This includes parameters sent from Mobile Measurement Partners and custom parameters via App Events.

key type value required

_application

string

Facebook app ID for app triggering events

yes

_eventName

string

Event name. Use App Events API to see app events and parameters reported by the app.

yes

_valueToSum

float OR JSON object

If set to a single float value, Facebook matches events that have exactly that value. If a JSON object, you can use rule operators, defined below

no

_cumulativeRule

JSON object

A JSON object of metric, period, and technique, see Cumulative Rules

No, but if _cumulativeRule specified, no other clauses allowed except _application and _eventName

_appVersion

String or JSON object

Mobile app version. If you use JSON objects, you can use rule operators, defined below

no

_logTime

Integer or JSON object

Time of event in unixtime. If a JSON object, you can use rule operators, defined below. Not intended for standard use.

no

Cumulative Rules

Define a JSON object with three fields, metric, period, and technique, for a _cumulativeRule:

key type value required

metric

string

must be count, amount, or usd_amount. The property that a rule applies to

yes

period

string

must be 1d, 7d, 28d

yes

technique

JSON object

JSON object with technique_name and two optional fields, lower_bound and upper_bound.
technique_name values:
percentile: add people from a specified percentile range
absolute: add people that logged events in specified range. For example, from 80 logged purchases to 870 logged purchases.



lower_bound (int): if specified, lowest percentile to start adding. If not specified, defaults to 0 for percentile or negative infinity for absolute.
upper_bound (int): if specified, highest percentile to start adding. If not specified, default to 100 for percentile or positive infinity for absolute.

yes

This creates an audience with the top 20% of purchasers based on purchases in the last seven days:

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;
use FacebookAds\Object\Values\CustomAudienceSubtypes;

$custom_audience = new CustomAudience(null, 'act_<AD_ACCOUNT_ID>');
$custom_audience->setData(array(
  CustomAudienceFields::NAME =>
    'My Mobile App Custom Audience with Cumulative Rule',
  CustomAudienceFields::SUBTYPE => CustomAudienceSubtypes::APP,
  CustomAudienceFields::RETENTION_DAYS => 15,
  CustomAudienceFields::RULE => array(
    "_application" => <APP_ID>,
    "_eventName" => $event_name,
    "_cumulativeRule" => array(
      "metric" => "count",
      "period" => "7d",
      "technique" => array(
          "technique_name" => "percentile",
          "lower_bound" => 80,
      ),
    ),
  ),
));
$custom_audience->create();
curl \
  -F 'name=My Mobile App Custom Audience with Cumulative Rule' \
  -F 'subtype=APP' \
  -F 'retention_days=15' \
  -F 'rule={ 
    "_application": "<APP_ID>", 
    "_eventName": "fb_mobile_purchase", 
    "_cumulativeRule": { 
      "metric": "count", 
      "period": "7d", 
      "technique": {"technique_name":"percentile","lower_bound":80} 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/customaudiences

Rule operators

These provide flexibility for your rules:

Operator Description Example

gt

True if event's parameter value greater than specified value.

'_valueToSum' : { 'gt' : 5 }

gte

True if event's parameter value greater than or equal to specified value.

'_valueToSum' : { 'gte' : 5 }

lt

True if event's parameter value less than specified value.

'_valueToSum' : { 'lt' : 5 }

lte

True if event's parameter value less than or equal to specified value.

'_valueToSum' : { 'lte' : 5 }

eq

True if event's parameter value equal to specified value. Note this is equivalent to not specifying an operator at all. That is, "'x' : { 'eq' : 'y' }" is the same as "'x' : 'y' }.

'myParam' : { 'eq' : 'Hello' }

neq

True if event's parameter value not equal to specified value.

'myParam' : { 'neq' : 'Hello' }

contains

True if event's parameter value, as string, contains specified string. Value of "shoe12345" fulfills 'contains' if specified value 'shoe'.

'fb_content_id' : { 'contains' : 'shoe' }

not_contains

True if event's parameter value, as string, does not contain specified string. Value "shoe12345" fulfills 'not_contains' if specified value is 'purse'.

'fb_content_id' : { 'not_contains' : 'purse' }

i_contains

Contains, case-insensitive

'fb_content_id' : { 'i_contains' : 'shoe' }

i_not_contains

Not contains, case-insensitive

'fb_content_id' : { 'i_not_contains' : 'purse' }

is_any

True if event's parameter value matches any strings in given array.

'fb_content_type' : { 'is_any' : [ 'books', 'music' ] }

is_not_any

True if event's parameter value matches no strings in specified array.

'fb_content_type' : { 'is_not_any' : [ 'books', 'music' ] }

i_is_any

'is_any', case-insensitive.

'fb_content_type' : { 'i_is_any' : [ 'books', 'music' ] }

i_is_not_any

'is_not_any', case-insensitive

'fb_content_type' : { 'i_is_not_any' : [ 'books', 'music' ] }

Boolean Operators

Rules can also express AND, OR, and NOT between parameters. The default Custom Audience creation rule implicitly is AND between different clauses. You can nest boolean operators 5 levels deep. This should be expressed as:

{"_application":"12345",
 "_eventName":"myEvent",
  "boolean_operator": [ {"param1":"value1"},
                        {"param2":"value2"}] }

App Events API

Query which app events and parameters an app reported to Facebook. You can use these events and parameters directly for creating Custom Audiences. You need an access token associated with the app_id with a admin, developer, or advertiser role.

Make a HTTP GET call:

https://graph.facebook.com/<API_VERSION>/<APP_ID>/app_event_types

The response is JSON containing a data array of JSON dictionaries having these fields:

Name Description Type

event_name

App event type to use in rule

string

display_name

Human-readable name of event type

string

description

Verbose description of standard event

string

parameters

array of JSON dictionaries describing parameters for this event { "parameter_name": "fb_currency", "display_name": "Currency", "description": "Currency for event" }


parameter_name - string, App param type to use in rule


display_name - string, Human readable name of event type


description - string, Verbose description of parameter, if a standard param

array


Managing Audiences

Exclusion Targeting

Audience Create API populates audiences based on a single event. When this event occurs, Facebook adds the person to your audience. Sometimes you want to apply conditions beyond a single event such as "Added to cart but not purchased", or "Used app in the last 8 days but hasn't purchased anything". To do this, use Exclusion Targeting at the audience-level.

For example, target people who "Added to cart but not purchased" by creating two audiences: one for fb_mobile_add_to_cart event, and one for fb_mobile_purchase event. Then ad targeting your ad to the first audience and excluding the second.

Examples

Here is a rule for app id 55064006, where the event must be an fb_mobile_purchase event, the valueToSum must be 5, fb_currency is USD, and the custom repeat_purchaser parameter is 0:

{"_application":"55064006",
 "_eventName":"fb_mobile_purchase",
 "_valueToSum": 5,
 "fb_currency":"USD",
 "repeat_purchaser":"0"}

Create an audience for all mobile app purchases for app id 55064006:

curl \
-F 'name=example1' \
-F 'subtype=APP' \
-F 'retention_days=14' \
-F 'rule={"_application":"55064006", "_eventName":"fb_mobile_purchase"}' \
-F 'access_token=_____' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences/'

Create an audience for custom timeOnPanel events:

curl \
-F 'name=example2' \
-F 'subtype=APP' \
-F 'retention_days=14' \
-F 'rule={"_application":"55064006", "_eventName":"timeOnPanel"}' \
-F 'access_token=_____' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences/'

Create an audience custom timeOnPanel events where color is red, and favorite dessert is bananaSplit:

curl \
-F 'name=example3' \
-F 'subtype=APP' \
-F 'retention_days=14' \
-F 'rule={"_application":"55064006", "_eventName":"timeOnPanel", \
                      "color":"red", "favoriteDessert":"bananaSplit"}' \
-F 'access_token=_____' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences/'

Create an audience on custom timeOnPanel events where event is greater than 30, color is red or blue, and favorite dessert contains banana:

curl \
-F 'name=example4' \
-F 'subtype=APP' \
-F 'retention_days=14' \
-F 'rule={"_application":"55064006", "_eventName":"timeOnPanel", \
                      "_valueToSum": {"gt":"30"}, \
                      "color": { "is_any" : [ "red", "blue" ]}, \
                      "favoriteDessert": { "contains" : "banana" } }' \
-F 'access_token=_____' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences/'

Create an audience for custom timeOnPanel events with color red or favorite dessert set to bananaSplit:

curl \
-F 'name=example5' \
-F 'subtype=APP' \
-F 'retention_days=14' \
-F 'rule={"_application":"55064006", "_eventName":"timeOnPanel", \
                      "or": [ {"color":"red" }, \
                              {"favoriteDessert":"bananaSplit"} ] }' \
-F 'access_token=_____' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences/'

If you want to create audiences based off of multiple events, you should create multiple audiences and combine them in ad targeting. For example, create audiences of purchasers, and of people who added to cart. Then use ad targeting for people who added to cart and excludes users who have already purchased.

Include everyone who added to cart for app id 55064006:

curl \
-F 'name=add_to_cart' \
-F 'subtype=APP' \
-F 'retention_days=14' \
-F 'rule={"_application":"55064006", "_eventName":"fb_mobile_add_to_cart"}' \
-F 'access_token=_____' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences/'

The response is audience ID 12345

Include people making mobile app purchases for app id 55064006:

curl \
-F 'name=purchase' \
-F 'subtype=APP' \
-F 'retention_days=14' \
-F 'rule={"_application":"55064006", "_eventName":"fb_mobile_purchase"}' \
-F 'access_token=_____' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences/'

The response is audience ID 56789.

Include people who added-to-cart and excluse purchased:

targeting={
  'custom_audiences':[{'id':600012345,'name':'add_to_cart'}]},
  'excluded_custom_audiences':[{'id':'600056789','name':'purchase'}]
}

Resources