Custom Audiences from Your Website

Create a custom audience of users who visited or took specific actions on your website using Facebook Pixel, JavaScript Tag API, and audience rules. See Custom Audience, Targeting', Facebook Tag API, Facebook Pixel Stats, Website Custom Audiences with Facebook Pixel.

Once you create a custom audience with website data, reference it in ad targeting as you do with standard custom audiences. Facebook automatically updates this audience based on the retention policy you setup.

Before You Begin

Code samples and rules below show old website custom audience pixel code; however, you should upgrade to Facebook pixel. See Website Custom Audiences with Facebook Pixel.

Create a Custom Audience Pixel

Use the following API call to create a Custom Audience Pixel:

curl -X POST \ -F 'name="My WCA Pixel"' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/act_<AD_ACCOUNT_ID>/adspixels
const adsSdk = require('facebook-nodejs-ads-sdk'); const AdAccount = adsSdk.AdAccount; const AdsPixel = adsSdk.AdsPixel; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'My WCA Pixel', }; let adspixels = (new AdAccount(id)).createAdsPixel( fields, params ); logApiCallResult('adspixels api call complete.', adspixels);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdsPixel; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'My WCA Pixel', ); echo json_encode((new AdAccount($id))->createAdsPixel( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebookads.adobjects.adaccount import AdAccount from facebookads.adobjects.adspixel import AdsPixel from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'My WCA Pixel', } print AdAccount(id).create_ads_pixel( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAdsPixel() .setName(\"My WCA Pixel\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adspixels = ad_account.adspixels.create({ name: 'My WCA Pixel', })

This returns the pixel ID:

{
  "id": "11111"
}

Read the Pixel Code

Then retrieve the Custom Audience Pixel code:

curl -X GET \ -d 'fields="code"' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/<PIXEL_ID>/
const adsSdk = require('facebook-nodejs-ads-sdk'); const AdsPixel = adsSdk.AdsPixel; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ 'code', ]; params = { }; let sample_code = (new AdsPixel(id)).get( fields, params ); logApiCallResult('sample_code api call complete.', sample_code);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdsPixel; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( 'code', ); $params = array( ); echo json_encode((new AdsPixel($id))->getSelf( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebookads.adobjects.adspixel import AdsPixel from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ 'code', ] params = { } print AdsPixel(id).get( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdsPixel(id, context).get() .requestCodeField() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ads_pixel = FacebookAds::AdsPixel.get(id ,'code')

This returns the following, where code contains the relevant Custom Audience Pixel code:

{
  "data": [
    {
      "code": "<script>(function() {\n  var _fbq = window._fbq || (window._fbq = []);\n  if (!_fbq.loaded) {\n    var fbds = document.createElement('script');\n    fbds.async = true;\n    fbds.src = 'https://connect.facebook.net/en_US/fbds.js';\n    var s = document.getElementsByTagName('script')[0];\n    s.parentNode.insertBefore(fbds, s);\n    _fbq.loaded = true;\n  }\n  _fbq.push(['addPixelId', '11111']);\n})();\nwindow._fbq = window._fbq || [];\nwindow._fbq.push(['track', 'PixelInitialized', {}]);\n</script>\n<noscript><img height=\"1\" width=\"1\" alt=\"\" style=\"display:none\" src=\"https://www.facebook.com/tr?id=11111&amp;amp;ev=NoScript\" /></noscript>", 
      "id": "11111"
    }
  ], 
  "paging": {
    "cursors": {
      "before": "MjM4NzQ5Njk5NjI2Mzc2", 
      "after": "MjM4NzQ5Njk5NjI2Mzc2"
    }
  }
}

Create an Audience

IMPORTANT: To create a Custom Audience using this method, the account needs to have already accepted the Terms of Service for Custom Audiences, in Ads Manager:

curl -X POST \ -F 'name="My Test Website Custom Audience"' \ -F 'rule={ "inclusions": { "operator": "or", "rules": [ { "event_sources": [ { "id": "<PIXEL_ID>", "type": "pixel" } ], "retention_seconds": 8400, "filter": { "operator": "and", "filters": [ { "field": "url", "operator": "i_contains", "value": "shoes" } ] } } ] } }' \ -F 'prefill=1' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/act_<AD_ACCOUNT_ID>/customaudiences
const adsSdk = require('facebook-nodejs-ads-sdk'); const AdAccount = adsSdk.AdAccount; const CustomAudience = adsSdk.CustomAudience; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'My Test Website Custom Audience', 'rule' : {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pixelID>','type':'pixel'}],'retention_seconds':8400,'filter':{'operator':'and','filters':[{'field':'url','operator':'i_contains','value':'shoes'}]}}]}}, 'prefill' : '1', }; let customaudiences = (new AdAccount(id)).createCustomAudience( fields, params ); logApiCallResult('customaudiences api call complete.', customaudiences);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\CustomAudience; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'My Test Website Custom Audience', 'rule' => array('inclusions' => array('operator' => 'or','rules' => array(array('event_sources' => array(array('id' => '<pixelID>','type' => 'pixel')),'retention_seconds' => 8400,'filter' => array('operator' => 'and','filters' => array(array('field' => 'url','operator' => 'i_contains','value' => 'shoes'))))))), 'prefill' => '1', ); echo json_encode((new AdAccount($id))->createCustomAudience( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebookads.adobjects.adaccount import AdAccount from facebookads.adobjects.customaudience import CustomAudience from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'My Test Website Custom Audience', 'rule': {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pixelID>','type':'pixel'}],'retention_seconds':8400,'filter':{'operator':'and','filters':[{'field':'url','operator':'i_contains','value':'shoes'}]}}]}}, 'prefill': '1', } print AdAccount(id).create_custom_audience( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createCustomAudience() .setName(\"My Test Website Custom Audience\") .setRule(\"{\\"inclusions\\":{\\"operator\\":\\"or\\",\\"rules\\":[{\\"event_sources\\":[{\\"id\\":\\"<pixelID>\\",\\"type\\":\\"pixel\\"}],\\"retention_seconds\\":8400,\\"filter\\":{\\"operator\\":\\"and\\",\\"filters\\":[{\\"field\\":\\"url\\",\\"operator\\":\\"i_contains\\",\\"value\\":\\"shoes\\"}]}}]}}\") .setPrefill(true) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) customaudiences = ad_account.customaudiences.create({ name: 'My Test Website Custom Audience', rule: {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<pixelID>','type':'pixel'}],'retention_seconds':8400,'filter':{'operator':'and','filters':[{'field':'url','operator':'i_contains','value':'shoes'}]}}]}}, prefill: '1', })

These parameters are most relevant for custom audiences from your website:

Name Description Type Required

name

The name for the cluster.

String

Yes

rule

Audience rules to be applied on the referrer URL.

string

Yes

Audience Rules

A custom audience from a website must contain at least one audience rule.

The rules are applied on either the referrer URL or specific events and data sent via Tag API. Rules determine whether someone should be added to this custom audience. Learn more about key components in Audience Rule Syntax.

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. For example, the following rule has three leaf nodes:
  • If you have audiences created before v3.0 using a syntax not supported by v3.0 rules, then the audience cannot be correctly rendered. On the other hand, if you have audiences created prior to v3.0 using syntax that is supported by v3.0 rules, then the audience can be rendered and you can update it.

To view the deprecated, pre-v3.0 rules and the rules as of v3.0, see Audience Rules, Deprecated and Audience Rules.

{
    "aggregation" : {
        "type" : count,
        "method" : absolute,
        "operator" : >=,
        "value" : 2
    },
    "event_sources" : [{"type" : pixel, "id" : 1441930299172957}],
    "filter" : {
        "operator" : and,
        "filters" : [
            {
                "field" : url,
                "operator" : i_contains,
                "value" : url,
            },
            {
                "operator" : or,
                "filters" : [
                    {
                        "field" : url,
                        "operator" : i_contains,
                        "value" : include,
                    },
                    {
                        "field" : url,
                        "operator" : i_contains,
                        "value" : people,
                    },
                ],
             },
         ],
    },
}

Some key components of Audiences rules are:

For for full examples of these components in action, see Example Custom Audience Rules.

Audience Rule Syntax

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

rule: {
   "inclusions": <RULE_SET>,
   "exclusions": <RULE_SET>,}
Name Description Type Required

inclusions

Rule Set JSON string that defines the inclusion

String

Yes

exclusions

Rule set JSON string that defines the inclusion

String

No

A custom audience for Website Custom Audiences must contain an audience rule. Each rule must be provided as a JSON-encoded string.

Inclusion/Exclusion Rule Syntax

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

The aggregation and retention_seconds are editable fields. However, editing aggregation and retention_seconds does not flush the audience. People who only match the old rule/aggregation continue to be in the audience until they expire.

Name Description Type Required

event_sources

JSON object containing the id (Pixel ID) and type (pixel)

String

Yes

retention_seconds

Integer (in seconds) for the retention window of the audience. Min=1; Max=365 days

Integer

Yes

filter

JSON string of the filter rules; see Filters

String

No

aggregation

JSON string of the aggregation functions; see Aggregate Functions

Integer

No

Filter

Filtration follows this general format:

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

Filter Rules

{
    "field": <FIELD>,
    "operator": <COMPARISON_OPERATOR>,
    "value": <VALUE>,
}
Name Description Type Required

field

Use "event" if the filter is to specify an event. Parameters that match events sent by pixel (for example, 'ViewContent', 'Purchase')

String

Yes

comparison operator

"="("eq"), "!="("neq"), ">="("gte"), ">"("gt"), "<="("lte"), "<"("lt"), "i_contains", "i_not_contains", "contains", "not_contains", "is_any", "is_not_any", "i_is_any", "i_is_not_any", "i_starts_with", "starts_with", "regex_match"[INFO]. If "field" is set to "event", must use "="

String

Yes

value

If the field attribute is set to "event", the value must be set to an event name. Use the App Event API to see app events and parameters reported by the app.

String

Yes

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}
Name Description Type Required

type

The aggregation function type: “count” “sum” “avg” “min” “max” "time_spent" "last_event_time_field"

String

Yes

method

"absolute", meaning add people that logged events in specified range, or "percentile", meaning add people from a specified percentile range. If you select percentile, the operator should only be in_range and not_in_range.

String

No

field

The parameter on which the aggregation function is applied.

String

No

comparison operator

=, !=, >=, >, <=, <, in_range, not_in_range

String

Yes

value

Expected value of the parameter.

String

Yes

Comparison Operators

Operator Description

">" or "gt"

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

">=" or "gte"

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

"<" or "lt"

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

"<=" or "lte"

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

"=" or "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' }.

"!=" or "neq"

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

"contains"

True if event's parameter value, as string, contains specified string. Value of "shoe12345" fulfills 'contains' if specified value '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'.

"i_contains"

Contains, case-insensitive

"i_not_contains"

Not contains, case-insensitive

"is_any"

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

"is_not_any"

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

"i_is_any"

'is_any', case-insensitive.

"i_is_not_any"

'is_not_any', case-insensitive

"starts_with"

True is the event's parameter value starts with the given string

"i_starts_with"

"starts_with", case-insensitive

"regex_match"

Matches a regular expression such as \"example\.com.*purchase$\". The full PCRE grammar is supported

Example Rules

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"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Operators and Data or Events

Rules have the following operators and data or events:

Operators The type of filter

i_contains

Contains substring, case insensitive

i_not_contains

Does not contain substring, case insensitive

contains

Contains substring, case sensitive

not_contains

Does not contain substring, case sensitive

eq

Equal to, case sensitive

neq

Not equal to, case sensitive

lt

Less than, numeric fields only

lte

Less than or equal to, numeric fields only

gt

Greater than, numeric fields only

gte

Greater than or equal to, numeric fields only

regex_match

Matches a regular expression such as \"example\\.com.*purchase$\". The full PCRE grammar is supported

Data Data being filtered

url

Fully escaped URL of the site visited

domain

Domain of site visited

path

Path of site visited, excluding domain

event

Name of pixel event, such as 'ViewContent'

device_type

Device that accessed site: desktop

mobile_android_phone

mobile_android_tablet

mobile_ipad

mobile_ipod

mobile_iphone

mobile_tablet

mobile_windows_phone

any customData field

Any field added to customData for pixel fires, such as productId, category, price

Provide each rule as a JSON-encoded string.

Audience Rules, deprecated

Use this content for audience rules prior to v3.0.

A custom audience from a website must contain at least one audience rule. As of 2.8 you can only provide up to 200 comparison operators in a rule for an audience.

The rules are applied on either the referrer URL or specific events and data sent via Tag API. Rules determine whether someone should be added to this custom audience.

Rules have the following operators and data or events:

Operators The type of filter

i_contains

Contains substring, case insensitive

i_not_contains

Does not contain substring, case insensitive

contains

Contains substring, case sensitive

not_contains

Does not contain substring, case sensitive

eq

Equal to, case sensitive

neq

Not equal to, case sensitive

lt

Less than, numeric fields only

lte

Less than or equal to, numeric fields only

gt

Greater than, numeric fields only

gte

Greater than or equal to, numeric fields only

regex_match

Matches a regular expression such as \"example\\.com.*purchase$\". The full PCRE grammar is supported

Data Data being filtered

url

Fully escaped URL of the site visited

domain

Domain of site visited

path

Path of site visited, excluding domain

event

Name of pixel event, such as 'ViewContent'

device_type

Device that accessed site: desktop

mobile_android_phone

mobile_android_tablet

mobile_ipad

mobile_ipod

mobile_iphone

mobile_tablet

mobile_windows_phone

any customData field

Any field added to customData for pixel fires, such as productId, category, price

Provide each rule as a JSON encoded string.

Example Rules

Rule Description
{  
  "url": {  
    "i_contains": "shoes"  
  }  
}

Match all referring URLs containing the string shoes

{  
  "url": {  
    "i_not_contains": "shoes"  
  }  
}

Match all referring URLs not containing the string shoes

{
  "and": [
    {"event": {"i_contains": "ViewContent"}},
    {"price": {"gte": 100}}
  ]
}

Match ViewContent events where item price is greater than or equal to $100. Consider using this rule for the following event:

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

{
  "or": [
    {"url": {"i_contains": "shoes"}},
    {"and": [
      {"event":{"i_contains":"ViewContent"}},
      {"category":{"i_contains":"shoes"}}
    ]}
  ]
}

Match either referring URLs containing the string shoes or ViewContent events where category contains the string shoes

{
  "and": [
    {"url":{"i_contains":"shoes"}},
    {"url":{"i_contains":"type=25"}}
  ]
}

Match all referring URLs containing 'shoes' and 'type=25'

{
  "or": [
    {"url":{"i_contains":"shoes"}},
    {"url":{"i_contains":"boots"}}
  ]
}

Match all referring URLs containing either shoes or boots

{
  "and": [
    {"or": [
      {"url":{"i_contains":"shoes"}},
      {"url":{"i_contains":"boots"}}
    ]},
    {"or": [
      {"url":{"i_contains":"mybrand"}},
      {"url":{"i_contains":"otherbrand"}}
    ]}
  ]
}

Match all referring URLs containing at least one of shoes or boots, AND at least one of 'mybrand' or 'otherbrand'

Filtering and Operators

There are several filters, combined with operators you can use when you define an audience.

  • Field: claim_objective
  • Operators: EQUAL
  • Values: enum {AUTO_OFFER, HOME_LISTING, PRODUCT, TRAVEL, VEHICLE}

For example:

act_ID/customaudiences?fields=name&filtering=[{field:'claim_objective', 
operator: 'EQUAL', 
value: 'TRAVEL'}]
}
act_ID/customaudiences?fields=data_source&fields=name,data_source&filtering=[{field: 'data_source.subtype', 
operator: 'IN', 
value: [3002]}]    
  • Field: delivery_status.code
  • Operators: IN
  • Values: [(200 | 300 | 400 | 401)]
act_ID/customaudiences?fields=name, 
delivery_status&filtering= 
[{field:'delivery_status.code', 
operator: 'IN', 
value: [200, 300]}]
  • Field: name
  • Operators: CONTAIN
  • Values: Any string
act_ID/customaudiences?fields=name&filtering= 
[{field:'name', 
operator: 'CONTAIN', 
value: 'Test'}]
act_ID/customaudiences?fields=name,operation_status&filtering=[{field:'operation_status.code', 
operator: 'IN', 
value: [200]}]
  • Field: rule
  • Operators: CONTAIN
  • Values: Any string
act_ID/customaudiences?fields=name,rule&filtering= \[{field:'rule', 
operator: 'CONTAIN', 
value: '\"event_name\":\"page_engaged\"'}]
  • Field: subtype
  • Operators: EQUAL, NOT_EQUAL, IN, NOT_IN
  • Values: enum {CUSTOM, WEBSITE, APP, OFFLINE_CONVERSION, CLAIM, PARTNER, MANAGED, VIDEO, LOOKALIKE, ENGAGEMENT, DATA_SET, BAG_OF_ACCOUNTS, STUDY_RULE_AUDIENCE, FOX}
act_ID/customaudiences?fields=name,subtype&filtering=[{field: 'subtype', 
operator: 'EQUAL', 
value: 'LOOKALIKE'}]
act_ID/customaudiences?fields=name,subtype&filtering= 
[{field:'subtype', 
operator: 'NOT_EQUAL', 
value: 'ENGAGEMENT'}]
act_ID/customaudiences?fields=name,subtype&filtering= 
[{field:'subtype', 
operator: 'IN', 
value: ['CUSTOM', 'ENGAGEMENT']}]
act_ID/customaudiences?fields=name,subtype&filtering= 
[{field:'subtype', 
operator: 'NOT_IN', 
value: ['CUSTOM', 'ENGAGEMENT']}]

Enhanced Website Custom Audiences, deprecated

For any version prior to 3.0, this a new feature that is not yet available to all advertisers. Please report bugs and provide feedback to your technical contact. Currently you may only create 20 Enhanced Website Custom Audiences per ad account.

This introduces additional flexibility to create custom audiences. You can now create targeting rules from aggregate behavior, device type and dynamic date, which is in beta. For background, see Website Custom Audiences with Custom Audience Pixel.

Editable Fields

rule, rule_aggregation and retention_days are editable fields. However if you edit rule, rule_aggregation or retention_days, you do not remove any audience members. This means that after Facebook adds someone who only matched an old rule, rule_aggregation and retention_days, that audience members continues to be in the audience until we reach the expiration for that member.

Aggregate Functions

Create custom audiences based upon the frequency and intensity of behavior using the rule_aggregation field. With this, you define an aggregate function. For example:

rule_aggregation={"type":"sum", "config":{"field":"price"}, "operator":">", "value": "100"}

Aggregation rules are made up the following fields:

Name Description

type

The type of the aggregation function: count, sum, avg, max, min, time_spent, last_event_time_field.

config

Required by certain types of aggregation functions.

operator

  • =
  • >
  • >=
  • <
  • <=
  • !=
  • @> - Time between delivery time and time passed by the pixel is longer than the value. Namely, now - pass-in-time > value.
  • @< - Time between delivery time and the time passed by the pixel is shorter than the value: now - pass-in-time < value.

value

Integer. Units for time_spent and last_event_time_field are seconds.

The available functions are:

Name Required Config Description

count

Number of pixel fires that satisfy the rule, such as url contains Purchase.

sum

{“field”: “field_name”}

Accumulate values of the specified field sent by pixel events.

avg

{“field”: “field_name”}

Average value of specified field sent by pixel events.

max

{“field”: “field_name”}

Maximum value of specified field sent by pixel events.

min

{“field”: “field_name”}

Minimum value of the specified field sent by pixel events.

time_spent

Total time spent in seconds on URLs that satisfy the rule.

last_event_time_field (beta)

{“field”: “checkin_date”, “time_format”: “YYYY-MM-DD”}

Used in dynamic date rules. The value of the specified field must be a valid time in the specified time format. For example, in this case, time format is YYYY-MM-DD, so {checkin date: 2015-08-28} is valid but {checkin date: 20150828} is invalid.

Examples

All website visitors in the past 30 days, who visited more than 5 times:

curl 
-F "name=visit_more_than_5_times_in_30_days" 
-F "pixel_id=PIXEL_ID" 
-F "subtype=WEBSITE" 
-F "retention_days=30" 
-F 'rule={"url":{"i_contains":"&amp;lt;url>"}}' 
-F 'rule_aggregation={"type":"count", "operator":">", "value": "5"}' 
-F "access_token=ACCESS_TOKEN" 
"https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/customaudiences"  

All website visitors who spent more than 5 minutes in past 180 days on your website:

curl 
-F "name=spent_more_than_5_mins_in_180_days" 
-F "pixel_id=PIXEL_ID" 
-F "subtype=WEBSITE" 
-F "retention_days=180" 
-F 'rule={"url":{"i_contains":"&amp;lt;url>"}}' 
-F 'rule_aggregation={"type":"time_spent", "operator":">", "value": "300"}' 
-F "access_token=ACCESS_TOKEN" 
"https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/customaudiences"

Users who spent more than $500 on your website in the last 30 days:

curl 
-F "name=spent_more_than_$500_in_30_days" 
-F "pixel_id=PIXEL_ID" 
-F "subtype=WEBSITE" 
-F "retention_days=30" 
-F 'rule={"and": [
{"event": {"i_contains": "purchase"}},
{"currency": {"eq": "USD"}}
]}' 
-F 'rule_aggregation={"type":"sum", "config":{"field":"price"}, "operator":">", "value": "500"}' 
-F "access_token=ACCESS_TOKEN" 
"https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/customaudiences"

Users who spent at least $100 in one transaction in last 30 days:

curl 
-F "name=spent_at_least_$100_in_one_session_in_30_days" 
-F "pixel_id=PIXEL_ID" 
-F "subtype=WEBSITE" 
-F "retention_days=30" 
-F 'rule={"and": [
{"event": {"i_contains": "purchase"}},
{"currency": {"eq": "USD"}}
]}' 
-F 'rule_aggregation={"type":"min", "config":{"field":"price"}, "operator":">", "value": "100"}' 
-F "access_token=ACCESS_TOKEN" 
"https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/customaudiences"

Users who made 3 or more purchases in the last 30 days:

curl 
-F "name=3_or_more_purchases" 
-F "pixel_id=PIXEL_ID" 
-F "subtype=WEBSITE" 
-F "retention_days=15" 
-F 'rule={"event":{"i_contains":"purchase"}}' 
-F 'rule_aggregation={"type":"count", "operator":">=", "value": "3"}' 
-F "access_token=ACCESS_TOKEN" 
"https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/customaudiences"

Device Type Targeting

Enhanced Website Custom Audiences introduces the ability to create targeting based upon device type a website is visited from. The supported device types are:

  • desktop
  • mobile_android_phone
  • mobile_android_tablet
  • mobile_ipad
  • mobile_ipod
  • mobile_iphone
  • mobile_phone
  • mobile_tablet
  • mobile_windows_phone

Examples

Android Users:

curl 
-F "name=android_users" 
-F "pixel_id=<PIXEL_ID>" 
-F "subtype=WEBSITE" 
-F "retention_days=180" 
-F 'rule={
  "or":[
    {"device_type":{"eq":"mobile_android_phone"}},
    {"device_type":{"eq":"mobile_android_tablet"}}
  ]
}' 
-F "access_token=ACCESS_TOKEN" 
"https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/customaudiences"

Desktop Users:

curl 
-F "name=mobile_visitors" 
-F "pixel_id=PIXEL_ID" 
-F "subtype=WEBSITE" 
-F 'rule={"device_type":{"eq":"desktop"}}' 
-F "access_token=ACCESS_TOKEN" 
"https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/customaudiences"

Dynamic Date (beta)

This enables travel advertisers to target users who searched for hotels and flights based upon the users check-in date. For instance an advertiser can create an audience that only targets users with a check-in dates in the future.

Travel advertisers should provide the intended check-in date in the checkin_date field for pixel fires:

fbq('track', 'Search', {'checkin_date': '2015-09-15', 'num_of_travelers':2});  

Supported Time formats

Currently only the ISO-8601 time format is supported. For example:

  • YYYYMMDD (eg 20080921)
  • YYYY-MM-DD (eg 1997-07-16)
  • YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+0100)
  • YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+0100)

Where:

  • YYYY is the four-digit year
  • MM is the two-digit month (01=January, etc.)
  • DD is the two-digit day of month (01 through 31)
  • hh is the two digits of hour (00 through 23) (am/pm NOT allowed)
  • mm is the two digits of minute (00 through 59)
  • ss is the two digits of second (00 through 59)
  • TZD is the time zone designator (+hhmm or -hhmm)

Examples

Users who searched for a hotel with start_date later than today in the last 30 days:

curl 
-F "name=search_hotel_later_than_today" 
-F "pixel_id=PIXEL_ID" 
-F "subtype=WEBSITE" 
-F "retention_days=30" 
-F 'rule={"event": {"i_contains": "search"}}' 
-F 'rule_aggregation={"type":"last_event_time_field", "config":{"field":"checkin_date", "time_format":"YYYY-MM-DD"}, "operator":"@&amp;lt;", "value": "0"}' 
-F "access_token=ACCESS_TOKEN" 
"https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/customaudiences"

Best Practices

  • Experiment with different potential measures of value, for example, people who visit the site frequently but have not purchased or people who visit the site with multiple devices.
  • Create Lookalike Audiences based on the best performing custom audiences.

Custom Audiences from Your Website FAQ

Q: How do I use Custom Audiences from your website?

A: Reach people who recently visited your website and deliver them highly relevant ads based on interest they express in your products.

Q: What are the benefits of Custom Audiences from your website?

A:

  • Remarket to people using your website
  • Make your existing ads more efficient by excluding audiences of people who have already converted on your message
  • Create lookalike audiences of people who look like the people browsing your website

By tracking how each customer progresses in a process, you can more effectively influence customers who expressed interest in your products. For example, using Facebook Pixel, capture intent based on activity of people who are viewing pages about a loyalty program, browsing a particular product page, or filling out a preferences form. Later, you can serve relevant ads to these people to help them complete the conversion.

Q: How do I create a Website Custom Audiences?

A: See Advertiser Help Center, Custom Audience from your Website

Q: How do I edit an existing Website Custom Audience?

A: See Advertiser Help Center, Custom Audience from your Website. When you add or remove people, updates can take a few hours. But, your ads continue to run.

If you edit the audience rules, the new rules only apply to people added from that moment forward. The previous rules continue to apply to existing people in the Website Custom Audience.

Q: How many audiences can I create?

A: At this time, there's a maximum of 10000 Custom Audiences from your website that can be created in a single account.

Q: Can I exclude a Website Custom Audience from my ad targeting?

A: Yes. Exclusion targeting prevents a particular audience from seeing your ad to help deliver your advertising more precisely. For example, exclude an audience of your current customers if you run a campaign to acquire new customers.

In Ads Manager, in the audience section of creating an ad, click Exclude and add the custom audience to the list.

Q: How long will customers stay in my website custom audience?

A: The longest duration can be set for 365 days. After 365 days, audience members are removed, unless they revisit the website again and match the same audience rule.

Q: Can I create a Lookalike Audience of a Website Custom Audience?

A: Yes. Open Ad Manager. Under the Audiences tab, click the New Audience drop-down menu and select Lookalikes.

Q: Can Dating & Gambling clients use Custom Audiences from your website?

A: Dating can use Custom Audiences from your website. However, gambling websites must be approved through the sales team on a managed list, and you must provide demographic restrictions, such as 21 years+.

Q: What bid type should we use for Custom Audiences from your website?

A: We recommend CPM bidding for Website Custom Audience until your audience has reached a sufficiently large size. Start with CPM, then migrate to oCPM or CPC once you reach sufficient scale.

Q: Can I access mobile and web inventory with Custom Audiences from your website?

A: Yes, Custom Audiences from your website works with all native ad formats and serves across desktop, mobile, and tablet.

Q: How does Custom Audiences from Your Website relate to FBX?

A: FBX and Website Custom Audiences are complementary products. FBX is best when advertisers require product-level dynamic ads, which are as current as possible and are not yet easily facilitated by Custom Audiences from your website. However, FBX is limited to desktop inventory. Custom Audiences from your website allows targeting across browsers, overlaying of Facebook data, access to mobile inventory, and usage of all Facebook ad units—all of which are not available on FBX.

Q: What is user retention based on?

A: Custom Audiences from Your Website requests a duration where customers will be retained within the audience created. The duration is based on when customers visited a website and fired the pixel. For example, with a retention window of 30 days, if someone visits a website and matches an Audience rule on June 1st, Facebook automatically removes them from the Website Custom Audience on June 30.

Q: Can we apply more complex rules for sophisticated clients?

A: You can create rules based on URLs visited or on custom events from Facebook pixel. Using custom data, create audiences based upon SKUs, Pricing, Color, or any other attribute you send to Facebook. See Facebook pixel.

Q: What privacy features are in Custom Audiences from your website?

A: No personal information is reported to the advertiser about any individual person on a website. You can only target an audience once it reaches a certain size; it's impossible to learn the individual identity an any person visiting a website.

Facebook also provides an AdChoices link where people can learn more and opt out of targeted ads they receive. Click the “x” in the top-right corner of ads to show more options:

  • Hide this ad—Don't see this ad again (Facebook native). This is specific to the ad ID in the campaign only.

  • Hide all ads—Don't see any other ads from that advertiser (Facebook native). Hide any ads from either that subdomain, such as savings.att.com or att.com, or the page facebook.com/ATT if we have it. Block the sub-domain or page across ad accounts.

  • Why Am I seeing this Ad?

Q: Are View Tags allowed with Custom Audiences from your website?

A: View Tags are not yet permitted for Custom Audiences from your website clients. Only Atlas view tag are accepted at this time.

Q: Can Website Custom Audiences be shared with another account or FBMP?

A: Yes, it's possible to share Website Custom Audiences.

Q: If I delete a Website Custom Audience, what happens to my campaign that's targeting this Website Custom Audience?

A: If an Active campaign targets a Website Custom Audience and that audience is deleted, the campaign is put on Pause.

Q: How quickly does my audience update?

A: We update an audience as soon as technically possible. Once customers go to webpages with a Facebook pixel and match an Audience rule, they're added to that Website Custom Audience. If this Website Custom Audience is being targeted with an ad, the customer is eligible to be served an ad in a matter of minutes.

Q: Do I have to add a new Facebook pixel to my website every time I create an audience?

A: No. There's one Facebook pixel generated per account. Add this Facebook pixel to all pages of your website one at a time, and use Audience rules to create different Website Custom Audiences.

Q: Can I use a Facebook pixel with another third-party tag?

A: Yes. You can use data from third-party tags, Tag Managers, or a DFA Floodlight tag. This depends on the sophistication of the third-party client. Simple rules are easy to implement, but if you pass dynamic variables through the JS event, your third-party tag should receive them and pass them to the Facebook pixel via Custom Data fields.

Q: Can I use the IMG only version of the pixel?

A: Yes, you can use the IMG only portion of the pixel.

Q: What are other benefits of using the JavaScript version of Facebook pixel?

A: The full JavaScript version has the following advantages over the IMG-only pixel:

  • It's cross-browser and cross-platform.
  • It's fast and loads asynchronously so it doesn't block the page load.
  • Built-in cache buster increases effectiveness.
  • You can send custom data with large payloads using HTTP POST.
  • It captures the original page URL when the pixel is placed in a tag container

Q: What is a pixel ID?

A: A pixel ID is an identifier of the piece of code placed on an advertiser's website. There's one pixel ID per Facebook Ad account.

Q: How to obtain a Facebook pixel through the API?

A: See Facebook Pixel.

Q: Where should I place Facebook pixel in my website?

A: See Facebook Pixel.

Q: How can I fire Custom Data events using fbq?

A: See Facebook Pixel, with Website Custom Audiences.

Q: How do I refer to custom data in Custom Audiences from your website rules?

A: In your rules, refer to event names under the parameter 'event'. For rules based on custom data, refer to it the same way you do for referring URLs, under the parameter 'url'. For example, to matches all visitors:

  • to URLs containing 'signup', or
  • associated with event 'SignUp' by fbq.push(['track', 'SignUp']);
"filter": {
    "operator": "or",
    "filters": [
        {
            "field": "url",
            "operator": "i_contains",
            "value": "signup"
        }
        {
            "field": "event",
            "operator": "i_contains",
            "value": "SignUp"
        }
    ]
}

The following rule matches all visitors who have viewed any product in the TV category by fbq.push(['track', 'ViewProduct', {category: 'TV'}]);.

"filter": {
    "operator": "or",
    "filters": [
        {
            "field": "event",
            "operator": "i_contains",
            "value": "ViewProduct"
        }
        {
            "field": "category",
            "operator": "i_contains",
            "value": "TV"
        }
    ]
},

Q: How to track conversion events?

A: The above examples shows how to track remarketing events. Use the same way to track conversion events by replacing eventName with conversion ID. This ID is created during the regular conversion creation flow (https://www.facebook.com/ads/manage/convtrack.php).

window.fbq = window.fbq || [];
fbq.push(['track', 123456, {currency: 'USD', value: 30.00}]);

Ideally, you don't need to know whether a fired event is a conversion event or a remarketing event. You only need the conversion ID to fire a conversion event. For example, if the old conversion pixel is:

var fb_param = {};
fb_param.pixel_id = '1234567890';
fb_param.value = '5.00';
fb_param.currency = 'USD';
(elided other code)

Then, using the new pixel, it is the following:

window.fbq = window.fbq || [];
fbq.push(['track', 1234567890, {currency: 'USD', value: 5.00}]);

The old conversion pixel allowed either a conversion pixel or a remarketing pixel on a page. Facebook pixel allows multiple pixel firings, including multiple conversion events, multiple remarketing events, or both per page.

Q: How do you use an image only version of the pixel?

A: Manually insert an IMG tag:

<img height="1" width="1" border="0" alt="" style="display:none"
  src="https://www.facebook.com/tr?id=pixel_ID/ad_account_id&amp;ev=event name&amp;cd[p1]=v1&amp;cd[p2]=v2..." />

Custom data is represented as key-value pairs. Each parameter is inside 'cd[...]'. For example:

<img height="1" width="1" border="0" alt="" style="display:none"
  src="https://www.facebook.com/tr?id=1234&amp;ev=ViewProduct
       &amp;cd[category]=TV" />

Is equivalent to the following JS call:

window.fbq = window.fbq || [];
fbq.push(['track', 'ViewProduct', {category: 'TV'}]);

Q: How do you use an image pixel to fire conversion events?

A: Use parameter 'ev' to specify conversion ID, parameter 'cd[value]' to specify value, and parameter 'cd[currency]' to specify currency:

<img height="1" width="1" border="0" alt="" style="display:none"
  src="https://www.facebook.com/tr?id=1234&amp;ev=1234567890
       &amp;cd[value]=5.00&amp;cd[currency]=USD" />

Q: When to use image pixel?

A: Facebook pixel code tries to fire events using JavaScript first. If JavaScript isn't available, Facebook pixel code tries to use image pixel. However it's recommended to always use the JavaScript pixel:

  • Can be fired multiple times on each page load.
  • Can control when an event should be fired such as on a button click.
  • Not subject to HTTP GET limit` in sending custom data.