Release Notes

v18 (2024-10-16)

The following new features and updates were added in v18.

Account Management

• (For allowlisted accounts only) Added DataLinkService.CreateDataLink, which allows linking a Google Ads account to creator videos hosted on the creator's YouTube channel. Video linking enables the Google Ads account to run partnership ads using creator videos.

Ad Groups

• Added AdGroup.exclude_demographic_expansion which lets you exclude demographics from being expanded when optimized_targeting_enabled is true, a feature that was previously only supported for Demand Gen.

Ads

• Added AdGroupAd.ad_group_ad_asset_automation_settings, which allows opting ads into or out of automatic asset generation.
• Added the following values to AssetAutomationType:
  • GENERATE_VERTICAL_YOUTUBE_VIDEOS
  • GENERATE_SHORTER_YOUTUBE_VIDEOS
• Added AdNetworkType.GOOGLE_OWNED_CHANNELS, which is used by ads that serve on Google-owned channels such as YouTube, Gmail, and the Discover feed.

Assets

• Renamed AssetType.DISCOVERY_CAROUSEL_CARD to AssetType.DEMAND_GEN_CAROUSEL_CARD.

Campaigns

• Added metrics.store_visits_last_click_model_attributed_conversions, which returns the number of store visits attributed by the last click model of a campaign.
• Added the following video view-related metrics for a campaign:
  • metrics.video_view_rate_in_feed
  • metrics.video_view_rate_in_stream
  • metrics.video_view_rate_shorts
• Added metrics.results_conversions_purchase, which returns conversion purchases for the unified goals results of a campaign.
• Changed the default value of DemandGenCampaignSettings.upgraded_targeting from false to true.

Criterion

• Added content_criterion_view which returns performance metrics of targeted contents, such as keywords, placements and topics, for Display, Demand Gen and Video campaigns.

Hotel & Travel

• Support for Travel Feeds in Search Ads
  • Added ClickType.TRAVEL_ASSETS to allow segmentation of metrics of Travel Feeds in Search Ads.
  • Added AssetSetType.TRAVEL_FEED which can be used to opt-in and opt-out of using Travel Feed in Search Ads.
• (For allowlisted accounts only) Added travel itinerary as a new conversion value rule with the following new fields and values:
  • ConversionValueRule.itinerary_condition with ValueRuleItineraryCondition, which allows for specifying an advance booking window, an itinerary length, and a travel start days of week
  • ConversionValueRulePrimaryDimensionEnum.ITINERARY
  • ValueRuleSetDimension.ITINERARY
• Added the following segments for campaign and ad_group reports to allow for segmenting performance data based on specific destinations (cities, countries and regions) for Hotel and Search campaigns:
  • segments.travel_destination_city
  • segments.travel_destination_country
  • segments.travel_destination_region

Local Services

• PhoneCallDetails.call_recording_url will be empty, instead of providing an invalid URL if the call recording doesn't exist for the given Local Services lead conversation.
• Added CategoryBid.target_cpa_bid_micro which allows for setting target CPA for a category through Campaign.local_services_campaign_settings.

Performance Max

• Support for brand guidelines
  • Added Campaign.brand_guidelines_enabled which shows whether brand guidelines are enabled for a given Performance Max campaign. If enabled, assets with field_type set to BUSINESS_NAME, LOGO, LANDSCAPE_LOGO must be linked as CampaignAsset resources instead of AssetGroupAsset resources.
  • Added CampaignError.REQUIRED_BUSINESS_NAME_ASSET_NOT_LINKED and CampaignError.REQUIRED_LOGO_ASSET_NOT_LINKED errors, which indicate that Performance Max campaigns with brand guidelines enabled don't have the required CampaignAsset resources linked to the campaign.
  • When brand guidelines are enabled, at least one asset with field_type set to BUSINESS_NAME and at least one with LOGO must be linked to the campaign as CampaignAsset resources. Performance Max campaigns for online sales with a product feed must meet this requirement only when there are assets that are linked to the campaign's asset groups.
  • Added the following values to AssetLinkError:
    • BRAND_ASSETS_NOT_LINKED_AT_ASSET_GROUP_LEVEL, which is thrown when attempting to link brand assets to campaigns as CampaignAsset resources instead of AssetGroupAsset resources in Performance Max campaigns with brand guidelines not enabled.
    • BRAND_ASSETS_NOT_LINKED_AT_CAMPAIGN_LEVEL error, which is thrown when attempting to link brand assets to campaigns as AssetGroupAsset resources instead of CampaignAsset resources in Performance Max campaigns with brand guidelines enabled.
• Added performance_max_placement_view which returns impressions of the placements where Performance Max ads served.
• Added AssetGroupListingGroupFilterError.TREE_WAS_INVALID_BEFORE_MUTATION

Planning

• (For allowlisted accounts only) Added a new service with the method ContentCreatorInsightsService.GenerateCreatorInsights, which allows users to explore insights about top YouTube Creators. This allows customers to search for creators given an audience targeting and content targeting combination or creator insights given a list of YouTube Channel IDs.
• Updates to AudienceInsightsService.GenerateSuggestedTargetingInsights:
  • Moved audience, baseline_audience and data_month into audience_definition.
  • Added audience_description to generate targeting suggestions from a free form text description using Gen AI.
• Added AudienceInsightsService.GenerateTargetingSuggestionMetrics which returns potential reach metrics for given audience targeting combinations.

Recommendations

• RecommendationService.GenerateRecommendations can now be used to generate recommendations about optimized budget suggestions during campaign construction, by including the CAMPAIGN_BUDGET recommendation type in GenerateRecommendationsRequest.recommendation_types[]. This works for Performance Max and Search campaigns.

Reporting

• Replaced the summary_row_setting and return_total_results_count fields of SearchGoogleAdsRequest with the search_settings field, whose type is SearchSettings with the following fields:
  • omit_results
  • return_summary_row
  • return_total_results_count
• Added the following new metrics about general invalid clicks, such as those generated by bots or crawlers, those having irregular patterns. They can be queried with the campaign report.
  • metrics.general_invalid_clicks
  • metrics.general_invalid_click_rate
• Added the following values to QuotaError:
  • EXCESSIVE_SHORT_TERM_QUERY_RESOURCE_CONSUMPTION
  • EXCESSIVE_LONG_TERM_QUERY_RESOURCE_CONSUMPTION

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.

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:
  • offline_conversion_upload_client_summary
    • pending_event_count
    • pending_rate
  • offline_conversion_upload_conversion_action_summary:
    • pending_count

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 on segments.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:
  • campaign.video_campaign_settings.video_ad_inventory_control.allow_in_feed
  • campaign.video_campaign_settings.video_ad_inventory_control.allow_in_stream
  • campaign.video_campaign_settings.video_ad_inventory_control.allow_shorts
• segments.ad_format_type which lets you segment the following reports based on the video ad format type:
  • ad_group
  • ad_group_ad
  • ad_group_ad_asset_view
  • campaign
  • customer

v17 (2024-06-05)

The following features and changes were added in v17.

Ads

• Removed AdService.getAd. This brings the AdService 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:
  • ImageError.UNEXPECTED_SIZE
  • ImageError.FORMAT_NOT_ALLOWED

Assets

• Added new enum: ClickType.AD_IMAGE
• Added the following new reports with new metrics for Performance Max and Search campaigns:
  • campaign_aggregate_asset_view
  • channel_aggregate_asset_view

Audiences

• Added OfflineUserDataJobError.OPERATION_LEVEL_CONSENT_PROVIDED

Batch Jobs

• Added BatchJobError.REQUEST_TOO_LARGE, which will be thrown when the submitted AddBatchJobOperationsRequest is larger than 10484504 bytes.
• Added support for setting MutateOperation.asset_group_operation when using BatchJobService. 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 now AdvertisingChannelType.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 to segments.sk_ad_network_fine_conversion_value.
  • Added segments.sk_ad_network_redistributed_fine_conversion_value.
• The following metrics are now returned with the response even when they are zero. This makes them consistent with other metrics.
  • metrics.all_conversions_value_by_conversion_date
  • metrics.all_conversions_by_conversion_date
  • metrics.conversions_value_by_conversion_date
  • metrics.conversions_by_conversion_date

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 for gender_view
• Added support for metrics.phone_calls for keyword_view

Local Services

• Added LocalServicesLeadService.AppendLeadConversation() used to append a new LocalServicesLeadConversation to LocalServicesLead, 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 with lead_type set to LeadType.MESSAGE can be specified in Conversation.local_services_lead.
• Added new enum values to ConversationType:
  • WHATSAPP to represent a conversation introduced through WhatsApp.
  • ADS_API to represent a conversation introduced using the new LocalServicesLeadService.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 throw QueryError.PROHIBITED_FIELD_COMBINATION_IN_SELECT_CLAUSE. For example, product_link.advertising_partner.customer and product_link.data_partner.data_partner_id cannot be selected in the same query.
• Passing a page_size to GoogleAdsService.Search will result in a RequestError.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 using segments.date when using GoogleAdsService.Search or GoogleAdsService.SearchStream. Segmentation by date is not permitted and will return a ShoppingProductError.UNSUPPORTED_DATE_SEGMENTATION error.

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, use UserListCustomerTypeService.MutateUserListCustomerTypes() instead.
  • Attach or unattach a user list by setting UserListCustomerType.customer_type_category to UserListCustomerTypeCategory.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.

Videos

• Added the following values to ContentLabelType. You can exclude these ContentLabelTypes 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 creating DemandGenVideoResponsiveAdInfo.
• (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 and asset_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 as MutateCustomerSkAdNetworkConversionValueSchemaRequest.enable_warnings. When set to true, any non-blocking errors pertaining to operation failures will be returned as MutateCustomerSkAdNetworkConversionValueSchemaResponse.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 and local_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 and BrandSafetySuitability 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 from AccountLink to ProductLink and ProductLinkInvitation.
• Removed data_partner and google_ads from AccountLink.
• Added IdentityVerificationService to manage advertiser verification.
  • StartIdentityVerification() is used to start a verification session using the provided verification_program. It creates a new verification session and returns an empty response for a successfully created verification.
    • Added IdentityVerificationProgram.ADVERTISER_IDENTITY_VERIFICATION.
  • GetIdentityVerification() can be used for retrieving verification information, which returns several objects of IdentityVerification. Each IdentityVerification includes:
    • verification_program which is the identity verification program type
    • identity_verification_requirement that contains details related to the deadline by which the advertiser should finish verification
    • verification_progress that contains details related to the verification session including:
      • program_status represents the current status of this verification session
      • action_url directs the customer to a URL to complete the verification.
      • invitation_link_expiration_time represents the expiration date for the action_url
  • Enums:
    • IdentityVerificationProgram
    • IdentityVerificationProgramStatus
  • Errors:
    • IdentityVerificationError
• Added AuthorizationError.ACTION_NOT_PERMITTED_FOR_SUSPENDED_ACCOUNT.

Assets

• Changes to asset_group:
  • Added support for time-related segments, such as segments.year and segments.month.
  • Made campaign an attributed resource instead of segmenting resource.

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 corresponding DemandGenProductAdInfo, available to Demand Gen campaigns with a non-null Campaign.shopping_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:
  • activity_state
  • activity_city
• Added support for the following segments to travel_activity_performance_view:
  • segments.activity_city
  • segments.activity_country
  • segments.activity_state

Local Services

• Added LocalServicesVerificationArtifact.business_registration_check_verification_artifact and BusinessRegistrationCheckArtifact 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 from AudienceInsightsAttributeMetadata.

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 to UNSPECIFIED instead of UNKNOWN.
• Added the following types of recommendations:
  • MAXIMIZE_CONVERSION_VALUE_OPT_IN which recommends opting in to the Maximize conversion value bidding strategy
  • IMPROVE_GOOGLE_TAG_COVERAGE which recommends deploying Google Tag on more pages
  • PERFORMANCE_MAX_FINAL_URL_OPT_IN which recommends turning on final URL expansion for your Performance Max campaigns
  • REFRESH_CUSTOMER_MATCH_LIST which recommends updating a customer list that hasn't been updated in the last 90 days
  • CUSTOM_AUDIENCE_OPT_IN which recommends creating a custom audience
  • LEAD_FORM_ASSET which recommends adding lead form assets at the campaign or customer level
  • IMPROVE_DEMAND_GEN_AD_STRENGTH which recommends improving ad strength on Demand Gen campaigns

Shopping

• Added CampaignError.CANNOT_LINK_TO_COMPARISON_SHOPPING_SERVICE_ACCOUNT and CampaignError.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 to CustomerLifecycleGoalOperation and CampaignLifecycleGoalOperation to make these operation types consistent with other operation types in the API. ## Archived release notes

See Sunsetted versions for archived release notes.