أدوات Google Ads: Display و Performance Max و Demand Gen والفيديو

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

gads_list_asset_groups

Kind: read. It is marked as changing nothing.

The asset groups of a Performance Max campaign: each with its status, Google's ad strength and what Google says would improve it, its final URL, every asset linked to it (texts, images, videos, with the field type each is used as, whether it is serving, and whether the advertiser or Google made it) and its signals (audiences and search themes). The asset_id and field_type of an asset are what gads_update_asset_group removes it by. For how each asset group or asset performed, use gads_pmax_report.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		A Performance Max campaign's id.

gads_search_brands

Kind: read. It is marked as changing nothing.

Find brands by the start of their name, as Google knows them, with the id a brand exclusion names (gads_set_brand_exclusions) and the brand's websites, to tell two brands of one name apart.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
text	text	yes		The start of the brand's name, at least two characters.

gads_list_brand_lists

Kind: read. It is marked as changing nothing.

The account's brand lists, with how many brands each holds. With campaign_id: which of them that campaign excludes. With brand_list_id: that list's brands as well.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	no	none	Optional campaign, to say which lists it excludes.
brand_list_id	text	no	none	Optional single list to show with its brands.

gads_get_video_upload

Kind: read. It is marked as changing nothing.

The state of a video uploaded to YouTube with gads_upload_video, or of every upload the account has made through the API when no upload_id is given. States: PENDING (still uploading), UPLOADED (YouTube is processing it), PROCESSED (ready: its video_id can be made an asset with gads_create_youtube_video_asset), FAILED, REJECTED (validation or policy; Google's API gives no further reason) and UNAVAILABLE (removed from YouTube). Use it when gads_upload_video answered before processing had finished.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
upload_id	text	no	none	The upload's id, from gads_upload_video. Left out: every upload, newest first.

gads_create_video_campaign

Kind: read. It is marked as changing nothing.

NOT AVAILABLE: this tool always refuses and changes nothing. Google does not let a Video campaign be created or changed through the Google Ads API. YouTube ads are made as a Demand Gen campaign instead: gads_create_demand_gen_campaign, gads_create_demand_gen_ad_group and gads_create_demand_gen_ad (kind=video), with gads_upload_video to put a video file on YouTube first. Call those; this one exists only so that asking for a Video campaign by name gets this answer.

Argument	Type	Required	Default	Description
customer_id	text	no	none	Ignored.
name	text	no	none	Ignored.

gads_create_display_campaign

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

Create a Display campaign with a budget of its own, its locations and its languages, in one transaction. Display shows image ads on websites, in apps and on YouTube to people who are NOT searching: who sees them is decided by the campaign's locations and languages and by what each ad group targets. The campaign is always created PAUSED. It shows nothing until it has an ad group (gads_create_display_ad_group) with an ad (gads_create_responsive_display_ad) and is enabled with gads_set_campaign_status.

Locations and languages are required: a campaign without them shows everywhere, to everyone.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
name	text	yes		Campaign name (must be unique in the account).
daily_budget	number	yes		Daily budget in account currency units.
bidding	one of MAXIMIZE_CONVERSIONS, TARGET_CPA, MAXIMIZE_CLICKS, MANUAL_CPC	yes		MAXIMIZE_CONVERSIONS (optional target_cpa), TARGET_CPA (target_cpa required), MAXIMIZE_CLICKS (optional cpc_bid_ceiling) or MANUAL_CPC (the ad group's bid).
locations	list of text	yes		Geo target ids to show in (gads_search_geo_targets). At least one.
languages	list of text	yes		Language ids to target (gads_search_languages). At least one.
target_cpa	number	no	none	Target cost per conversion, in account currency.
cpc_bid_ceiling	number	no	none	The most MAXIMIZE_CLICKS may bid for a click, in account currency.
start_date	text	no	none	Optional start, YYYY-MM-DD, in the account's time zone; not in the past.
end_date	text	no	none	Optional end, YYYY-MM-DD (the campaign runs through that day).
contains_eu_political_advertising	true or false	no	false	true only if the campaign carries political advertising aimed at the European Union; Google requires the declaration either way.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_display_ad_group

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

Create an ad group in a Display campaign together with what it targets, in one transaction. The ads show ONLY to what is listed here, within the campaign's locations and languages; each kind listed narrows the others (an audience AND a topic), and several of one kind widen it (this topic OR that one). Show the user the whole list before applying.

optimized_targeting is OFF unless the call says true. With it on, Google shows the ads to people and on places beyond this list, wherever it expects conversions: the list becomes a hint, not a boundary. Google's own default is on, so this writes it off by name, as a second logged step right after the ad group is made. Turn it on only when the user asked for it.

An ad group with nothing targeted and optimized targeting off would show to everyone in the campaign's locations, so it is refused. The ad group is created PAUSED unless the installation allows new ads to start enabled.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		The Display campaign to create it in.
name	text	yes		Ad group name (unique in the campaign).
audiences	list of text	no	none	User list ids to target (gads_list_audiences, kind user_lists).
interests	list of text	no	none	In-market or affinity segment ids to target (gads_list_audiences).
placements	list of Placement	no	none	Where to show: {type, value} with type website, youtube_channel, youtube_video or app_category (ids from gads_search_content_categories).
topics	list of text	no	none	Topic ids to target (gads_search_content_categories).
keywords	list of text	no	none	Display keywords: pages about these words. Broad match only, as Display has it.
optimized_targeting	true or false	no	false	true = let Google show the ads beyond what is listed (see above).
default_cpc_bid	number	no	none	Optional max CPC bid in account currency, used under MANUAL_CPC.
status	one of ENABLED, PAUSED	no	none	PAUSED or ENABLED; leave out to follow the installation's setting.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_set_optimized_targeting

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

Switch optimized targeting off or on for one ad group. Off: the ads show only to what the ad group targets. On: Google also shows them to people and on places beyond that, wherever it expects conversions, so reach and spend are no longer bounded by the targeting. Switch it on only when the user asked for exactly that; switching it off is never refused.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
ad_group_id	text	yes		The ad group (gads_list_ad_groups).
enabled	true or false	yes		false = off, true = on.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_responsive_display_ad

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

Create a responsive display ad in a Display ad group: Google assembles it from these texts and images into whatever size a page or an app has room for. The images come from your media library by media_id and nowhere else (an image at a URL is added first with meta_add_media); each is measured here before anything is sent, and the image assets and the ad are made in one transaction. The ad is created PAUSED unless the installation allows new ads to start enabled. Google's asset enhancements and auto-generated video are not opted into. The dry run is Google's own check, policy included, so show the user what Google said.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
ad_group_id	text	yes		The Display ad group (gads_list_ad_groups).
headlines	list of text	yes		1 to 5 short headlines, each up to 30 characters.
long_headline	text	yes		One long headline, up to 90 characters.
descriptions	list of text	yes		1 to 5 descriptions, each up to 90 characters.
business_name	text	yes		The advertiser's name as shown, up to 25 characters.
marketing_images	list of text	yes		Landscape images, 1.91:1 and at least 600x314: media ids. At least one.
square_images	list of text	yes		Square images, 1:1 and at least 300x300: media ids. At least one. With the landscape ones, 15 at most.
final_url	text	yes		The landing page, a full http(s) address.
logos	list of text	no	none	Optional logos, square (at least 128x128) or 4:1 (at least 512x128): media ids, up to 5.
call_to_action_text	text	no	none	Optional button text, e.g. "Learn more"; Google keeps a list per language.
status	one of ENABLED, PAUSED	no	none	PAUSED or ENABLED; leave out to follow the installation's setting.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_pmax_campaign

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

Create a Performance Max campaign and its first asset group, in one transaction: a budget of its own, the campaign, its locations and languages, the business name and logos, the asset group with its texts, images and videos, and its signals. Google takes nothing less, so ask the user for ALL of it up front.

Tell the user what Performance Max is before applying: Google decides where the ads show (Search, YouTube, Display, Discover, Gmail, Maps), who sees them and how the texts and images are combined. This server can hold it to the daily budget, the target, the locations and the languages, and to nothing else. Signals are hints, not limits.

The campaign is always created PAUSED. Google's automations for it are all written off: its own headlines and descriptions, image cropping and retouching, images taken from the landing page, reworked videos, and final URL expansion. final_url_expansion=true lets Google send clicks to other pages of the site and write texts for them (Google ties its text customisation to it, so both go on); pass it only when the user asked for that.

contains_eu_political_advertising has no default: ask the user, do not assume.

Images come from the media library by media_id and nowhere else (an image at a URL is added first with meta_add_media); each is measured here before anything is sent.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
name	text	yes		Campaign name (must be unique in the account).
daily_budget	number	yes		Daily budget in account currency units. Its own budget, never a shared one.
bidding	one of MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE	yes		MAXIMIZE_CONVERSIONS (optional target_cpa) or MAXIMIZE_CONVERSION_VALUE (optional target_roas). Performance Max takes no other.
locations	list of text	yes		Geo target ids to show in (gads_search_geo_targets). At least one.
languages	list of text	yes		Language ids to target (gads_search_languages). At least one.
final_url	text	yes		The landing page, a full http(s) address.
business_name	text	yes		The advertiser's name as shown, up to 25 characters.
headlines	list of text	yes		3 to 15 headlines, each up to 30 characters.
long_headlines	list of text	yes		1 to 5 long headlines, each up to 90 characters.
descriptions	list of text	yes		2 to 5 descriptions, each up to 90 characters; one of them 60 or fewer.
marketing_images	list of text	yes		Landscape images, 1.91:1 and at least 600x314: media ids. 1 to 20.
square_images	list of text	yes		Square images, 1:1 and at least 300x300: media ids. 1 to 20.
logos	list of text	yes		Logos: media ids, 1 to 5. At least one square (1:1, at least 128x128); the others square or wide (4:1, at least 512x128).
contains_eu_political_advertising	true or false	yes		true only if the campaign carries political advertising aimed at the European Union. Required: the user states it.
target_cpa	number	no	none	Target cost per conversion, in account currency (MAXIMIZE_CONVERSIONS).
target_roas	number	no	none	Target return on ad spend as a ratio: 4.0 means 400% (MAXIMIZE_CONVERSION_VALUE).
portrait_images	list of text	no	none	Optional portrait images, 4:5 and at least 480x600: media ids, up to 20.
videos	list of text	no	none	Optional YouTube videos, by id or address, up to 15. Without one Google may make a video from the images and texts.
audience_signal	text	no	none	Optional id of a saved audience (gads_list_audiences, kind=saved): a hint about who is likely to convert.
search_themes	list of text	no	none	Optional search themes, up to 50: what people who want this search for.
final_url_expansion	true or false	no	false	true = let Google send clicks beyond final_url (see above).
asset_group_name	text	no	none	Optional name for the asset group.
asset_group_status	one of ENABLED, PAUSED	no	none	PAUSED or ENABLED; leave out to follow the installation's setting.
start_date	text	no	none	Optional start, YYYY-MM-DD, in the account's time zone; not in the past.
end_date	text	no	none	Optional end, YYYY-MM-DD (the campaign runs through that day).
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_asset_group

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

Add a further asset group to a Performance Max campaign, with its texts, images, videos and signals, in one transaction: Google takes an asset group only with its minimum assets. Use one asset group per theme or landing page; all of a campaign's asset groups share its budget, bidding, locations and languages.

It is created PAUSED unless the installation lets new ads start, and enabled with gads_update_asset_group. An ENABLED asset group in an ENABLED campaign starts showing.

The business name and the logos are the campaign's own where it has brand guidelines on (every campaign made by gads_create_pmax_campaign): leave business_name and logos out. Only a campaign with brand guidelines off needs them here; gads_list_asset_groups says which.

Images come from the media library by media_id and nowhere else; each is measured first.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		The Performance Max campaign's id.
name	text	yes		Asset group name (unique in the campaign).
final_url	text	yes		The landing page, a full http(s) address.
headlines	list of text	yes		3 to 15 headlines, each up to 30 characters.
long_headlines	list of text	yes		1 to 5 long headlines, each up to 90 characters.
descriptions	list of text	yes		2 to 5 descriptions, each up to 90 characters; one of them 60 or fewer.
marketing_images	list of text	yes		Landscape images, 1.91:1 and at least 600x314: media ids. 1 to 20.
square_images	list of text	yes		Square images, 1:1 and at least 300x300: media ids. 1 to 20.
portrait_images	list of text	no	none	Optional portrait images, 4:5 and at least 480x600: media ids, up to 20.
videos	list of text	no	none	Optional YouTube videos, by id or address, up to 15.
audience_signal	text	no	none	Optional id of a saved audience (gads_list_audiences, kind=saved): a hint.
search_themes	list of text	no	none	Optional search themes, up to 50: what people who want this search for.
business_name	text	no	none	Only for a campaign with brand guidelines off: the advertiser's name, up to 25.
logos	list of text	no	none	Only for a campaign with brand guidelines off: 1 to 5 logo media ids, one square.
status	one of ENABLED, PAUSED	no	none	PAUSED or ENABLED; leave out to follow the installation's setting.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_update_asset_group

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.

Change a Performance Max asset group: rename it, change its final URL, pause or enable it, add assets, and unlink assets. (An asset group is not removed from here; pausing is its off switch.) status=ENABLED is how an asset group created PAUSED is started: in an ENABLED campaign it then shows and spends, so do it only when the user asked.

To REPLACE an asset, give the new one in add_assets and the old one in remove_asset_ids in the same call: both happen in one transaction, so the asset group never has fewer than Google requires. A removal that would leave it under a minimum (3 headlines, 1 long headline, 2 descriptions with one of 60 characters or fewer, 1 landscape image, 1 square image) is refused. Unlinking needs confirm_remove=true; the asset itself stays in the account.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
asset_group_id	text	yes		Asset group id from gads_list_asset_groups.
name	text	no	none	A new name.
final_url	text	no	none	A new landing page, a full http(s) address; it replaces the asset group's final URLs.
status	one of ENABLED, PAUSED	no	none	ENABLED or PAUSED.
add_assets	AssetsToAdd	no	none	What to add: headlines, long_headlines, descriptions, marketing_images, square_images, portrait_images (media ids) and videos (YouTube ids or addresses).
remove_asset_ids	list of text	no	none	Asset ids to unlink, from gads_list_asset_groups; "<asset_id>~<FIELD_TYPE>" where one asset is linked under two field types.
confirm_remove	true or false	no	false	Must be true to unlink, after the user asked for the removal.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_set_asset_group_signals

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 a Performance Max asset group's signals: its audience signal and its search themes. Signals are HINTS to Google about who is likely to convert. They never limit who sees the ads: do not present them as targeting.

audience_id names the saved audience the asset group should have (gads_list_audiences with kind=saved); one it has already is replaced. search_themes is the WHOLE list it should have: themes not on it yet are added and themes it has that are not in the list are removed. Leave an argument out to leave that kind of signal as it is. Anything that removes a signal needs confirm_remove=true. All of it is one transaction.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
asset_group_id	text	yes		Asset group id from gads_list_asset_groups.
audience_id	text	no	none	The saved audience to use as the audience signal.
remove_audience	true or false	no	false	true = take the audience signal off, leaving none.
search_themes	list of text	no	none	The complete list of search themes, up to 50, each up to 80 characters and ten words. An empty list removes them all.
confirm_remove	true or false	no	false	Must be true when a signal is removed or replaced, after the user asked.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_set_brand_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 a Performance Max campaign off searches for certain brands (its own brand, so that it does not take what a Search campaign already catches, or competitors'). Brands are excluded as a brand list: give brand_list_id to exclude a list the account has (gads_list_brand_lists), or brands - brand ids from gads_search_brands - to make a new list and exclude it, in one transaction. It holds for this campaign only.

remove_brand_list_ids lifts an exclusion, so the campaign can show on those searches again: it needs confirm_remove=true, and the brand list itself is kept. A brand list is not edited from here: to change which brands are excluded, make a new list and lift the old one in the same call.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		The Performance Max campaign's id.
brand_list_id	text	no	none	An existing brand list to exclude.
brands	list of text	no	none	Brand ids (gads_search_brands) for a new brand list, up to 100.
list_name	text	no	none	Name for the new list; "<campaign name> brand exclusions" by default.
remove_brand_list_ids	list of text	no	none	Brand lists the campaign should stop excluding.
confirm_remove	true or false	no	false	Must be true to lift an exclusion, after the user asked for exactly that.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_youtube_video_asset

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

Make a video that is already on YouTube an asset of the account, so it can be used in a Performance Max asset group (gads_update_asset_group) or a video ad. Give the video's 11-character id or its YouTube address; only the id's form is checked here and nothing is fetched. Whether the video exists and may be used (not private, not age-restricted) is Google's to say, and its dry run does say it. A video the account already holds as an asset is handed back, not made twice. A video file that is not on YouTube yet is uploaded first with gads_upload_video.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
youtube_video	text	yes		The video's id (11 characters) or its youtube.com / youtu.be address.
name	text	no	none	Optional name for the asset in Google Ads.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_upload_video

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

Upload a video file from your media library to YouTube through Google Ads, and make it a video asset of the account. THE VIDEO IS THEN ON YOUTUBE, outside this server, for good: nothing here can take it back, and anyone who has its link can watch it.

Where it lands: without channel_id, on a YouTube channel that Google manages for this Google Ads account (not the advertiser's own channel, and not visible in their YouTube Studio). With channel_id, on that channel, which must be the advertiser's own and linked to the Google Ads account. Either way it is uploaded UNLISTED: it does not appear in search or on the channel, and is seen in ads and by whoever has the link. This tool never uploads a public video; on the advertiser's own channel a person can make it public afterwards in YouTube Studio.

The file comes from the media library by media_id and nowhere else (a video at a URL is added first with meta_add_media; the library is shared by every platform). An upload cannot be checked without sending the file, so the dry run is this server's own preflight (status preflighted_not_sent): it sends nothing, and Google has not seen or accepted anything. Ask the user before dry_run=false, and tell them where the video will be. After the upload the tool waits up to three minutes for YouTube to process the video and then makes the asset; if processing takes longer it answers with the upload's id, and gads_get_video_upload reads its state later.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
media_id	text	yes		The video (MP4 or MOV) in your media library (meta_list_media lists them).
title	text	yes		The video's title on YouTube, up to 100 characters. It cannot be changed from here.
description	text	yes		The video's description on YouTube, up to 5000 characters.
channel_id	text	no	none	Optional: the advertiser's own YouTube channel id (starts with UC, 24 characters). Left out: a channel Google manages for the account.
dry_run	true or false	no	true	true = preflight only, nothing sent (default). false = upload, only after the user confirms.

gads_create_demand_gen_campaign

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

Create a Demand Gen campaign with a budget of its own, in one transaction. Demand Gen shows image and video ads on YouTube (in-stream, in-feed, Shorts), Discover, Gmail, Maps and the Display network to people who are NOT searching. It is how a YouTube ad is made from here: Google does not allow a Video campaign to be created through its API.

The campaign is always created PAUSED and holds nothing yet. Where it shows, in which locations and languages and to whom is set on each ad group (gads_create_demand_gen_ad_group), and the ads with gads_create_demand_gen_ad; then it is enabled with gads_set_campaign_status.

Give daily_budget, or total_budget with start_date and end_date (the whole amount spent over those days). Google refuses a budget under 5 US dollars a day, or its equivalent.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
name	text	yes		Campaign name (must be unique in the account).
bidding	one of MAXIMIZE_CONVERSIONS, TARGET_CPA, MAXIMIZE_CLICKS, TARGET_ROAS	yes		MAXIMIZE_CONVERSIONS (optional target_cpa), TARGET_CPA (target_cpa required), MAXIMIZE_CLICKS or TARGET_ROAS (target_roas required).
contains_eu_political_advertising	true or false	yes		Ask the user; there is no default. true only if the campaign carries political advertising aimed at the European Union.
daily_budget	number	no	none	Average daily budget in account currency units.
total_budget	number	no	none	Instead of daily_budget: the whole budget for the campaign's run, in account currency units. Needs start_date and end_date.
start_date	text	no	none	Start, YYYY-MM-DD, in the account's time zone; not in the past.
end_date	text	no	none	End, YYYY-MM-DD (the campaign runs through that day).
target_cpa	number	no	none	Target cost per conversion, in account currency.
target_roas	number	no	none	Target return on ad spend as a ratio: 4.0 is 400%.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_demand_gen_ad_group

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

Create an ad group in a Demand Gen campaign with its locations, its languages, its channels and (optionally) its audience, in one transaction. A Demand Gen campaign keeps locations and languages on the ad group, so both are required here: without them the ads would show everywhere, to everyone. Show the user the channels and the audience before applying.

channels says where the ads may show: youtube_in_stream, youtube_in_feed, youtube_shorts, discover, gmail, display (other companies' websites and apps) and maps. Left out, all of them are on, as Google has it. For YouTube ads only, give the three youtube_ ones.

optimized_targeting is OFF unless the call says true. With it on, Google shows the ads to people beyond the audience, wherever it expects conversions. Google's own default is on, so this writes it off by name, as a second logged step right after the ad group is made. Turn it on only when the user asked for it.

The ad group is created PAUSED unless the installation allows new ads to start enabled.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		The Demand Gen campaign to create it in.
name	text	yes		Ad group name (unique in the campaign).
locations	list of text	yes		Geo target ids to show in (gads_search_geo_targets). At least one.
languages	list of text	yes		Language ids to target (gads_search_languages). At least one.
audience_id	text	no	none	Optional saved audience to show the ads to (gads_list_audiences, kind=saved). Left out, the ads show to everyone in the locations who uses the languages.
channels	list of one of youtube_in_stream, youtube_in_feed, youtube_shorts, discover, gmail, display, maps	no	none	Where the ads may show (see above). Left out = every channel.
optimized_targeting	true or false	no	false	true = let Google show the ads beyond the audience (see above).
status	one of ENABLED, PAUSED	no	none	PAUSED or ENABLED; leave out to follow the installation's setting.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_demand_gen_ad

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

Create an ad in a Demand Gen ad group. kind decides what it is made of:

• image: 1 to 5 headlines (30 characters), 1 to 5 descriptions (90), 1 to 5 logos, and images: at least one landscape or square one, 20 at most with the portrait ones.
• carousel: exactly one headline (40) and one description (90), exactly one logo, and 2 to 10 cards, each with its own image, headline and (optionally) landing page.
• video: 1 to 5 videos, 1 to 5 headlines (40), 1 to 5 long_headlines (90), 1 to 5 descriptions (90) and a logo. This is the YouTube ad.

Images and logos come from your media library by media_id and nowhere else (an image at a URL is added first with meta_add_media); each is measured here before anything is sent. A video is a YouTube video's id or address; a video file is put on YouTube first with gads_upload_video, as its own confirmed step. The assets and the ad are made in one transaction. The ad is created PAUSED unless the installation allows new ads to start enabled. Every automation Google has for the ad's kind (redesigned images, videos made from images, shorter and vertical versions of a video, landing page previews) is written opted out. The dry run is Google's own check, policy included, so show the user what Google said.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
ad_group_id	text	yes		The Demand Gen ad group (gads_list_ad_groups).
kind	one of image, carousel, video	yes		image, carousel or video.
final_url	text	yes		The landing page, a full http(s) address.
business_name	text	yes		The advertiser's name as shown, up to 25 characters.
headlines	list of text	yes		The headlines (see above for how many and how wide).
descriptions	list of text	yes		The descriptions.
logos	list of text	yes		Square logos, 1:1 and at least 128x128: media ids.
long_headlines	list of text	no	none	video only: 1 to 5 long headlines, each up to 90 characters.
marketing_images	list of text	no	none	image only: landscape images, 1.91:1 and at least 600x314: media ids.
square_images	list of text	no	none	image only: square images, 1:1 and at least 300x300: media ids.
portrait_images	list of text	no	none	image only: portrait images, 4:5 and at least 480x600: media ids.
tall_portrait_images	list of text	no	none	image only: tall images, 9:16 and at least 600x1067: media ids.
videos	list of text	no	none	video only: YouTube video ids or addresses.
cards	list of Card	no	none	carousel only: {headline, marketing_image and/or square_image, portrait_image?, final_url?, call_to_action_text?}, 2 to 10 of them, the images as media ids.
call_to_action_text	text	no	none	image and carousel: optional button text, e.g. "Learn more".
status	one of ENABLED, PAUSED	no	none	PAUSED or ENABLED; leave out to follow the installation's setting.
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.

AssetsToAdd

What gads_update_asset_group adds to an asset group.

Field	Type	Required	Default	Description
headlines	list of text	no		Headlines to add, each up to 30 characters.
long_headlines	list of text	no		Long headlines to add, each up to 90 characters.
descriptions	list of text	no		Descriptions to add, each up to 90 characters.
marketing_images	list of text	no		Landscape images to add (1.91:1, at least 600x314): media ids from the library.
square_images	list of text	no		Square images to add (1:1, at least 300x300): media ids.
portrait_images	list of text	no		Portrait images to add (4:5, at least 480x600): media ids.
videos	list of text	no		YouTube videos to add, by id or address.
business_name	text	no	none	A new business name, up to 25 characters. Only where the campaign has brand guidelines off; remove the old one in the same call.
logos	list of text	no		Logos to add: media ids, square (1:1, at least 128x128) or wide (4:1). Only where the campaign has brand guidelines off.

Card

One card of a carousel ad: an image, a headline and where a click on it leads.

Field	Type	Required	Default	Description
headline	text	yes		The card's headline, up to 40 characters.
marketing_image	text	no	none	Landscape image, 1.91:1, at least 600x314: a media id.
square_image	text	no	none	Square image, 1:1, at least 300x300: a media id.
portrait_image	text	no	none	Optional portrait image, 4:5, at least 480x600: a media id.
final_url	text	no	none	Where this card leads; the ad's final_url when left out.
call_to_action_text	text	no	none	Optional button text for this card.