Website Custom Audiences with Facebook Pixel

Create website custom audiences targeting people on your website. After you create a custom audience, use it in ad targeting as you do with standard custom audiences. Facebook automatically adds or removes people from audiences following the retention policy you setup.

For a website custom audience pixel, see Custom Audiences from your Website. We recommend that you upgrade to Facebook Pixel.

Create Audience

To create a Custom Audience from Websites, you must accept the Terms of Service for Custom Audiences, in Power Editor. Then make an HTTP POST:

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

Use these parameters:

Name Description Type Required

name

Audience name.

String

Yes

subtype

Must be set to WEBSITE.

String

Yes

rule

Audience rules applied to referring URL.

JSON Object

Yes

retention_days

Number of days to retain someone in audience. Between 1 and 180 days. Default 14 days.

Int

Yes

prefill

true - Include website activity recorded before audience creation.


false - Only include website traffic from the time of audience creation.

Boolean

No


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::PIXEL_ID => <PIXEL_ID>,
  CustomAudienceFields::NAME => 'My New Website Custom Audience',
  CustomAudienceFields::SUBTYPE => CustomAudienceSubtypes::WEBSITE,
  CustomAudienceFields::RETENTION_DAYS => 15,
  CustomAudienceFields::RULE => array('url' => array('i_contains' => 'shoes')),
  CustomAudienceFields::PREFILL => true,
));
$custom_audience->create();
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.customaudience import CustomAudience

ad_account = AdAccount(fbid='act_<AD_ACCOUNT_ID>')
audience = ad_account.create_custom_audience(params={
    CustomAudience.Field.name: 'My New Website Custom Audience',
    CustomAudience.Field.subtype: CustomAudience.Subtype.website,
    CustomAudience.Field.retention_days: 15,
    CustomAudience.Field.rule: {'url': {'i_contains': 'shoes'}},
    CustomAudience.Field.pixel_id: <PIXEL_ID>,
})
CustomAudience customAudience = new AdAccount(act_<AD_ACCOUNT_ID>, context).createCustomAudience()
  .setPixelId(<PIXEL_ID>)
  .setName("My New Website Custom Audience")
  .setSubtype(CustomAudience.EnumSubtype.VALUE_WEBSITE)
  .setRetentionDays(15L)
  .setRule("{\"url\":{\"i_contains\":\"shoes\"}}")
  .setPrefill(true)
  .execute();
curl \
  -F 'pixel_id=<PIXEL_ID>' \
  -F 'name=My New Website Custom Audience' \
  -F 'subtype=WEBSITE' \
  -F 'retention_days=15' \
  -F 'rule={"url":{"i_contains":"shoes"}}' \
  -F 'prefill=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/customaudiences

Response:

{
  "id": "123567890"
}

Audience Rules

The rules determine whether someone is added your audience. You can apply rules on referring URLs or on specific events sent by Tag API. A custom audience from a website must contain at least one audience rule. Provide rules as JSON-encoded strings. Rules contain the following operators and events:

Operators Filter type

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

Equals, 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$\". Supports full PCRE grammar

Data Data to filter

url

Fully-escaped URL of site visited

domain

Domain of site visited

path

Path of site visited, without the domain

event

Name of pixel event such as 'ViewContent'. See Facebook Pixel, Standard Events.

any customData field

Any field added to customData such as productId, category, price

Examples

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 greater than or equal to $100.

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

Match either referring URL containing the string shoes or AddToCart 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 referring URLs containing at least one of shoes or boots, AND at least one of 'mybrand' or 'otherbrand'

Managing Audiences

To read audiences for an ad account make an HTTP GET:

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

Example:

use FacebookAds\Object\AdAccount;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$audiences = $account->getCustomAudiences();
APINodeList<CustomAudience> customAudiences = new AdAccount(act_<AD_ACCOUNT_ID>, context).getCustomAudiences()
  .execute();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/customaudiences

Response:

{
  "data": [
    {
      "name": "My Test CA", 
      "id": "1234567890"
    }, 
    {
      "name": "WCA", 
      "id": "0987654321"
    },
  ],
}

To read a specific custom audience:

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

$custom_audience = new CustomAudience(<CUSTOM_AUDIENCE_ID>);
$custom_audience->read(array(
  CustomAudienceFields::NAME,
  CustomAudienceFields::RULE,
));
from facebookads.adobjects.customaudience import CustomAudience

audience = CustomAudience('<CUSTOM_AUDIENCE_ID>')
audience.remote_read(fields=[
    CustomAudience.Field.name,
    CustomAudience.Field.rule,
])
CustomAudience customAudience2 = new CustomAudience(<CUSTOM_AUDIENCE_ID>, context).get()
  .requestNameField()
  .requestRuleField()
  .execute();
curl -G \
  -d 'fields=name,rule' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CUSTOM_AUDIENCE_ID>

Response:

{
  "name": "My WCA", 
  "rule": "{\"and\": [\n\t\t{\"url\": {\"i_contains\": \"shoes\"}},\n\t\t{\"url\": {\"i_contains\": \"red\"}}]}", 
  "id": "1234567890"
}

To update a custom audience name:

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

$audience = new CustomAudience(<CUSTOM_AUDIENCE_ID>);

$audience->setData(array(
  CustomAudienceFields::NAME => 'Updated Name for CA',
));

$audience->update();

echo $audience->{CustomAudienceFields::NAME}.PHP_EOL;
from facebookads.adobjects.customaudience import CustomAudience

audience = CustomAudience('<CUSTOM_AUDIENCE_ID>')
audience[CustomAudience.Field.name] = 'Updated name for CA'
audience.remote_update()
new CustomAudience(<CUSTOM_AUDIENCE_ID>, context).update()
  .setName("Updated Name for CA")
  .execute();
curl \
  -F 'name=Updated Name for CA' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CUSTOM_AUDIENCE_ID>

Response:

{
  "success": true
}

Delete an audience by id:

use FacebookAds\Object\CustomAudience;

$custom_audience = new CustomAudience(<CUSTOM_AUDIENCE_ID>);
$custom_audience->deleteSelf();
from facebookads.adobjects.customaudience import CustomAudience

audience = CustomAudience('<CUSTOM_AUDIENCE_ID>')
audience.remote_delete()
new CustomAudience(<CUSTOM_AUDIENCE_ID>, context).delete()
  .execute();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CUSTOM_AUDIENCE_ID>/

Response:

{
  "success": true
}