Audience Rules

Audience rules determine whether someone is added your custom audience. The rules are applied on either the referrer URL or specific events and data.

Provide your rules as JSON-encoded strings structured like so:

• One audience rule contains two rule sets.
• Each rule set can contain an inclusion or exclusion rule.
• Each inclusion or exclusion rule can contain filters and aggregation functions.
• Each filter contains a filter set.

Use audience rules for different types of custom audiences, including Website Custom Audiences, Mobile App Custom Audiences, and Offline Custom Audiences. For Engagement Audience Rules, see Engagement Custom Audiences.

Limitations

• Each audience can specify up to 10 rules in the audience rule. This includes the number of rules in inclusions or exclusions.
• Each rule can specify up to 100 filters, known as leaf nodes.

Audience Rules Syntax

To define an audience rule, the following structure must be followed:

rule: {
   "inclusions": <RULE_SET>,
   "exclusions": <RULE_SET>,
}

Available Fields

Rule Set Syntax

For each rule set, follow this structure:

{
  "operator" : <BOOLEAN_OPERATOR>,
  "rules" : <JSON_RULE>,
}

Available Fields

Inclusion And Exclusion Rule Syntax

For each inclusion or exclusion rule, follow this structure:

{
  "event_sources" : <EVENT_SOURCE_DEFINITION>, 
  "retention_seconds" : <SECONDS>,
  "filter" : <FILTER>,
  "aggregation" : <AGGREGATION>, 
}

Available Fields

Filters

Filtration follows this general format:

"filter" : {
  "operator": <BOOLEAN_OPERATOR>,
  "filters": <FILTER_SET>,
  }

Available Fields

Filter Set Syntax

{
    "field": <FIELD>,
    "operator": <COMPARISON_OPERATOR>,
    "value": <VALUE>,
}

Available Fields

Aggregate Functions

Create custom audiences based upon the frequency and intensity of behavior using the aggregation in the audience rule field. With this, you define an aggregate function, for example:

"aggregation" : {
  "type":"count",
  "operator":">",
  "value":1
}

Available Fields

For example:

"aggregation" : {
  "type":"count",
  "operator":">",
  "value":1
}

Comparison Operators

Examples

Website Custom Audiences

Match all referring URLs containing the string shoes in the last 30 days:

{
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "pixel",
                        "id": "<PIXEL_ID>",
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "url",
                            "operator": "i_contains",
                            "value": "shoes"
                        }
                    ]
                },
            }
        ]
    }
}

Match ViewContent events where item price is greater than or equal to USD 100 in the last 30 days. Consider using this rule for the following event:

_fbq.push([ 'track', 'ViewContent', { productId: 1234, category: 'Men > Shoes', price: 199 } ]);

{
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "pixel",
                        "id": "<PIXEL_ID>"
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "ViewContent"
                        },
                        {
                            "operator": "or",
                            "filters": [
                                {
                                    "field": "price",
                                    "operator": ">=",
                                    "value": "100"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Mobile App Custom Audiences

See Mobile App Custom Audiences, Example Custom Audience Rules.

Operators and Data or Events

Rules have the following operators and data or events:

Provide each rule as a JSON-encoded string.