إصدار ‏‎Graph API‎‏

Custom Conversions

Optimize ads delivery based on online and offline conversion events that you define. Track activity without adding new events Meta Pixel. Custom conversions objects are associated with an Ad Account. Use them to describe events you want to measure and events you want to track to optimize ads delivery.

Specify actions that are different from the nine standard events. See also Facebook Pixel, Conversion Tracking with Facebook Pixel and Promoted Object.

You need standard API access for this endpoint. See Marketing API, Access Levels.

For example, define a PURCHASE conversion as an event occuring when someone visits certain pages such as thankyou.html or confirmation.html:

curl \
-F 'name=URL based Custom Conversion' \
-F 'event_source_id=<FB_PIXEL_ID>' \
-F 'rule={"or":[{"url":{"i_contains": "thankyou.html"}},{"url":{"i_contains":"confirmation.html"}}]}' \
-F 'custom_event_type=PURCHASE' \
-F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customconversions'

In this example, events occur if someone visits those two .html pages, case-insensitive of the page name and extention.

Limitations

Note that the maximum number of custom conversions you can have per ad account is 100.

If you use the Ads Insights API to get metrics on custom conversions, be aware of these limitations:

Getting product ID breakdowns are not supported.
Getting unique action counts are not supported.

قراءة

Custom conversions on Facebook allows you to optimize and track actions without having to add anything to your Facebook pixel base code. They also allow you to optimize for and track actions that are different from the 9 standard events that come with the Facebook pixel.

بدءًا من 14 سبتمبر 2021، ستعرض الحقول التالية خطأ بالنسبة لاستدعاءات الإصدار 12.0 والإصدارات الأحدث التي تم إجراؤها بواسطة التطبيقات التي تفتقر إلى أذونات نقطة النهاية المطلوبة. علمًا بأن هذا التغيير سينطبق على جميع الإصدارات اعتبارًا من 13 ديسمبر 2021.

pixel

List of custom conversions for an account:

curl -G \
-d 'fields=["pixel","rule","custom_event_type"]' \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customconversions

المعلمات

لا تحتوي نقطة النهاية هذه على أي معلمات.

الحقول

الحقل	الوصف
`id` numeric string	ID of the custom conversion
`account_id` string	Ad Account ID assoicated to this custom conversion
`business` Business	Business that owns the custom conversion
`creation_time` datetime	Time at which the conversion was created
`custom_event_type` enum {ADD_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, COMPLETE_REGISTRATION, CONTENT_VIEW, INITIATED_CHECKOUT, LEAD, PURCHASE, SEARCH, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, LISTING_INTERACTION, FACEBOOK_SELECTED, OTHER}	The type of the conversion event, e.g. PURCHASE
`data_sources` list<ExternalEventSource>	Event sources of the custom conversion
`default_conversion_value` integer	When conversion is URL based, the default conversion value associated to each conversion
`description` string	Description of the custom conversion
`event_source_type` enum	Event source type of the custom conversion, e.g. pixel, app, etc.
`first_fired_time` datetime	Time at which the pixel was first fired
`is_archived` bool	Whether this conversion is archived. Archived conversions are no longer tracked in the system
`is_unavailable` bool	Whether this conversion is unavailable
`last_fired_time` datetime	Time at which the pixel was last fired
`name` string	Name of the custom conversion
`pixel` AdsPixel	The pixel that will send events
`retention_days` unsigned int32	Retention period for advanced rule
`rule` string	Rule of the custom conversion

عناصر الربط

حد الشبكة الخلوية الوصف

حد الشبكة الخلوية	الوصف
`stats` Edge<CustomConversionStatsResult>	Stats data for this conversion

stats

Edge<CustomConversionStatsResult>

Stats data for this conversion

‎Error Codes‎

خطأ	الوصف
100	Invalid parameter
368	The action attempted has been deemed abusive or is otherwise disallowed

إنشاء

When you create a custom conversion, provide rule with these operators and data:

Name	Description
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 (eg: `"example\.com.*purchase$"`). The full PCRE grammar is supported
Data	The data being filtered.
`url`	The full escaped URL of the site visited
`event`	The name of the pixel event fired from your website. Example: `Purchase`

Examples

Defines a high-value PURCHASE when someone triggers the Purchase standard event and purchase value is greater than 100:

curl \
-F 'name=High value Purchase Custom Conversion' \
-F 'event_source_id=<FB_PIXEL_ID>' \
-F 'rule={"and":[{"event":{"eq": "Purchase"}},{"value":{"gt":100}}]}' \
-F 'custom_event_type=PURCHASE' \
-F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customconversions'

Define a custom event then build a custom conversion for it. Specify a PURCHASE conversion that to track when a user-defined, item-sold custom event occurs. Track when someone purchases an item in a certain color.

Step 1: Define item-sold custom event in Facebook pixel on your website:

fbq('trackCustom', 'item-sold', {
   color: 'black',
   value: 1.00,
   currency: 'USD'
});

Step 2: Provide a PURCHASE conversion for the item-sold custom event for a given color by specifying it as a custom parameter:

curl \
-F 'name=Item Sold Custom Conversion' \
-F 'event_source_id=<FB_PIXEL_ID>' \
-F 'rule={"and":[{"event":{"eq": "item-sold"}},{"color":{"i_contains":"black"}}]}' \
-F 'custom_event_type=PURCHASE' \
-F 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customconversions'

‎You can make a POST request to claim_custom_conversions edge from the following paths:

/{business_id}/claim_custom_conversions

‎

‎When posting to this edge, a CustomConversion will be created.‎

المعلمات

معلمة الوصف

معلمة	الوصف
`custom_conversion_id` numeric string or integer	Custom conversion ID the business claims. مطلوب

custom_conversion_id

numeric string or integer

Custom conversion ID the business claims.

مطلوب

‎Return Type‎

Struct {

success: bool,

}

‎Error Codes‎

خطأ	الوصف
100	Invalid parameter

‎You can make a POST request to customconversions edge from the following paths:

/act_{ad_account_id}/customconversions

‎

‎When posting to this edge, a CustomConversion will be created.‎

المعلمات

معلمة	الوصف
`action_source_type` enum{app, chat, email, other, phone_call, physical_store, system_generated, website, business_messaging}	action source type the custom conversion is created from
`advanced_rule` string	Advanced ruleset for the custom conversion being created allowing multiple sources.
`custom_event_type` enum {ADD_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, COMPLETE_REGISTRATION, CONTENT_VIEW, INITIATED_CHECKOUT, LEAD, PURCHASE, SEARCH, CONTACT, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION, SUBSCRIBE, LISTING_INTERACTION, FACEBOOK_SELECTED, OTHER}	The custom event type of the conversion being created
`default_conversion_value` float	القيمة الافتراضية: ‏`0`‏ The default conversion value of the conversion being created
`description` string	The description of the conversion being created
`event_source_id` numeric string or integer	Event source ID, where event sources are pixel, offline event sets and so on. Aggregate custom conversion data from these sources.
`name` string	The name of the conversion being created مطلوب
`rule` string	Only count an event as a custom conversion if it fulfills this rule.

‎Return Type‎

‎This endpoint supports ‎read-after-write‎ and will read the node represented by id in the return type.‎

Struct {

id: numeric string,

is_custom_event_type_predicted: numeric string,

}

‎Error Codes‎

خطأ	الوصف
100	Invalid parameter
200	Permissions error
190	Invalid OAuth 2.0 Access Token

جارٍ التحديث

‎You can update a CustomConversion by making a POST request to /{custom_conversion_id}.‎

المعلمات

معلمة الوصف

معلمة	الوصف
`default_conversion_value` float	The default conversion value of the conversion being created
`description` string	Description of the custom conversion
`name` string	Name of the custom conversion

default_conversion_value

float

The default conversion value of the conversion being created

description

string

Description of the custom conversion

name

string

Name of the custom conversion

‎Return Type‎

‎This endpoint supports ‎read-after-write‎ and will read the node to which you POSTed.‎

Struct {

success: bool,

}

‎Error Codes‎

خطأ	الوصف
100	Invalid parameter

جارٍ الحذف

‎You can delete a CustomConversion by making a DELETE request to /{custom_conversion_id}.‎

المعلمات

لا تحتوي نقطة النهاية هذه على أي معلمات.

‎Return Type‎

Struct {

success: bool,

}

‎Error Codes‎

خطأ	الوصف
200	Permissions error
100	Invalid parameter