Release Notes

10.1.0 (2022-04-27)

The functionality and changes below were added in v10.1.0.

Assets

• Added the following for lead forms:
  • Support for retrieving submitted lead form data through LeadFormSubmissionData using GoogleAdsService.Search and GoogleAdsService.SearchStream
  • LeadFormAsset.custom_question_fields
• Added the following asset types:
  • Added dynamic_real_estate_asset to Asset to support dynamic real estate assets.
  • Added dynamic_custom_asset to Asset to support dynamic custom assets.
  • Added dynamic_hotels_and_rentals_asset to Asset to support dynamic hotels and rentals assets.
  • Added dynamic_flights_asset to Asset to support dynamic flights assets.
  • Added dynamic_travel_asset to Asset to support dynamic travel assets.
  • Added dynamic_local_asset to Asset to support dynamic local assets.
  • Added dynamic_jobs_asset to Asset to support dynamic jobs assets.
• Added support for the following fields to asset_group_product_group_view:
  • asset_group
  • asset_group_listing_group_filter
• Added ad_group_ad_asset_combination_view.enabled.
• Added AssetError.NAME_CONFLICT_FOR_ASSET_TYPE.

Audiences

• Added support for metrics.absolute_top_impression_percentage and metrics.top_impression_percentage in campaign_audience_view and ad_group_audience_view.
• Added ResourceLimitType.RULE_BASED_USER_LISTS_PER_CUSTOMER.
• Added the following values to AudienceError:
  • AUDIENCE_SEGMENT_NOT_FOUND
  • AUDIENCE_SEGMENT_TYPE_NOT_SUPPORTED
  • DUPLICATE_AUDIENCE_SEGMENT
  • TOO_MANY_SEGMENTS
  • TOO_MANY_DIMENSIONS_OF_SAME_TYPE
  • IN_USE

Batch Jobs

• Added BatchJobOperation.remove to support removing batch jobs in the PENDING state.

Campaigns

• Added support for retrieving, creating, and updating Discovery campaigns, their ad groups, and their ads.
  • Enums:
    • AdvertisingChannelType.DISCOVERY
    • AdType.DISCOVERY_CAROUSEL
    • AdType.DISCOVERY_MULTI_ASSET
    • AssetType.DISCOVERY_CAROUSEL_CARD
• Added support for retrieving, creating, and updating campaign groups:
  • Resource: CampaignGroup
  • Service: CampaignGroupService
  • Fields in other resources:
    • Campaign.campaign_group
    • GoogleAdsRow.campaign_group
  • Enums:
    • CampaignGroupError
    • CampaignGroupStatus
• Local Services campaigns, previously in Beta, are now in generally availability
• Added legacy support for the following dimensions to ListingDimensionInfo for Display campaigns only:
  • ProductGroupingInfo
  • ProductLabelsInfo
  • ProductLegacyConditionInfo
  • ProductTypeFullInfo

Change History

• Added the following values to ChangeEventResourceType:
  • ASSET_SET
  • ASSET_SET_ASSET
  • CAMPAIGN_ASSET_SET

Conversions

• Added ConversionTrackingSetting.google_ads_conversion_customer, used to determine which Google Ads account is managing your account's conversions.
• Added ClickConversion.conversion_environment to support reporting the environment on which a conversion was recorded. This feature is available to allowlisted accounts only.
• Added support for metrics.all_conversions_value and metrics.all_conversions in conversion_action.
• Added ConversionValueRuleSetError.UNSUPPORTED_CONVERSION_ACTION_CATEGORIES.
• Added ConversionAdjustmentUploadError.MISSING_ORDER_ID_FOR_WEBPAGE.
• Added ConversionUploadError.CUSTOMER_NOT_ACCEPTED_CUSTOMER_DATA_TERMS.

Criteria

• Added CriterionError.CANNOT_TARGET_CUSTOMER_MATCH_USER_LIST.

Experiments

• Added ExperimentError.STATUS_TRANSITION_INVALID.

Hotel Ads

• Added support for getting hotel_center_id through AccountLink.hotel_center.

Planning

• Added KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics. It returns the historical metrics for a given list of keywords without asking for any plan, campaigns, or ad groups.
• Added KeywordPlanHistoricalMetrics.average_cpc_micros which is the average cost per click in micros of a given keyword.
  • Added a new field HistoricalMetricsOption.include_average_cpc, which is used in GenerateKeywordIdeasRequest.historical_metrics_options as an option to request KeywordPlanHistoricalMetrics.average_cpc_micros to be included in the response. The default value if not specified is false.
• Added GenerateKeywordIdeaResult.close_variants which is the list of close variants from the requested keywords that are combined into this GenerateKeywordIdeaResult.

Reporting

• segments.click_type now returns CROSS_NETWORK for Performance Max and Discovery campaigns.
• Added the following fields for SKAdNetwork conversion segments, available when fetching the data of customer or campaign:
  • metrics.sk_ad_network_conversions
  • segments.sk_ad_network_attribution_credit
• Made metrics.absolute_top_impression_percentage and metrics.top_impression_percentage compatible with segments.geo_target_region and segments.geo_target_city.

Video

• Added VideoResponsiveAdInfo.breadcrumb1 and VideoResponsiveAdInfo.breadcrumb2.

10.0 (2022-02-09)

The functionality and changes below were added in v10.0.

All Services

The get method and any services that exclusively had a get method have been removed. Retrieve objects with Search and SearchStream from GoogleAdsService.

Account Management

• Added Customer.status and CustomerClient.status, whose type is CustomerStatus, to show the status of the account.
• CustomerClient will contain inactive accounts in addition to active and test accounts.

Ads

• Renamed Video TrueView Discovery Ad format to In-Feed Video Ad:
  • VideoTrueViewDiscoveryAdInfo is renamed to InFeedVideoAdInfo.
  • AdType.VIDEO_TRUEVIEW_DISCOVERY_AD is renamed to AdType.IN_FEED_VIDEO_AD.
• Renamed MutateOperation.customizer_customizer_operation to MutateOperation.customer_customizer_operation.

Assets

• Added support for ad_group_ad_asset_combination_view for responsive search ads.
• Added support for reporting the performance of App pre registration ads in ad_group_ad_asset_view.
• For Image and Media Bundle assets (Asset that has image_asset and media_bundle_asset set, respectively):
  • Made name required.
  • Added support for auto-renaming the asset names on creation. If an asset exists with the same name but different content, it is renamed by appending the specified name with a timestamp and a counter.
• For the following asset types, if an asset with a different name having the same content already exists then the asset uploaded will be silently dropped.
  • Image
  • Media Bundle
  • Text
  • Call to Action
  • Book on Google
• Added the following values related to asset sets to ResourceLimitType:
  • PAGE_FEED_ASSET_SETS_PER_CUSTOMER
  • DYNAMIC_EDUCATION_FEED_ASSET_SETS_PER_CUSTOMER
  • ASSET_PER_PAGE_FEED_ASSET_SET
  • ASSET_PER_DYNAMIC_EDUCATION_FEED_ASSET_SET
• Added the following values to AssetError:
  • MOBILE_APP_INVALID_APP_ID
  • MOBILE_APP_INVALID_FINAL_URL_FOR_APP_DOWNLOAD_URL
  • NAME_REQUIRED_FOR_ASSET_TYPE

Audiences

• Added support for Audience used to create a targeting based on created dimensions, such as demographics or memberships in user lists and user interests:
  • Resource: Audience
  • Service: AudienceService
  • Fields in other resources:
    • GoogleAdsRow.audience
    • Campaign.audience_setting
    • AdGroup.audience_setting
    • AdGroupCriterion.audience
  • Enums:
    • AudienceError
    • CriterionType.AUDIENCE

Bidding

• Removed support for creating seasonality adjustments on manager accounts.
• Added the following values to BiddingError:
  • BIDDING_STRATEGY_AND_BUDGET_MUST_BE_ALIGNED
  • BIDDING_STRATEGY_AND_BUDGET_MUST_BE_ATTACHED_TO_THE_SAME_CAMPAIGNS_TO_ALIGN
  • BIDDING_STRATEGY_AND_BUDGET_MUST_BE_REMOVED_TOGETHER

Campaigns

• Smart campaigns have exited open beta and entered general availability.
• Added support for Local Services Ads campaigns as open beta.
  • They have AdvertisingChannelType as LOCAL_SERVICES.
  • Added support for retrieving these campaigns using Search and SearchStream.
  • Added support for updating their status and amount_micros of their associated CampaignBudget objects.
• Performance Max Campaigns now support asset group signals which advertisers can use to tell the campaign who's most likely to convert.
• Added Campaign.use_vehicle_inventory for Smart Shopping campaigns.

Conversions

• Added the following fields to the conversion_tracking_setting attribute of Customer:
  • conversion_tracking_status indicates whether the customer is using conversion tracking, and who is the conversion tracking owner.
  • accepted_customer_data_terms indicates if the conversion tracking owner has accepted the customer data terms.
  • enhanced_conversions_for_leads_enabled indicates if the customer has opted into enhanced conversions for leads.
• Made ConversionAction.primary_for_goal optional to support setting the value to false during create operations.
• Made ConversionValueRuleSet.attachment_type immutable.
• Added ConversionValueRuleSet.conversion_action_categories and ValueRuleSetDimension.NO_CONDITION to support conversion value rules for store visits and store sales.
• Added the following values to ConversionValueRuleSetError:
  • INELIGIBLE_CONVERSION_ACTION_CATEGORIES
  • DIMENSION_NO_CONDITION_USED_WITH_OTHER_DIMENSIONS
  • DIMENSION_NO_CONDITION_NOT_ALLOWED
• Removed LEAD from the ConversionActionCategory enum and replaced with the following new values:
  • QUALIFIED_LEAD
  • CONVERTED_LEAD
• Added ExternalConversionSource.DISPLAY_AND_VIDEO_360_FLOODLIGHT.

Experiments

• Added a new ExperimentService with a set of new resources, which is a replacement for campaign experiments.

Hotel Ads

• Added hotel_reconciliation.campaign and added support for the following metrics:
  • metrics.hotel_commission_rate_micros
  • metrics.hotel_expected_commission_cost

Recommendations

• Added support for returning ResponsiveSearchAdAssetRecommendation.
• Added support for returning UseBroadMatchKeywordRecommendation.

Reporting

• Fixed inconsistencies where rows with zero metrics were returned when segments were selected in some reports. All reports will now follow the expected behavior of ignoring zero-metric rows in reports that select metrics and segments.
• Added a new meta parameter omit_unselected_resource_names. When set to true, the response from GoogleAdsService will only return resource name fields that you explicitly request in the SELECT clause of your query.
• When retrieving Campaign.start_date and Campaign.end_date, the date returned will always be formatted based on the time zone of the customer specified as customer_id of SearchGoogleAdsRequest or SearchGoogleAdsStreamRequest. Previously, the returned date could vary based on the time zone of the manager account specified in login-customer-id.
• Added support for metrics.absolute_top_impression_percentage and metrics.top_impression_percentage
  • in geographic_view
  • with segments.hour
• Added support for the following segments for metrics.sk_ad_network_conversions (SKAdNetwork conversions), which is available when fetching the data of customer or campaign:
  • segments.sk_ad_network_user_type
  • segments.sk_ad_network_ad_event_type
  • segments.sk_ad_network_source_app.sk_ad_network_source_app_id
• Added metrics.biddable_app_install_conversions and metrics.biddable_app_post_install_conversions.

RMF

• Added new requirements for Performance Max and Smart campaigns. We are also documenting the required minimum functionality for other developer tools such as shopping, hotel and app campaigns, and simplifying standard shopping campaigns to align with full service campaigns.

9.0 (2021-11-03)

The functionality and changes below were added in v9.0.

Account Management

• Added the following errors:
  • ManagerLinkError.CREATING_ENABLED_LINK_NOT_ALLOWED
  • ManagerLinkError.CUSTOMER_CANNOT_MANAGE_SELF

Ads

• Added support for ad customizers for Responsive Search Ads through the following services:
  • CustomizerAttributeService
  • CustomerCustomizerService
  • CampaignCustomizerService
  • AdGroupCustomizerService
  • AdGroupCriterionCustomizerService
• Added support for pre-registration ads which helps in pre-registering the app or game from the Play store to help gauge interest before an app or a game is available to install. For more information, see App campaigns for pre-registration.
• Added the following enums to AdError:
  • CALL_AD_VERIFICATION_URL_FINAL_URL_DOES_NOT_HAVE_SAME_DOMAIN
  • CALL_AD_FINAL_URL_AND_VERIFICATION_URL_CANNOT_BOTH_BE_EMPTY
  • CUSTOMIZER_TYPE_FORBIDDEN_FOR_FIELD
  • INVALID_CUSTOMIZER_ATTRIBUTE_NAME

Assets

• Added the following asset types, which will be available in all accounts by the end of 2021:
  • Added price_asset to Asset to support price assets.
  • Added hotel_callout_asset to Asset to support hotel callout assets.
  • Added mobile_app_asset to Asset to support mobile app assets.
  • Added call_asset to Asset to support call assets.
  • Added call_to_action to Asset to support call to action assets.
• Added support for asset groups for Performance Max:
  • Added AssetGroupService to allow for removing AssetGroup, which represents a bunch of assets. Use GoogleAdsService.mutate to create or update an AssetGroup. An asset group is used in a Performance Max campaign to group assets, a final URL, and audience signals. The asset group and the conversion goals are pulled together to create a campaign.
  • Added AssetGroupAssetService to allow for adding/updating/removing AssetGroupAsset, which is a link between an asset and an asset group.
  • Added AssetGroupListingGroupFilterService to allow for adding/updating/removing AssetGroupListingGroupFilter, which represents a listing group filter tree node in an asset group.
  • Added asset_group_product_group_view, for retrieving product groups in an asset group. At the time of the release, requests for this view will return an error. The view will start returning data at a later date.
• Added support for asset sets:
  • Added AssetSetService to allow for adding/updating/removing AssetSet, which represents a collection of assets, which will eventually replace the FeedService. AssetSetType represents feed types that are currently supported.
  • Added AssetSetAssetService to allow for adding/updating/removing AssetSetAsset, which represents a link between an asset and an asset set.
  • Added CampaignAssetSetService to allow for adding/updating/removing CampaignAssetSet, which represents a link between a campaign and an asset set.
• Added support for reporting the performance of the following ad types in ad_group_ad_asset_view:
  • App engagement ads
  • Responsive search ads
• Added AssetLinkError.YOUTUBE_VIDEO_DURATION_NOT_DEFINED.
• Added FeedError.LEGACY_EXTENSION_TYPE_READ_ONLY for extension types migrated to Asset.
• TextAsset is now read/write.
• Added values to AssetError:
  • CALL_CARRIER_SPECIFIC_SHORT_NUMBER_NOT_ALLOWED
  • CALL_CUSTOMER_CONSENT_FOR_CALL_RECORDING_REQUIRED
  • CALL_DISALLOWED_NUMBER_TYPE
  • CALL_INVALID_CONVERSION_ACTION
  • CALL_INVALID_COUNTRY_CODE
  • CALL_INVALID_DOMESTIC_PHONE_NUMBER_FORMAT
  • CALL_INVALID_PHONE_NUMBER
  • CALL_PHONE_NUMBER_NOT_SUPPORTED_FOR_COUNTRY
  • CALL_PREMIUM_RATE_NUMBER_NOT_ALLOWED
  • CALL_VANITY_PHONE_NUMBER_NOT_ALLOWED
  • PRICE_HEADER_SAME_AS_DESCRIPTION

Audiences

• Added support for warnings for OfflineUserDataJobService through AddOfflineUserDataJobOperationsRequest.enable_warnings. When enable_warnings is set to true and the request succeeds, any non-blocking errors relating to operation failures will be returned as AddOfflineUserDataJobResponse.warning. No warnings are returned if the request fails. Learn more.
• Added CreateOfflineUserDataJobRequest.enable_match_rate_range_preview. When it's set to true, the match rate range for the uploaded offline user data job will be calculated and returned as OfflineUserDataJobMetadata.match_rate_range, which you can retrieve using the newly added OfflineUserDataJob.operation_metadata field.
  • match_rate_range shows the range of the match rate (efficacy) of your Customer Match uploads, which is the number of matched user data rows divided by the total number of Customer Match uploaded rows.
• Added UserAttribute.shopping_loyalty to allow for sending loyalty-related data with UserAttribute.
• Added OfflineUserDataJobError.INVALID_ITEM_ID.

Bidding

• Added the following fields for MaximizeConversions and MaximizeConversionValue portfolio bidding strategies:
  • MaximizeConversions.cpc_bid_ceiling_micros
  • MaximizeConversions.cpc_bid_floor_micros
  • MaximizeConversionValue.cpc_bid_ceiling_micros
  • MaximizeConversionValue.cpc_bid_floor_micros
• Removed support for CampaignCriterionSimulation for Shopping campaigns.
• Removed support for AdGroupSimulation for Video campaigns.

Billing

• Added the following errors:
  • BillingSetupError.FUTURE_START_TIME_PROHIBITED
  • InvoiceError.BILLING_SETUP_NOT_ON_MONTHLY_INVOICING
  • InvoiceError.NON_SERVING_CUSTOMER

Campaigns

• Added support for Performance Max campaigns, which is a new campaign type that provides a unified buying service to virtually all Google Ads inventory.

• Changes in Smart campaigns:

  • Smart campaigns have entered open beta and users no longer need to be allowlisted to use them.

  • Added SmartCampaignSuggestService.SuggestKeywordThemes to generate keyword theme suggestions for Smart campaigns based on the business details provided.

    This provides more comprehensive suggestions than SuggestKeywordThemeConstants, and is now the recommended way to generate keyword themes for a Smart campaign.

  • Improved error handling and additional user-facing error codes.

Conversions

• Added support for conversion goals to help you more easily optimize towards your advertising objects.
• Changes related to ConversionAdjustmentUploadService:
  • Moved gclid_date_time_pair and order_id out of the oneof field of ConversionAdjustment.
    • If adjustment_type is ENHANCEMENT, order_id is required. We recommend advertisers to set gclid_date_time_pair to GclidDateTimePair.conversion_date_time. GclidDateTimePair.gclid is optional.
    • If ConversionAdjustmentType is of other types, only one of order_id and gclid_date_time_pair can be set. Otherwise, a GCLID_DATE_TIME_PAIR_AND_ORDER_ID_BOTH_SET error is thrown.
• Changes related to ConversionUploadService:
  • Changed CartData.merchant_id from string to int64.
  • Added ClickConversion.gbraid and ClickConversion.wbraid fields as click identifiers for iOS devices.
• Made UserIdentifier.user_identifier_source optional.
• Improved ConversionUploadService and ConversionAdjustmentService to report an error if the ClickConversion, CallConversion, or ConversionAdjustment in a mutate operation already exists or is a duplicate to another one in the same mutate operation. Prior to v9, the Google Ads API would silently ignore such operations. The error returned by each service will be as follows:
  • For ConversionUploadService:
    • For a click conversion: a ConversionUploadError with CLICK_CONVERSION_ALREADY_EXISTS or DUPLICATE_CLICK_CONVERSION_IN_REQUEST
    • For a call conversion: a ConversionUploadError with CALL_CONVERSION_ALREADY_EXISTS or DUPLICATE_CALL_CONVERSION_IN_REQUEST
  • For ConversionAdjustmentService:
    • For a restatement: a ConversionAdjustmentUploadError with RESTATEMENT_ALREADY_EXISTS or DUPLICATE_ADJUSTMENT_IN_REQUEST
    • For an enhancement: a ConversionAdjustmentUploadError with CONVERSION_ALREADY_ENHANCED or DUPLICATE_ENHANCEMENT_IN_REQUEST
• Removed INVALID_USER_IDENTIFIER_SOURCE from ConversionAdjustmentUploadError and ConversionUploadError.

Feeds

• Deprecated extension setting services:

  • AdGroupExtensionSettingService
  • CampaignExtensionSettingService
  • CustomerExtensionSettingService
  • ExtensionFeedItemService

• Deprecated most use cases of feed service in favor of assets:

  • All extensions apart from location extensions should migrate to assets.
  • DSA page feed should migrate to assets.
  • Dynamic remarketing for education should migrate to assets. Other dynamic remarketing types will follow in a release.
  • Ad customizers are the only non-deprecated use case for feeds.

Hotel Ads

• Added support for retrieving hotel_reconciliation resources, which contain booking information to reconcile bookings from commission campaigns.
• Removed HOTEL_ADS_COMMISSION from BudgetType.

Mutates

• Added MutateError.OPERATION_DOES_NOT_SUPPORT_PARTIAL_FAILURE, thrown when MutateGoogleAdsRequest.partial_failure is set to true but MutateGoogleAdsRequest.mutate_operations[] contains mutate operations that don't support partial failure.

Planning

• Added PlannableLocation.location_type which contains the location's type (COUNTRY, STATE, etc.).
• Added PlannableLocation.country_code which contains the ISO-3166-1 alpha-2 code associated with the location.
• Added CampaignDuration.date_range which allows the duration of a planning campaign to be specified as a date range.

Reporting

• A value for any of the following date-related segments in the WHERE clause must be the start of the field's period:

  Fields	Allowed filter values
  segments.week	YYYY-MM-DD where DD is the date that is Monday and YYYY and MM are valid year and month values, respectively.
  segments.month	YYYY-MM-01 where YYYY and MM are valid year and month values, respectively.
  segments.quarter	YYYY-01-01 or YYYY-04-01 or YYYY-07-01 or YYYY-10-01.

  Failing to set the correct values will result in a MISALIGNED_DATE_FOR_FILTER error.

• segments.sk_ad_network_conversion_value now supports distinguishing between 0 conversion value and conversion value missing from the postback received from Apple. Note that this feature will only be available for SKAdNetwork conversions received after September 20th, 2021.

• Published the phone_calls, phone_impressions, and phone_through_rate metric fields in the following resources:

  • ad_group_asset
  • asset_field_type_view
  • campaign_asset
  • customer_asset

RMF

• RMF requirements have been considerably simplified.

Video

• Added VideoTrueViewDiscoveryAdInfo.thumbnail.
• Added VideoNonSkippableInStreamAdInfo.action_button_label and VideoNonSkippableInStreamAdInfo.action_headline.
• Removed the optional keyword from the following fields to be consistent with their behaviors, since null and the default values of those fields (empty strings) have the same meaning for the Google Ads API:
  • VideoOutstreamAdInfo.headline
  • VideoOutstreamAdInfo.description
  • VideoTrueViewDiscoveryAdInfo.headline
  • VideoTrueViewDiscoveryAdInfo.description1
  • VideoTrueViewDiscoveryAdInfo.description2
• Migrated Video ads from using MediaFile to represent videos and images to using assets.
  • Changed the type of the following fields from string to AdImageAsset:
    • VideoBumperInStreamAdInfo.companion_banner
    • VideoNonSkippableInStreamAdInfo.companion_banner
    • VideoTrueViewInStreamAdInfo.companion_banner
  • Replaced VideoAdInfo.media_file (available until v8) with VideoAdInfo.video and changed the type from string to AdVideoAsset.