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 Ads Manager. 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:

curl -X POST \ -F 'name=My Test Website Custom Audience' \ -F 'subtype=WEBSITE' \ -F 'retention_days=15' \ -F 'rule={"url":{"i_contains":"shoes"}}' \ -F 'prefill=1' \ -F 'pixel_id=<PIXEL_ID>' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v2.11/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 fields = [ ]; const params = { 'name' : 'My Test Website Custom Audience', 'subtype' : 'WEBSITE', 'retention_days' : '15', 'rule' : {'url':{'i_contains':'shoes'}}, 'prefill' : '1', 'pixel_id' : '<pixelID>', }; (new AdAccount(id)).createCustomAudience( fields, params ) .then((result) => { customaudiences_id = result.id; console.log(customaudiences_id); }) .catch((error) => { console.log(error); });
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', 'subtype' => 'WEBSITE', 'retention_days' => '15', 'rule' => array('url' => array('i_contains' => 'shoes')), 'prefill' => '1', 'pixel_id' => '<pixelID>', ); echo json_encode((new AdAccount($id))->createCustomAudience( $fields, $params )->getResponse()->getContent(), 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', 'subtype': 'WEBSITE', 'retention_days': '15', 'rule': {'url':{'i_contains':'shoes'}}, 'prefill': '1', 'pixel_id': '<pixelID>', } 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\") .setSubtype(CustomAudience.EnumSubtype.VALUE_WEBSITE) .setRetentionDays(15L) .setRule(\"{\\"url\\":{\\"i_contains\\":\\"shoes\\"}}\") .setPrefill(true) .setPixelId(\"<pixelID>\") .execute(); } }
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) ad_account.customaudiences.create({ name: 'My Test Website Custom Audience', subtype: 'WEBSITE', retention_days: '15', rule: {'url':{'i_contains':'shoes'}}, prefill: '1', pixel_id: '<pixelID>', })

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:

curl -X GET \ -d 'fields=id' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.0/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 fields = [ 'id', ]; const params = { }; (new AdAccount(id)).getCustomAudiences( fields, params ) .then((result) => { customaudiences_id = result[0].id; console.log(customaudiences_id); }) .catch((error) => { console.log(error); });
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( 'id', ); $params = array( ); echo json_encode((new AdAccount($id))->getCustomAudiences( $fields, $params )->getResponse()->getContent(), 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 = [ 'id', ] params = { } print AdAccount(id).get_custom_audiences( 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).getCustomAudiences() .requestField(\"id\") .execute(); } }
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) ad_account.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:

curl -X POST \ -F 'name=Updated Name for CA' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.0/<CUSTOM_AUDIENCE_ID>/
const adsSdk = require('facebook-nodejs-ads-sdk'); 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 fields = [ ]; const params = { 'name' : 'Updated Name for CA', }; (new CustomAudience(id)).update( fields, params ) .then((result) => { sample_code_id = result.id; console.log(sample_code_id); }) .catch((error) => { console.log(error); });
require __DIR__ . '/vendor/autoload.php'; 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' => 'Updated Name for CA', ); echo json_encode((new CustomAudience($id))->update( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
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': 'Updated Name for CA', } print CustomAudience(id).update( 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 CustomAudience(id, context).update() .setName(\"Updated Name for CA\") .execute(); } }
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 custom_audience = FacebookAds::CustomAudience.get(id) custom_audience..create( name: 'Updated Name for CA', )

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
}