أدوات Google Ads: الاستهداف والجماهير والاستبعادات

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

gads_list_campaign_targeting

Kind: read. It is marked as changing nothing.

A campaign's bidding strategy, ad schedule, device bid modifiers, locations and languages (with names, criterion ids and modifiers), who a location reaches, and its settings. An empty schedule means the campaign runs at all hours; a device with no modifier bids normally, and one at 0 is excluded. No locations means it targets everywhere.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		Campaign id.

gads_search_geo_targets

Kind: read. It is marked as changing nothing.

Find the ids of places to target: countries, governorates, regions, cities. Searches the full name ("Hawalli Governorate,Kuwait"), so a country's name finds the places inside it. The geo_target_id is what gads_set_locations takes.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id (any account you can reach).
query	text	yes		Part of the place's name, in English.
country_code	text	no	none	Optional two-letter country to search within, e.g. KW.
limit	whole number	no	25	Most places to return (1-200).

gads_search_languages

Kind: read. It is marked as changing nothing.

The languages a campaign can target, with the language_id gads_set_languages takes. Without a query it lists them all.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id (any account you can reach).
query	text	no	none	Optional part of the language's English name, e.g. Arabic.

gads_list_audiences

Kind: read. It is marked as changing nothing.

Audiences. With a campaign_id: the audiences on that campaign and whether the campaign observes them or targets only them. Without one, by kind: user_lists (the account's own remarketing and other lists, with their size on Search and whether they can serve there; takes_rows marks a Customer Match list that gads_upload_customer_match can fill), in_market and affinity (Google's segments; give search, there are thousands), custom (the account's custom segments, listed only: a Search campaign does not take one from here), or saved (the audiences saved in Google Ads, each a combination of segments and lists: what gads_create_pmax_campaign takes as its audience_signal).

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
kind	one of user_lists, in_market, affinity, custom, saved	no	"user_lists"	user_lists, in_market, affinity, custom or saved.
search	text	no	none	Optional text the name must contain, e.g. "software".
campaign_id	text	no	none	List the audiences on this campaign instead.
limit	whole number	no	100	Most rows to return (default 100, at most 500).

gads_list_exclusions

Kind: read. It is marked as changing nothing.

Who and where ads are kept away from: excluded audiences, websites, YouTube channels and videos, app categories, topics and content labels, each with the criterion_id a remove takes. Always the whole account's exclusions; with campaign_id also that campaign's and those of each of its ad groups; with ad_group_id that ad group's (its campaign's exclusions hold for it as well: list the campaign to see them). Negative keywords are another list (gads_list_negative_keywords), and so are excluded locations (gads_list_campaign_targeting).

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	no	none	Also list this campaign's exclusions and its ad groups'.
ad_group_id	text	no	none	Also list this ad group's exclusions (give this or campaign_id, not both).

gads_search_content_categories

Kind: read. It is marked as changing nothing.

Find the id of one of Google's topics (what a page is about, e.g. "Games > Card Games") or mobile app categories, by a piece of its name. The id is what gads_set_content_exclusions (topics) and gads_set_placement_exclusions (app_category) take.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
kind	one of topic, app_category	yes		topic or app_category.
search	text	yes		Text the name must contain, e.g. "games".
limit	whole number	no	50	Most rows to return (default 50, at most 200).

gads_set_locations

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.

Add or remove a campaign's locations, in one transaction. add takes geo target ids from gads_search_geo_targets, targeted, or excluded with negative=true. remove takes criterion ids from gads_list_campaign_targeting and needs confirm_remove=true. Removing the campaign's last targeted location is refused: a campaign with none shows everywhere in the world.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		Campaign id.
add	list of text	no	none	Geo target ids to add.
remove	list of text	no	none	Criterion ids of locations to remove.
negative	true or false	no	false	true = the added locations are excluded rather than targeted.
bid_modifier	number	no	none	Optional bid multiplier for the added locations (1.2 is +20%); not for exclusions.
confirm_remove	true or false	no	false	Must be true when remove is given.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_set_geo_target_type

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

Choose who a campaign's locations reach. targeted: PRESENCE = people in or regularly in the location; PRESENCE_OR_INTEREST = also people elsewhere who show interest in it (Google's default, and wider); SEARCH_INTEREST = people searching for it. excluded: PRESENCE = people in the excluded location; PRESENCE_OR_INTEREST = also people showing interest in it.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		Campaign id.
targeted	one of PRESENCE_OR_INTEREST, SEARCH_INTEREST, PRESENCE	no	none	PRESENCE, PRESENCE_OR_INTEREST or SEARCH_INTEREST.
excluded	one of PRESENCE_OR_INTEREST, PRESENCE	no	none	PRESENCE or PRESENCE_OR_INTEREST.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_set_languages

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

Set the languages a campaign targets. The list is the whole answer: languages on the campaign and not in it are removed, the others added, in one transaction. An empty list is refused, since a campaign with no language targets all of them.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		Campaign id.
language_ids	list of text	yes		Every language id the campaign should target (gads_search_languages).
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_update_campaign_settings

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

Change a campaign's name, search partners, start and end dates, tracking template or URL suffix, or switch off two of Google's automations. Only what is passed changes. Removing the end date or moving it later lets the campaign spend for longer: say so to the user.

url_expansion_opt_out=true stops Google sending clicks to pages other than the ad's final URL; ai_max=false switches AI Max off. Neither can be switched ON from here.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		Campaign id.
name	text	no	none	New campaign name.
include_search_partners	true or false	no	none	Show on Google search partner sites or not.
start_date	text	no	none	New start, YYYY-MM-DD, in the account's time zone; not in the past.
end_date	text	no	none	New end, YYYY-MM-DD (the campaign runs through that day).
clear_end_date	true or false	no	false	true = no end date; the campaign runs until paused.
tracking_url_template	text	no	none	New tracking template; an empty string clears it.
final_url_suffix	text	no	none	New final URL suffix; an empty string clears it.
url_expansion_opt_out	true or false	no	none	true = opt out of final URL expansion.
ai_max	true or false	no	none	false = switch AI Max off.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_add_campaign_audience

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

Put an audience on a campaign: one of the account's user lists, or one of Google's in-market or affinity segments (gads_list_audiences finds both).

OBSERVATION leaves reach as it is: the audience only informs bidding and gets its own figures. TARGETING shows the ads ONLY to people in the campaign's audiences. That choice belongs to the campaign, so it holds for EVERY audience on it: giving a mode other than the campaign's changes them all, and the result says so. Leave mode out to keep the campaign's; a campaign that says neither is written as OBSERVATION.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		The campaign.
user_list_id	text	no	none	A user list from gads_list_audiences (give this or user_interest_id).
user_interest_id	text	no	none	An in-market or affinity segment from gads_list_audiences.
mode	one of OBSERVATION, TARGETING	no	none	OBSERVATION or TARGETING, for the whole campaign. Leave out to keep what it has.
bid_modifier	number	no	none	Optional bid multiplier for people in the audience: 1.2 is +20%, 0.8 is -20%.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_remarketing_list

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

Create a remarketing list of people who visited a page whose address contains a value, e.g. everyone who saw "/pricing" in the last 30 days. It fills from the Google tag on the site: without the tag it stays empty, and it serves on Search only once it holds about a thousand active people. A list of the advertiser's own customers is another tool: gads_create_customer_match_list.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
name	text	yes		The list's name (unique in the account).
url_contains	text	yes		Text the visited page's address must contain, e.g. /pricing or example.com/erp.
lookback_days	whole number	no	30	How long a visitor stays on the list, 1 to 540 days.
description	text	no	none	Optional note about the list.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_set_audience_exclusions

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.

Keep the people on a user list away from a campaign's or an ad group's ads, or stop excluding them. This is how a list of existing customers (a Customer Match list, or a remarketing list of buyers) is kept out of a campaign meant to find new ones. One or the other per call: add is applied item by item, so the answer may be partly_applied; remove is all or nothing and needs confirm_remove=true. The campaign's audience mode (observation or targeting) is not changed by either. A list that is an audience on the same campaign or ad group is refused, not excluded beside it. A remove takes excluded audiences only: any other criterion id is refused.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	no	none	The campaign (give this or ad_group_id).
ad_group_id	text	no	none	The ad group.
add	list of text	no	none	User list ids to exclude (gads_list_audiences lists them).
remove	list of text	no	none	criterion_ids of excluded audiences, from gads_list_exclusions.
confirm_remove	true or false	no	false	Must be true with remove, after the user asked for it.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_set_placement_exclusions

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.

Keep ads off websites, YouTube channels, YouTube videos and categories of mobile app, for a campaign, an ad group or the whole account - or stop excluding them. One or the other per call: add is applied item by item, so the answer may be partly_applied; remove is all or nothing and needs confirm_remove=true. What is already excluded there is left out and said. Which campaign types take which kind is Google's to say: its refusal is passed on as it is. A remove takes excluded placements only: any other criterion id is refused.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
level	one of campaign, ad_group, account	yes		campaign, ad_group or account (every campaign in the account).
id	text	no	none	The campaign id or ad group id; leave out for account.
add	list of Placement	no	none	List of {type, value}: type website (a host or a page address without a query), youtube_channel (the UC... channel id), youtube_video (the video id) or app_category (an id from gads_search_content_categories).
remove	list of text	no	none	criterion_ids of excluded placements, from gads_list_exclusions.
confirm_remove	true or false	no	false	Must be true with remove, after the user asked for it.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_set_content_exclusions

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.

Keep ads off kinds of content: content labels (Google's own classes of sensitive or low-quality inventory, for a campaign or the whole account) and topics (what a page is about, for a campaign or an ad group) - or stop excluding them. One or the other per call: labels and topics are added item by item, so the answer may be partly_applied; remove is all or nothing and needs confirm_remove=true. A remove takes excluded content labels and topics only: any other criterion id is refused.

Content labels: SEXUALLY_SUGGESTIVE, BELOW_THE_FOLD, PARKED_DOMAIN, JUVENILE, PROFANITY, TRAGEDY, VIDEO, VIDEO_RATING_DV_G, VIDEO_RATING_DV_PG, VIDEO_RATING_DV_T, VIDEO_RATING_DV_MA, VIDEO_NOT_YET_RATED, EMBEDDED_VIDEO, LIVE_STREAMING_VIDEO, SOCIAL_ISSUES, BRAND_SUITABILITY_CONTENT_FOR_FAMILIES, BRAND_SUITABILITY_GAMES_FIGHTING, BRAND_SUITABILITY_GAMES_MATURE, BRAND_SUITABILITY_HEALTH_SENSITIVE, BRAND_SUITABILITY_HEALTH_SOURCE_UNDETERMINED, BRAND_SUITABILITY_NEWS_RECENT, BRAND_SUITABILITY_NEWS_SENSITIVE, BRAND_SUITABILITY_NEWS_SOURCE_NOT_FEATURED, BRAND_SUITABILITY_POLITICS, BRAND_SUITABILITY_RELIGION.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
level	one of campaign, ad_group, account	yes		campaign, ad_group (topics only) or account (content labels only).
id	text	no	none	The campaign id or ad group id; leave out for account.
labels	list of text	no	none	Content labels to exclude, from the list above.
topics	list of text	no	none	Topic ids to exclude (gads_search_content_categories finds them).
remove	list of text	no	none	criterion_ids of excluded content labels or topics, from gads_list_exclusions.
confirm_remove	true or false	no	false	Must be true with remove, after the user asked for it.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

Objects the arguments take

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

Placement

One place to keep ads off.

Field	Type	Required	Default	Description
type	one of website, youtube_channel, youtube_video, app_category	yes
value	text (1 to 2048 characters)	yes		website: a host or a page address without a query, e.g. example.com or example.com/games. youtube_channel: the channel id (UC...) or its youtube.com/channel/ address. youtube_video: the 11-character video id or the video's address. app_category: a category id from gads_search_content_categories.