أدوات Meta Ads: القياس والضوابط

في هذه الصفحة 11 أداة. هذه الصفحة مولَّدة آليًا من قائمة الأدوات في الخادم نفسه، الإصدار 0.1.0، ولا تُحرَّر باليد. أوصاف الأدوات مكتوبة للمساعد الذكي، وهي بالإنجليزية ولم تُترجم، فكل ما تحت هذه الفقرة بالإنجليزية كما يقرؤه المساعد الذكي. لا تحتاج إلى معرفة اسم أي أداة لتطلب عملًا: هذه الصفحة مرجع لمن يريد أن يعرف ما تأخذه كل أداة بالضبط. صفحة كل الأدوات تسرد الصفحات كلها.

meta_ads_list_pixels

Kind: read. It is marked as changing nothing.

List the Meta pixels (datasets) of an ad account, and when each last reported a visit to the website. A pixel_id from here is what a website audience, a custom conversion and an ad's conversion tracking take.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
limit	whole number	no	25	Rows per page (1-100).
after	text	no	none	next_after from the previous page.

meta_ads_pixel_events

Kind: read. It is marked as changing nothing.

Count what a Meta pixel reported over the last days: how often each event fired (by "event"), or the same fires by where they came from. Use it to check that a pixel is installed and that the event a campaign optimises for is really arriving.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
pixel_id	text	yes		From meta_ads_list_pixels.
by	text	no	"event"	"event" (default: PageView, Lead, ...), "event_source", "host" (the website's domain), "url" or "device_type".
days	whole number	no	7	How many days back, 1-28. Default 7.

meta_ads_list_custom_conversions

Kind: read. It is marked as changing nothing.

List the custom conversions of a Meta ad account: each one's rule, the pixel it counts on and when it last fired.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
limit	whole number	no	25	Rows per page (1-100).
after	text	no	none	next_after from the previous page.

meta_ads_get_ab_test_results

Kind: read. It is marked as changing nothing.

Report on a Meta A/B test: each side with its spend, reach, clicks, leads, conversations and their cost over the test's days. Meta's API names no winner, so compare the sides on the cost of the result the campaign is for, and wait for the test to end.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		The ad account the tested campaigns or ad sets are in.
study_id	text	yes		From meta_ads_create_ab_test.

meta_ads_list_rules

Kind: read. It is marked as changing nothing.

List the automated rules of a Meta ad account: what each watches, what it does when its conditions hold, how often it runs and whether it is enabled.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
limit	whole number	no	25	Rows per page (1-100).
after	text	no	none	next_after from the previous page.

meta_ads_get_billing_summary

Kind: read. It is marked as changing nothing.

What a Meta ad account has spent, what it owes, its own spending limit and how much is left before that limit stops every ad. Totals only: no payment method, invoice or charge is read. Amounts are in the account's currency units.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.

meta_ads_create_custom_conversion

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create a Meta custom conversion: a name for some of a pixel's events, such as "demo request sent" for visits to the thank-you page. It spends nothing, and its rule cannot be changed afterwards.

The dry run is this server's own preflight: Meta has no validate-only mode for a custom conversion and has not seen it, so do not call it validated.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
name	text	yes		The custom conversion's name.
pixel_id	text	yes		One of the ad account's pixels, from meta_ads_list_pixels.
category	text	yes		What it counts as: LEAD, CONTACT, COMPLETE_REGISTRATION, SUBMIT_APPLICATION, SCHEDULE, START_TRIAL, SUBSCRIBE, PURCHASE, ADD_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, INITIATED_CHECKOUT, CONTENT_VIEW, SEARCH, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION or OTHER.
pixel_event	text	no	none	Only this pixel event, e.g. Lead or PageView.
url_contains	list of text	no	none	Only on an address containing any of these parts, e.g. ["/thank-you"]. Give pixel_event, url_contains or both.
description	text	no	none	A note kept with it.
dry_run	true or false	no	true	true = check here without sending anything (default). false = create it, only after the user confirms.

meta_ads_create_ab_test

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create a Meta A/B test between two to five campaigns, or ad sets, that already exist: for its duration Meta divides the audience evenly between them, so that they can be compared fairly. It switches nothing on and changes no budget.

The dry run is this server's own preflight: Meta has not seen the test, so do not call it validated.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
name	text	yes		The test's name.
level	text	yes		"campaign" or "adset" - what object_ids are.
object_ids	list of text	yes		The sides, 2 to 5 ids from meta_ads_list. They should differ in one thing.
start_time	text	yes		When the test starts, ISO 8601 with an offset, in the future.
end_time	text	yes		When it ends.
description	text	no	none	A note kept with the test.
dry_run	true or false	no	true	true = check here without sending anything (default). false = create it, only after the user confirms.

meta_ads_create_rule

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create an automated rule on a Meta ad account: on a schedule, Meta checks every campaign, ad set or ad against the conditions and pauses the ones that meet all of them, or sends a notification. It is always created DISABLED and does nothing until meta_ads_set_rule_status enables it.

A rule made here can only pause or notify. One that switches things on, or changes a budget or a bid, would act with nobody confirming it and is not offered. The dry run is this server's own preflight: Meta has not seen the rule, so do not call it validated.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
name	text	yes		The rule's name.
level	text	yes		"campaign", "adset" or "ad" - what the rule watches and acts on.
conditions	list of Condition	yes		1 to 5, all of which must hold. Each is {metric, operator, value}: metric spent, impressions, reach, clicks, ctr, cpc, cpm or frequency; operator GREATER_THAN or LESS_THAN. spent, cpc and cpm are in the account's currency units.
action	text	no	"PAUSE"	"PAUSE" (default) or "NOTIFICATION".
period	text	no	"LAST_7_DAYS"	The days the metrics are counted over: TODAY, YESTERDAY, LAST_3_DAYS, LAST_7_DAYS (default), LAST_14_DAYS, LAST_30_DAYS or LIFETIME.
schedule	text	no	"DAILY"	How often Meta checks: DAILY (default), HOURLY or SEMI_HOURLY.
object_ids	list of text	no	none	Only these campaigns, ad sets or ads (up to 10). Left out, all of them.
dry_run	true or false	no	true	true = check here without sending anything (default). false = create it, only after the user confirms.

meta_ads_set_rule_status

Kind: write. It only previews the change unless dry_run is false. Removing needs confirm_remove to be true as well. Not offered while the server is in read-only mode.

Enable, disable or delete an automated rule of a Meta ad account.

An ENABLED rule acts by itself on its schedule, so enabling is always its own step: show the user what the rule does (the dry run shows it) and enable only after they confirm. Only a rule that pauses or notifies can be enabled from here. DISABLED stops a rule and can be undone. DELETED cannot be undone and needs confirm_remove=true.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
rule_id	text	yes		From meta_ads_list_rules or meta_ads_create_rule.
status	text	yes		"ENABLED", "DISABLED" or "DELETED".
confirm_remove	true or false	no	false	Must be true to delete, and only when the user asked for a delete.
dry_run	true or false	no	true	true = preflight only (default). false = make the change, after the user confirms.

meta_ads_set_account_spend_cap

Kind: write. It only previews the change unless dry_run is false. Removing needs confirm_remove to be true as well. Not offered while the server is in read-only mode.

Set or remove a Meta ad account's own spending limit: the total the account may spend, after which Meta stops every ad on it. For administrators of this installation only.

The limit counts spend from when it was last set or reset. A limit at or below what the account has already spent stops everything at once; the dry run says how much is left. Meta allows ten changes a day. The dry run is this server's own preflight.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
spend_cap	number	no	none	The new limit, in the account's currency units (500, not 50000).
remove	true or false	no	false	true to take the limit away instead. Needs confirm_remove=true.
confirm_remove	true or false	no	false	Must be true to remove the limit, and only when the user asked.
dry_run	true or false	no	true	true = preflight only (default). false = make the change, after the user confirms.

Objects the arguments take

An argument whose type is a name takes an object with these fields.

Condition

One thing that must be true of a campaign, ad set or ad for a rule to act on it.

Field	Type	Required	Default	Description
metric	one of spent, impressions, reach, clicks, ctr, cpc, cpm, frequency	yes		spent, cpc and cpm are amounts in the ad account's currency units; ctr is a percentage.
operator	one of GREATER_THAN, LESS_THAN	yes
value	number	yes