أدوات Google Ads: الأصول

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

gads_list_assets

Kind: read. It is marked as changing nothing.

Sitelinks, callouts, structured snippets, call assets, images, lead forms, price lists and promotions: what each says, where it is linked, its link status and policy state, and its impressions, clicks and cost. With a campaign_id or an ad_group_id it lists the assets linked there; with neither, the ones linked to the whole account. all_assets=true lists every such asset the account holds, linked or not, without metrics - which is how to find an asset_id for gads_link_asset. Without a field_type that list also has the account's YouTube video assets (type YOUTUBE_VIDEO, with the video's id and title), which no field type here links.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	no	none	List the assets linked to this campaign.
ad_group_id	text	no	none	List the assets linked to this ad group.
field_type	one of SITELINK, CALLOUT, STRUCTURED_SNIPPET, CALL, AD_IMAGE, LEAD_FORM, PRICE, PROMOTION	no	none	Optional: SITELINK, CALLOUT, STRUCTURED_SNIPPET, CALL, AD_IMAGE, LEAD_FORM, PRICE or PROMOTION.
all_assets	true or false	no	false	true = every asset of these kinds in the account, without links or metrics.
date_range	text	no	"LAST_30_DAYS"	Named range for the metrics, e.g. LAST_7_DAYS, LAST_30_DAYS.
start_date	text	no	none	Optional custom range start, YYYY-MM-DD (with end_date).
end_date	text	no	none	Optional custom range end, YYYY-MM-DD.

gads_create_sitelink

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

Create a sitelink: an extra link shown under an ad. Give campaign_id or ad_group_id to link it there in the same step; with neither it is only created. Google shows sitelinks once a campaign has at least two.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
link_text	text	yes		The link's text, up to 25 characters.
final_url	text	yes		Where the link goes, a full http(s) address.
description1	text	no	none	Optional first line under the link, up to 35 characters (needs description2).
description2	text	no	none	Optional second line, up to 35 characters (needs description1).
campaign_id	text	no	none	Link it to this campaign.
ad_group_id	text	no	none	Link it to this ad group.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_callout

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

Create a callout: a short phrase shown with an ad, such as "Free delivery". Give campaign_id or ad_group_id to link it there in the same step.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
text	text	yes		The callout, up to 25 characters.
campaign_id	text	no	none	Link it to this campaign.
ad_group_id	text	no	none	Link it to this ad group.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_structured_snippet

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

Create a structured snippet: a header from Google's fixed list and 3 to 10 values, shown with an ad as "Services: Accounting, Payroll, Stock". The header must be one of Google's, in the language of the values. In English: Amenities, Brands, Courses, Degree programs, Destinations, Featured hotels, Insurance coverage, Models, Neighborhoods, Service catalog, Shows, Styles, Types. Give campaign_id or ad_group_id to link it there in the same step.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
header	text	yes		One of Google's headers, exactly as Google spells it.
values	list of text	yes		3 to 10 values, each up to 25 characters.
campaign_id	text	no	none	Link it to this campaign.
ad_group_id	text	no	none	Link it to this ad group.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_call_asset

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

Create a call asset: a phone number shown with an ad. Give campaign_id or ad_group_id to link it there in the same step. Calls are counted as conversions by the conversion action it names; without one it follows the account's own call conversion setting, and the result says which applies.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
country_code	text	yes		Two-letter country of the number, e.g. KW, SA, EG.
phone_number	text	yes		The number, e.g. +965 2222 3333.
call_conversion_action_id	text	no	none	Optional conversion action that counts calls from this asset.
campaign_id	text	no	none	Link it to this campaign.
ad_group_id	text	no	none	Link it to this ad group.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_image_asset

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

Create an image asset from a file in your media library, to show beside a Search ad. The image is square (1:1, at least 300x300) or landscape (1.91:1, at least 600x314), JPEG or PNG, at most 5120 KB; it is measured here before anything is sent. Give campaign_id or ad_group_id to link it there in the same step. An image at a URL is added to the library first with meta_add_media (the library is shared by every platform), then named here.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
media_id	text	yes		The image in your media library (meta_list_media lists them).
name	text	no	none	Optional name for the asset in Google Ads. Defaults to the file's name.
campaign_id	text	no	none	Link it to this campaign.
ad_group_id	text	no	none	Link it to this ad group.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_lead_form_asset

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

Create a lead form: a form people fill in on Google itself, from the ad, without visiting the site. It collects personal details, so it needs a privacy policy and the account must have accepted Google's lead form terms (in the Google Ads UI); Google refuses it otherwise and says so. Leads are downloaded in the Google Ads UI or sent to a webhook; this tool reads none of them, and leads_export does only where an administrator allows it. Give campaign_id to link it to that campaign in the same step; without one it is only created, for a person to review first.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
business_name	text	yes		The business as shown on the form, up to 25 characters.
headline	text	yes		The form's headline, up to 30 characters.
description	text	yes		What the person gets for filling it in, up to 200 characters.
privacy_policy_url	text	yes		The https address of the privacy policy.
final_url	text	yes		The site's page the form belongs to, a full http(s) address.
fields	list of one of FULL_NAME, FIRST_NAME, LAST_NAME, EMAIL, PHONE_NUMBER, POSTAL_CODE, STREET_ADDRESS, CITY, REGION, COUNTRY, WORK_EMAIL, COMPANY_NAME, WORK_PHONE, JOB_TITLE	yes		What the form asks for, e.g. ["FULL_NAME", "PHONE_NUMBER", "EMAIL"].
call_to_action_description	text	yes		The line beside the button, up to 30 characters.
call_to_action	one of LEARN_MORE, GET_QUOTE, APPLY_NOW, SIGN_UP, CONTACT_US, SUBSCRIBE, DOWNLOAD, BOOK_NOW, GET_OFFER, REGISTER, GET_INFO, REQUEST_DEMO, JOIN_NOW, GET_STARTED	no	"LEARN_MORE"	The button: LEARN_MORE, GET_QUOTE, CONTACT_US, REQUEST_DEMO, SIGN_UP, ...
post_submit_headline	text	no	none	Optional headline shown after the form is sent, up to 30 characters.
post_submit_description	text	no	none	Optional text shown after it is sent, up to 200 characters.
post_submit_call_to_action	one of VISIT_SITE, DOWNLOAD, LEARN_MORE, SHOP_NOW	no	none	Optional button shown after it is sent, leading to final_url.
more_qualified_leads	true or false	no	false	true = Google asks the person to review before sending: fewer, surer leads.
webhook_url	text	no	none	Optional https address Google sends each lead to (needs webhook_secret).
webhook_secret	text	no	none	The key Google sends with each lead so the webhook can trust it.
campaign_id	text	no	none	Link it to this campaign.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_price_asset

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

Create a price asset: 3 to 8 items with their prices, shown under an ad, each with its own page. Give campaign_id or ad_group_id to link it there in the same step.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
price_type	one of BRANDS, EVENTS, LOCATIONS, NEIGHBORHOODS, PRODUCT_CATEGORIES, PRODUCT_TIERS, SERVICES, SERVICE_CATEGORIES, SERVICE_TIERS	yes		What the items are: SERVICES, SERVICE_TIERS, PRODUCT_CATEGORIES, BRANDS, ...
currency_code	text	yes		The currency of every price, e.g. KWD.
offerings	list of PriceOffer	yes		3 to 8 items: header, description, price, final_url and an optional unit.
language_code	text	no	"en"	The language of the text, e.g. en or ar.
price_qualifier	one of FROM, UP_TO, AVERAGE	no	none	Optional FROM, UP_TO or AVERAGE, shown before every price.
campaign_id	text	no	none	Link it to this campaign.
ad_group_id	text	no	none	Link it to this ad group.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_create_promotion_asset

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

Create a promotion asset: an offer shown under an ad, such as "20% off Payroll". Give either percent_off or money_off (with currency_code). It can name a promotion code or a least order value, not both. Give campaign_id or ad_group_id to link it in the same step.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
promotion_target	text	yes		What the offer is on, up to 20 characters.
final_url	text	yes		The page the offer leads to, a full http(s) address.
percent_off	number	no	none	The discount in percent, e.g. 20 for 20% off.
money_off	number	no	none	The discount as an amount in currency units (needs currency_code).
currency_code	text	no	none	The currency of money_off and orders_over, e.g. KWD.
up_to	true or false	no	false	true = shown as "up to" the discount.
promotion_code	text	no	none	Optional code the buyer enters, up to 15 characters.
orders_over	number	no	none	Optional least order value the offer needs, in currency units.
occasion	one of NEW_YEARS, CHINESE_NEW_YEAR, VALENTINES_DAY, EASTER, MOTHERS_DAY, FATHERS_DAY, LABOR_DAY, BACK_TO_SCHOOL, HALLOWEEN, BLACK_FRIDAY, CYBER_MONDAY, CHRISTMAS, BOXING_DAY, INDEPENDENCE_DAY, NATIONAL_DAY, END_OF_SEASON, WINTER_SALE, SUMMER_SALE, FALL_SALE, SPRING_SALE, RAMADAN, EID_AL_FITR, EID_AL_ADHA, SINGLES_DAY, WOMENS_DAY, HOLI, PARENTS_DAY, ST_NICHOLAS_DAY, CARNIVAL, EPIPHANY, ROSH_HASHANAH, PASSOVER, HANUKKAH, DIWALI, NAVRATRI, SONGKRAN, YEAR_END_GIFT	no	none	Optional occasion, e.g. RAMADAN, EID_AL_FITR, NATIONAL_DAY, BLACK_FRIDAY.
language_code	text	no	"en"	The language of the text, e.g. en or ar.
start_date	text	no	none	Optional first day the asset shows, YYYY-MM-DD.
end_date	text	no	none	Optional last day the asset shows, YYYY-MM-DD.
campaign_id	text	no	none	Link it to this campaign.
ad_group_id	text	no	none	Link it to this ad group.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_link_asset

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

Link an existing asset to a campaign, an ad group, or the whole account, so it can show with the ads there. An account-level link reaches every campaign.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
asset_id	text	yes		Asset id (gads_list_assets with all_assets=true lists them).
field_type	one of SITELINK, CALLOUT, STRUCTURED_SNIPPET, CALL, AD_IMAGE, LEAD_FORM, PRICE, PROMOTION	yes		What the asset is used as: SITELINK, CALLOUT, STRUCTURED_SNIPPET, CALL, AD_IMAGE (an image), LEAD_FORM (a campaign only), PRICE or PROMOTION.
campaign_id	text	no	none	Link it to this campaign.
ad_group_id	text	no	none	Link it to this ad group.
account_level	true or false	no	false	true = link it to the whole account.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_unlink_asset

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.

Remove an asset's link to a campaign, an ad group or the account: it stops showing with the ads there. The asset itself stays and can be linked again. Needs confirm_remove=true.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
asset_id	text	yes		Asset id from gads_list_assets.
field_type	one of SITELINK, CALLOUT, STRUCTURED_SNIPPET, CALL, AD_IMAGE, LEAD_FORM, PRICE, PROMOTION	yes		SITELINK, CALLOUT, STRUCTURED_SNIPPET, CALL, AD_IMAGE, LEAD_FORM, PRICE or PROMOTION.
campaign_id	text	no	none	Unlink it from this campaign.
ad_group_id	text	no	none	Unlink it from this ad group.
account_level	true or false	no	false	true = remove its account-level link.
confirm_remove	true or false	no	false	Must be true, 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.

PriceOffer

Field	Type	Required	Default	Description
header	text	yes		What is priced, up to 25 characters, e.g. 'Payroll module'.
description	text	yes		A line about it, up to 25 characters.
price	number (at least 0)	yes		The price in currency units, e.g. 49.5.
final_url	text	yes		The page for this item, a full http(s) address.
unit	one of PER_HOUR, PER_DAY, PER_WEEK, PER_MONTH, PER_YEAR, PER_NIGHT	no	none