v17.1.0 (2024-08-07)
The following new features and updates were added in v17_1.
Assets
AdGroupAdService.RemoveAutomaticallyCreatedAssets()
lets you remove specified automatically created assets linked to Responsive Search Ads.
Audiences
- New enum values in
UserListCustomerTypeCategory
:LOYALTY_TIER_1_MEMBERS
LOYALTY_TIER_2_MEMBERS
LOYALTY_TIER_3_MEMBERS
LOYALTY_TIER_4_MEMBERS
LOYALTY_TIER_5_MEMBERS
LOYALTY_TIER_6_MEMBERS
LOYALTY_TIER_7_MEMBERS
Campaigns
ShareablePreviewService.GenerateShareablePreviews()
generates the URLs (shareable_preview_url
in the response) for shareable ad previews for enabled and paused asset groups.- The
expiration_date_time
field indicates the expiration date of the URLs in the response. - If an error occurs, the method will return
partial_failure_error
instead of the URLs.
- The
Change History
- New change status resource type:
ASSET_GROUP
.
Conversions
- New segment field for SKAdNetwork version:
segments.sk_ad_network_version
offline_conversion_upload_conversion_action_summary
which exposes conversion upload diagnostics at the conversion action level.- The following metrics are added to the offline diagnostics reports to convey the number of uploaded conversions that are still being processed:
Planning
AudienceInsights.GenerateAudienceOverlapInsights()
which accepts an input primary attribute and a collection of audience attributes, and returns the estimates of the overlap of potential YouTube reach between the primary attribute and the audience attributes.
Reporting
- Support for segmenting
per_store_view
based onsegments.date
Videos
- Support for retrieving information related to the following standard bidding strategies for video campaigns using reports, such as,
ad_group
,campaign
:Campaign.fixed_cpm
(Fixed CPM (cost per thousand impression))Campaign.target_cpv
(Target CPV (cost per view))
Campaign.video_campaign_settings
which lets you determine on which inventories the video ads can be shown, using the following report fields:segments.ad_format_type
which lets you segment the following reports based on the video ad format type:
v17 (2024-06-05)
The following features and changes were added in v17.
Ads
- Removed
AdService.getAd
. This brings theAdService
in line with other services in the Google Ads API. See Retrieving objects for the recommended way to fetch ads and other resource types. - Added more validations for
ImageAdInfo.image_asset
regarding dimensions and format. The following errors may be thrown if the image is invalid:
Assets
- Added new enum:
ClickType.AD_IMAGE
- Added the following new reports with new metrics for Performance Max and Search campaigns:
Audiences
Batch Jobs
- Added
BatchJobError.REQUEST_TOO_LARGE
, which will be thrown when the submittedAddBatchJobOperationsRequest
is larger than 10484504 bytes. - Added support for setting
MutateOperation.asset_group_operation
when usingBatchJobService
. This lets you use batch processing to create and manage entire Performance Max campaigns. See our new dedicated guide.
Campaigns
- Renamed Discovery to Demand Gen in all fields, enums, errors of all
resources across the Google Ads API, such as campaigns, ads, and assets. For
example,
AdvertisingChannelType.DISCOVERY
is nowAdvertisingChannelType.DEMAND_GEN
. - Added
Campaign.keyword_match_type
to let you set keyword match type for all keywords in a campaign.
Conversions
- For SKAdNetwork
conversions,
- Renamed
segments.sk_ad_network_conversion_value
tosegments.sk_ad_network_fine_conversion_value
. - Added
segments.sk_ad_network_redistributed_fine_conversion_value
.
- Renamed
- The following metrics are now returned with the response even when they are zero. This makes them consistent with other metrics.
Criteria
- Added to following fields to
AdGroupCriterion
to show whether the ad group criterion is serving or the reasons why it's not serving:primary_status
primary_status_reasons
- Added support for
metrics.search_impression_share
forgender_view
- Added support for
metrics.phone_calls
forkeyword_view
Local Services
- Added
LocalServicesLeadService.AppendLeadConversation()
used to append a newLocalServicesLeadConversation
toLocalServicesLead
, which sends the messages to users through appropriate channels like SMS depending on how the lead was created.- The size of
AppendLeadConversationRequest.conversations
is limited to 1,000. - Only
LocalServicesLead
withlead_type
set toLeadType.MESSAGE
can be specified inConversation.local_services_lead
.
- The size of
- Added new enum values to
ConversationType
:WHATSAPP
to represent a conversation introduced through WhatsApp.ADS_API
to represent a conversation introduced using the newLocalServicesLeadService.AppendLeadConversation()
method.
- Added the following new fields to
local_services_verification_artifact
:local_services_verification_artifact.insurance_verification_artifact.expiration_date_time
local_services_verification_artifact.license_verification_artifact.expiration_date_time
Reporting
- You can now select only fields related to one linked product
when querying
product_link
. Selecting multiple fields of several linked products will throwQueryError.PROHIBITED_FIELD_COMBINATION_IN_SELECT_CLAUSE
. For example,product_link.advertising_partner.customer
andproduct_link.data_partner.data_partner_id
cannot be selected in the same query. - Passing a
page_size
toGoogleAdsService.Search
will result in aRequestError.PAGE_SIZE_NOT_SUPPORTED
error.
Shopping
- Added a new report
shopping_product
, which corresponds to the Products page of the Google Ads UI. It supports returning data related to the current state of products from Google Merchant Center accounts linked to a Google Ads account.- You can filter metrics from the
shopping_product
report usingsegments.date
when usingGoogleAdsService.Search
orGoogleAdsService.SearchStream
. Segmentation by date is not permitted and will return aShoppingProductError.UNSUPPORTED_DATE_SEGMENTATION
error.
- You can filter metrics from the
Unified Goals
- Added
UserListCustomerTypeService.MutateUserListCustomerTypes()
to configure audience customer types. - Removed
CustomerLifecycleGoal.lifecycle_goal_customer_definition_settings
. To configure audience settings of customer lifecycle goals, useUserListCustomerTypeService.MutateUserListCustomerTypes()
instead.- Attach or unattach a user list by setting
UserListCustomerType.customer_type_category
toUserListCustomerTypeCategory.PURCHASERS
to include it into or exclude it from an existing customer definition for customer lifecycle goals, respectively. Visit segment your audiences for more details.
- Attach or unattach a user list by setting
Videos
- Added the following values to
ContentLabelType
. You can exclude theseContentLabelTypes
at the customer level: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
- Added
AdVideoAsset.ad_video_asset_info
to support inventory preferences for video assets when creatingDemandGenVideoResponsiveAdInfo
. - (Allowlisted accounts only) Made
Campaign.video_brand_safety_suitability
mutable.
v16.1.0 (2024-04-24)
The following features and changes were added in v16.1.
Account Management
CustomerNegativeCriterion.ip_block
which supports adding an IP as a negative criterion at the customer level.- New enum value:
ProductLinkError.LINK_EXISTS
. - New enum value:
ProductLinkInvitationError.CUSTOMER_NOT_PERMITTED_TO_CREATE_INVITATION
.
Assets
- Support for assets related to Demand Gen to
ad_group_ad_asset_view
andasset_field_type_view
. - New enum value:
AssetFieldType.DISCOVERY_CAROUSEL_CARD
.
Audiences
- New enum value:
ResourceLimitType.LOOKALIKE_USER_LISTS_PER_CUSTOMER
which limits the number of lookalike user lists a customer can have to 1000.
Campaigns
- Support for returning Target
ROAS campaign bid simulations for
App campaigns using the
campaign_simulation
report. - New enum value:
CampaignError.DYNAMIC_TEXT_ASSET_CANNOT_OPT_OUT_WITH_FINAL_URL_EXPANSION_OPT_IN
. - New enum value:
AdGroupPrimaryStatusReason.AD_GROUP_PAUSED_DUE_TO_LOW_ACTIVITY
. - New enum value:
CampaignCriterionError.CANNOT_REMOVE_ALL_LOCATIONS_DUE_TO_TOO_MANY_COUNTRY_EXCLUSIONS
.
Conversions
SkAdNetworkConversionValueSchema.postback_mappings
which supports SKAdNetwork 4.0 features.- Added support for warnings for
CustomerSkAdNetworkConversionValueSchemaService
asMutateCustomerSkAdNetworkConversionValueSchemaRequest.enable_warnings
. When set totrue
, any non-blocking errors pertaining to operation failures will be returned asMutateCustomerSkAdNetworkConversionValueSchemaResponse.warning
. - New enum values in
CustomerSkAdNetworkConversionValueSchemaError
:INVALID_EVENT_COUNTER
INVALID_EVENT_NAME
Criteria
- New fields in
BrandInfo
:display_name
primary_url
rejection_reason
status
- New enum:
BrandRequestRejectionReason
. - New enum value:
CriterionType.LIFE_EVENT
.
Experiments
- New enum value:
ExperimentError.INVALID_DURATION_FOR_AN_EXPERIMENT
.
Local Services
local_services_lead.credit_details.credit_state
andlocal_services_lead.credit_details.credit_state_last_update_date_time
which returns the state of credit and the timestamp when the credit state was updated, respectively.local_services_lead_conversation.message_details.attachment_urls
which returns the URLs that can be used to download the contents of the attachment.
Videos
customer.video_brand_safety_suitability
andBrandSafetySuitability
which support retrieving video brand safety suitability at the customer level.- New enum value:
VideoCampaignError.MUTATE_REQUIRES_RESERVATION
.
v16 (2024-02-21)
The following features and changes were added in v16.
Account Management
- Migrated
advertising_partner
fromAccountLink
toProductLink
andProductLinkInvitation
. - Removed
data_partner
andgoogle_ads
fromAccountLink
. - Added
IdentityVerificationService
to manage advertiser verification.StartIdentityVerification()
is used to start a verification session using the providedverification_program
. It creates a new verification session and returns an empty response for a successfully created verification.GetIdentityVerification()
can be used for retrieving verification information, which returns several objects ofIdentityVerification
. EachIdentityVerification
includes:verification_program
which is the identity verification program typeidentity_verification_requirement
that contains details related to the deadline by which the advertiser should finish verificationverification_progress
that contains details related to the verification session including:program_status
represents the current status of this verification sessionaction_url
directs the customer to a URL to complete the verification.invitation_link_expiration_time
represents the expiration date for theaction_url
- Enums:
- Errors:
- Added
AuthorizationError.ACTION_NOT_PERMITTED_FOR_SUSPENDED_ACCOUNT
.
Assets
- Changes to
asset_group
:- Added support for time-related segments, such as
segments.year
andsegments.month
. - Made
campaign
an attributed resource instead of segmenting resource.
- Added support for time-related segments, such as
Campaigns
- Changes to Demand Gen campaigns:
- Added support for setting
Campaign.shopping_setting
to an existing Demand Gen campaign. - Added
ShoppingSetting.disable_product_feed
to disable the optional product feed of Demand Gen campaigns. - Added
Ad.demand_gen_product_ad
and the correspondingDemandGenProductAdInfo
, available to Demand Gen campaigns with a non-nullCampaign.shopping_setting
.
- Added support for setting
- Added to following fields to
AdGroup
to show whether the ad group is serving or the reasons why it's not serving:primary_status
primary_status_reasons
- Added to following fields to
AdGroupAd
to show whether the ad group ad is serving or the reasons why it's not serving:primary_status
primary_status_reasons
- Added the following values to
AdGroupError
:CANNOT_ADD_AD_GROUP_FOR_CAMPAIGN_TYPE
INVALID_STATUS
Experiment
- Added
Experiment.sync_enabled
to specify if sync should be enabled in the experiment. With sync enabled, changes made to the original campaign while your experiment is running, are automatically copied to the experiment campaign. - Added
ExperimentError.CANNOT_ENABLE_SYNC_FOR_UNSUPPORTED_EXPERIMENT_TYPE
. - Added
CampaignError.CANNOT_MODIFY_TEXT_ASSET_AUTOMATION_WITH_ENABLED_TRIAL
.
Hotel & Travel
- Added the following fields to
ListingDimensionInfo
for a Things to do ad to enable creating listing groups based on the state and city where the travel activity is available: - Added support for the following segments to
travel_activity_performance_view
:
Local Services
- Added
LocalServicesVerificationArtifact.business_registration_check_verification_artifact
andBusinessRegistrationCheckArtifact
to allow advertisers to monitor the progress of the business registration verification process. - Added a new resource
local_services_employee
to allow advertisers to retrieve the employee information they've added.
Planning
- Removed
score
fromAudienceInsightsAttributeMetadata
.
Recommendations
- Added
RecommendationService.GenerateRecommendations()
which returns recommendations based on the specified settings, such as recommendation types and advertising channel types. This is particularly helpful during campaign construction. - Added
RecommendationMetrics.conversions_value
. - Recommended keywords with unset keyword match type now have
recommended_match_type
set toUNSPECIFIED
instead ofUNKNOWN
. - Added the following types of recommendations:
MAXIMIZE_CONVERSION_VALUE_OPT_IN
which recommends opting in to the Maximize conversion value bidding strategyIMPROVE_GOOGLE_TAG_COVERAGE
which recommends deploying Google Tag on more pagesPERFORMANCE_MAX_FINAL_URL_OPT_IN
which recommends turning on final URL expansion for your Performance Max campaignsREFRESH_CUSTOMER_MATCH_LIST
which recommends updating a customer list that hasn't been updated in the last 90 daysCUSTOM_AUDIENCE_OPT_IN
which recommends creating a custom audienceLEAD_FORM_ASSET
which recommends adding lead form assets at the campaign or customer levelIMPROVE_DEMAND_GEN_AD_STRENGTH
which recommends improving ad strength on Demand Gen campaigns
Shopping
- Added
CampaignError.CANNOT_LINK_TO_COMPARISON_SHOPPING_SERVICE_ACCOUNT
andCampaignError.CANNOT_TARGET_NETWORK_FOR_COMPARISON_SHOPPING_SERVICE_LINKED_ACCOUNTS
in order to provide more detailed errors for Shopping campaigns linked to a Comparison Shopping Service Center account. - Added the following values to
AssetGroupListingGroupFilterError
:DIMENSION_TYPE_NOT_ALLOWED
DUPLICATE_WEBPAGE_FILTER_UNDER_ASSET_GROUP
FILTER_EXCLUSION_NOT_ALLOWED
LISTING_SOURCE_NOT_ALLOWED
MULTIPLE_LISTING_SOURCES
MULTIPLE_WEBPAGE_CONDITION_TYPES_NOT_ALLOWED
MULTIPLE_WEBPAGE_TYPES_PER_ASSET_GROUP
PAGE_FEED_FILTER_HAS_PARENT
Lifecycle Goals
- Added
update
toCustomerLifecycleGoalOperation
andCampaignLifecycleGoalOperation
to make these operation types consistent with other operation types in the API. ## Archived release notes
See Sunsetted versions for archived release notes.