أدوات Google Ads: عروض الأسعار والتحويلات
في هذه الصفحة 7 أداة. هذه الصفحة مولَّدة آليًا من قائمة الأدوات في الخادم نفسه، الإصدار 0.1.0، ولا تُحرَّر باليد. أوصاف الأدوات مكتوبة للمساعد الذكي، وهي بالإنجليزية ولم تُترجم، فكل ما تحت هذه الفقرة بالإنجليزية كما يقرؤه المساعد الذكي. لا تحتاج إلى معرفة اسم أي أداة لتطلب عملًا: هذه الصفحة مرجع لمن يريد أن يعرف ما تأخذه كل أداة بالضبط. صفحة كل الأدوات تسرد الصفحات كلها.
gads_list_conversion_actions
Kind: read. It is marked as changing nothing.
Conversion actions with the settings that decide bidding (primary or secondary, category, counting, lookback windows, value, attribution model) and each one's conversions in the last 30 days. Also the account's custom conversion goals and the campaigns that do not follow the account's default goals. Give campaign_id to see that campaign's own goals, which is what gads_set_campaign_conversion_goals changes.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
include_removed | true or false | no | false | Also list removed conversion actions. |
campaign_id | text | no | none | Optional campaign whose goal level and goals to include. |
gads_update_conversion_action
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 conversion action: whether bidding uses it (primary_for_goal), its category, how it counts, its lookback windows, its value and its attribution model. Only what is passed changes. This changes what campaigns optimise for across the whole account, so it works only while an administrator has switched conversion edits on.
status REMOVED deletes the action and cannot be undone: it needs confirm_remove=true, and nothing else may be changed in the same call. HIDDEN is the softer state - the action stops showing and stops counting, and can be enabled again.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
conversion_action_id | text | yes | Id from gads_list_conversion_actions. | |
status | one of ENABLED, HIDDEN, REMOVED | no | none | ENABLED, HIDDEN, or REMOVED (see above). |
primary_for_goal | true or false | no | none | true = bidding optimises for it; false = it is only observed. |
category | one of DEFAULT, PAGE_VIEW, PURCHASE, SIGNUP, DOWNLOAD, ADD_TO_CART, BEGIN_CHECKOUT, SUBSCRIBE_PAID, PHONE_CALL_LEAD, IMPORTED_LEAD, SUBMIT_LEAD_FORM, BOOK_APPOINTMENT, REQUEST_QUOTE, GET_DIRECTIONS, OUTBOUND_CLICK, CONTACT, ENGAGEMENT, STORE_VISIT, STORE_SALE, QUALIFIED_LEAD, CONVERTED_LEAD | no | none | The goal category the action belongs to. |
counting_type | one of ONE_PER_CLICK, MANY_PER_CLICK | no | none | ONE_PER_CLICK (leads) or MANY_PER_CLICK (sales). |
click_through_lookback_window_days | whole number | no | none | Days after a click a conversion still counts. |
view_through_lookback_window_days | whole number | no | none | Days after an impression a conversion still counts. |
default_value | number | no | none | The value of one conversion when none is sent with it. |
default_currency_code | text | no | none | Three-letter currency of default_value, e.g. KWD. |
always_use_default_value | true or false | no | none | true = ignore the value sent and use default_value. |
attribution_model | one of GOOGLE_ADS_LAST_CLICK, GOOGLE_SEARCH_ATTRIBUTION_DATA_DRIVEN | no | none | GOOGLE_ADS_LAST_CLICK or GOOGLE_SEARCH_ATTRIBUTION_DATA_DRIVEN. |
confirm_remove | true or false | no | false | Must be true for status REMOVED. |
dry_run | true or false | no | true | true = validate only (default). false = apply, only after the user confirms. |
gads_create_conversion_action
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Create a conversion action: UPLOAD_CLICKS, which takes conversions uploaded from the advertiser's own records (gads_upload_offline_conversions), or WEBPAGE, which Google's tag counts on a page of the website. Any other type is refused: Google makes those itself or imports them from a linked property.
A new action is ENABLED and, with primary_for_goal=true, every campaign whose goals include its category starts bidding towards it as soon as it records conversions; pass primary_for_goal=false to only observe it first. It works only while an administrator has switched conversion edits on. After a real create of a WEBPAGE action the result carries its tag snippets, for the website. A new UPLOAD_CLICKS action takes uploads about six hours after it is made.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
name | text | yes | The action's name, unique in the account. | |
type | text | yes | UPLOAD_CLICKS or WEBPAGE. | |
category | one of DEFAULT, PAGE_VIEW, PURCHASE, SIGNUP, DOWNLOAD, ADD_TO_CART, BEGIN_CHECKOUT, SUBSCRIBE_PAID, PHONE_CALL_LEAD, IMPORTED_LEAD, SUBMIT_LEAD_FORM, BOOK_APPOINTMENT, REQUEST_QUOTE, GET_DIRECTIONS, OUTBOUND_CLICK, CONTACT, ENGAGEMENT, STORE_VISIT, STORE_SALE, QUALIFIED_LEAD, CONVERTED_LEAD | yes | The goal category it belongs to, e.g. QUALIFIED_LEAD, CONVERTED_LEAD, PURCHASE, SUBMIT_LEAD_FORM. | |
counting_type | one of ONE_PER_CLICK, MANY_PER_CLICK | no | none | ONE_PER_CLICK (leads) or MANY_PER_CLICK (sales). Google's default if omitted. |
default_value | number | no | none | The value of one conversion when none is sent with it. |
currency | text | no | none | Three-letter currency of default_value, e.g. SAR. |
click_through_days | whole number | no | none | Days after a click a conversion still counts. |
view_through_days | whole number | no | none | Days after an impression a conversion still counts. |
primary_for_goal | true or false | no | true | true = bidding optimises for it (default); false = it is only observed. |
dry_run | true or false | no | true | true = validate only (default). false = apply, only after the user confirms. |
gads_set_campaign_conversion_goals
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Choose what one campaign optimises for. Exactly one of three:
- use_account_default_goals=true: back to the account's goals.
- goals: campaign-specific goals. The ones listed are set as given and EVERY OTHER goal the campaign has is set to not biddable, so the list is the whole answer. Each must be a category and origin the campaign already has (see gads_list_conversion_actions with campaign_id); Google creates those, this cannot.
- custom_conversion_goal_id: bid on that custom goal's conversion actions, primary or not.
Works only while an administrator has switched conversion edits on.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
campaign_id | text | yes | Campaign id. | |
use_account_default_goals | true or false | no | false | true to follow the account's default goals again. |
goals | list of GoalInput | no | none | List of {category, origin, biddable}. |
custom_conversion_goal_id | text | no | none | Id of an enabled custom conversion goal. |
dry_run | true or false | no | true | true = validate only (default). false = apply, only after the user confirms. |
gads_set_bidding_strategy
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Change how a campaign bids. Changing the strategy restarts Google's learning, and a strategy that bids by itself ignores keyword and ad group bids: tell the user both.
- MANUAL_CPC: keyword and ad group bids, nothing else.
- MAXIMIZE_CLICKS: optional cpc_bid_ceiling.
- MAXIMIZE_CONVERSIONS: optional target_cpa. TARGET_CPA is the same with target_cpa required.
- MAXIMIZE_CONVERSION_VALUE: optional target_roas. TARGET_ROAS is the same with it required.
- TARGET_IMPRESSION_SHARE: impression_share_location, impression_share_pct and cpc_bid_ceiling, all three required.
- PORTFOLIO: portfolio_strategy_id, a shared strategy that already exists in the account.
Leaving an optional target or ceiling out removes the one the campaign has. A target CPA and a ceiling are held to the installation's limits; lowering one is never refused.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
campaign_id | text | yes | Campaign id. | |
strategy | one of MANUAL_CPC, MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, TARGET_CPA, MAXIMIZE_CONVERSION_VALUE, TARGET_ROAS, TARGET_IMPRESSION_SHARE, PORTFOLIO | yes | One of the names above. | |
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 means 400%. |
cpc_bid_ceiling | number | no | none | The most the strategy may bid for a click, in account currency. |
impression_share_location | one of ANYWHERE_ON_PAGE, TOP_OF_PAGE, ABSOLUTE_TOP_OF_PAGE | no | none | ANYWHERE_ON_PAGE, TOP_OF_PAGE or ABSOLUTE_TOP_OF_PAGE. |
impression_share_pct | number | no | none | The share of impressions to aim for, 1 to 100. |
portfolio_strategy_id | text | no | none | Id of a portfolio bidding strategy. |
enhanced_cpc | true or false | no | false | Not available: Google ended enhanced CPC for Search campaigns in March 2025. |
dry_run | true or false | no | true | true = validate only (default). false = apply, only after the user confirms. |
gads_set_ad_schedule
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Set the hours a campaign's ads may show, in the account's time zone. A campaign with no schedule runs at all hours; once it has one, ads show only inside it.
replace_existing=false (default) adds these entries to the schedule the campaign has, and refuses one that overlaps it. replace_existing=true removes the whole current schedule and puts this list in its place, in one transaction; with an empty list that returns the campaign to all hours. An entry cannot be edited: Google changes one by removing it and adding another.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
campaign_id | text | yes | Campaign id. | |
entries | list of ScheduleEntry | yes | List of {day_of_week, start_hour, start_minute, end_hour, end_minute, bid_modifier}. Minutes are 0, 15, 30 or 45; 24:00 is the end of a day; at most six entries a day. Hours past midnight are two entries. | |
replace_existing | true or false | no | false | true = this list becomes the whole schedule. |
dry_run | true or false | no | true | true = validate only (default). false = apply, only after the user confirms. |
gads_set_device_bid_modifier
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Raise or lower bids on one kind of device, for a campaign or for one ad group.
bid_modifier multiplies the bid: 1.2 is +20%, 0.8 is -20%, 1.0 is no adjustment, and 0 EXCLUDES the device - ads stop showing there. Google takes 0.1 to 10. A raise is held to the installation's limit; lowering and excluding are never refused. Under a conversion strategy Google mostly ignores device modifiers; the result says when that applies.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
device | one of MOBILE, TABLET, DESKTOP | yes | MOBILE, TABLET or DESKTOP. | |
bid_modifier | number | yes | The multiplier, or 0 to exclude the device. | |
campaign_id | text | no | none | The campaign to set it on (give this or ad_group_id). |
ad_group_id | text | no | none | The ad group to set it on. |
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.
GoalInput
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
category | one of DEFAULT, PAGE_VIEW, PURCHASE, SIGNUP, DOWNLOAD, ADD_TO_CART, BEGIN_CHECKOUT, SUBSCRIBE_PAID, PHONE_CALL_LEAD, IMPORTED_LEAD, SUBMIT_LEAD_FORM, BOOK_APPOINTMENT, REQUEST_QUOTE, GET_DIRECTIONS, OUTBOUND_CLICK, CONTACT, ENGAGEMENT, STORE_VISIT, STORE_SALE, QUALIFIED_LEAD, CONVERTED_LEAD | yes | The goal's category, e.g. SUBMIT_LEAD_FORM. | |
origin | one of WEBSITE, GOOGLE_HOSTED, APP, CALL_FROM_ADS, STORE, YOUTUBE_HOSTED | yes | Where the conversion happens, e.g. WEBSITE. | |
biddable | true or false | no | true | Whether the campaign bids towards this goal. |
ScheduleEntry
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
day_of_week | one of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY | yes | ||
start_hour | whole number | yes | 0 to 23. | |
start_minute | whole number | no | 0 | 0, 15, 30 or 45. |
end_hour | whole number | yes | 0 to 24; 24 is the end of the day. | |
end_minute | whole number | no | 0 | 0, 15, 30 or 45. |
bid_modifier | number | no | none | Optional bid multiplier for these hours: 1.2 is +20%, 0.8 is -20%. |