版本说明

v19 (2025-02-26)

v19 中新增了以下功能和变更。

账号管理

• 为 CustomerError 添加了以下值，以应对即将发生的更改：
  • CREATION_DENIED_FOR_POLICY_VIOLATION
  • CREATION_DENIED_INELIGIBLE_MCC

Ads

• 添加了 DemandGenMultiAssetAdInfo.tall_portrait_marketing_images，以支持在需求开发广告中使用宽高比为 9:16 的纵向图片素材资源。

素材资源

• （仅适用于列入许可名单的账号）通过 Asset.business_message_asset、BusinessMessageAsset 以及以下枚举和错误添加了对消息素材资源的支持。
  • 枚举：
    • AssetFieldType.BUSINESS_MESSAGE
    • AssetType.BUSINESS_MESSAGE
    • BusinessMessageCallToActionType
    • BusinessMessageProvider
  • 错误：
    • AssetError.CUSTOMER_NOT_ON_ALLOWLIST_FOR_WHATSAPP_MESSAGE_ASSETS
    • ResourceLimitType
      • BUSINESS_MESSAGE_ASSET_LINKS_PER_CUSTOMER
      • WHATSAPP_BUSINESS_MESSAGE_ASSET_LINKS_PER_CAMPAIGN
      • WHATSAPP_BUSINESS_MESSAGE_ASSET_LINKS_PER_AD_GROUP
• 添加了 AssetAutomationType.GENERATE_LANDING_PAGE_PREVIEW，以支持自动生成着陆页预览。
• AssetAutomationType.GENERATE_SHORTER_YOUTUBE_VIDEOS 现在默认已选择启用自适应需求开发视频广告。
• （仅适用于已列入许可名单的账号；许可名单目前处于关闭状态）添加了 Asset.app_deep_link_asset 和 AppDeepLinkAsset。

转化次数

• 转化目标
  • LifecycleGoalValueSettings.high_lifetime_value 已结束 Beta 版测试，现在可变。
  • 添加了 CustomerLifecycleGoal.owner_customer，用于显示拥有客户生命周期目标的客户的资源名称。
• 废弃了 ConversionActionType.SALESFORCE。

Feed

• 移除了所有与 Feed 相关的实体，例如 Feed、FeedMapping、FeedService、AdGroupFeed、feed_placeholder_view 等。用户现在应使用素材资源来实现相同的目的。如需查看所有已移除实体的列表，请参阅迁移备注。

酒店和旅行

• 将 ValueRuleItineraryAdvanceBookingWindow 的 min_days 和 max_days 设为 optional 字段，以允许将 0 指定为值。这支持定位到当天进行的旅行搜索。

效果最大化广告系列

• （仅适用于列入许可名单的账号）品牌推广指南
  • 将 Campaign.brand_guidelines_enabled 设为仅在制作效果最大化广告系列时可变。
  • 此目标与指定旅行目标的效果最大化广告系列不兼容。
  • 如需为现有效果最大化广告系列启用品牌推广指南，请使用新添加的 CampaignService.EnablePMaxBrandGuidelines。不支持停用品牌推广指南。
  • 添加了 Campaign.brand_guidelines 和 BrandGuidelines，以允许设置品牌的颜色和字体系列。
  • 新增了错误值：
    • BatchJobError.CAMPAIGN_AND_CAMPAIGN_ASSET_TRANSACTION_FAILURE
    • BrandGuidelinesMigrationError
    • BRAND_GUIDELINES_ALREADY_ENABLED
    • CANNOT_ENABLE_BRAND_GUIDELINES_FOR_REMOVED_CAMPAIGN
    • BRAND_GUIDELINES_LOGO_LIMIT_EXCEEDED
    • CANNOT_AUTO_POPULATE_BRAND_ASSETS_WHEN_BRAND_ASSETS_PROVIDED
    • AUTO_POPULATE_BRAND_ASSETS_REQUIRED_WHEN_BRAND_ASSETS_OMITTED
    • TOO_MANY_ENABLE_OPERATIONS
  • CampaignError
    • BRAND_GUIDELINES_NOT_ENABLED_FOR_CAMPAIGN
    • BRAND_GUIDELINES_MAIN_AND_ACCENT_COLORS_REQUIRED
    • BRAND_GUIDELINES_COLOR_INVALID_FORMAT
    • BRAND_GUIDELINES_UNSUPPORTED_FONT_FAMILY
    • BRAND_GUIDELINES_UNSUPPORTED_CHANNEL
    • CANNOT_ENABLE_BRAND_GUIDELINES_FOR_TRAVEL_GOALS
    • CUSTOMER_NOT_ALLOWLISTED_FOR_BRAND_GUIDELINES
• 添加了 AssetAutomationType.GENERATE_ENHANCED_YOUTUBE_VIDEOS，以支持为效果最大化广告系列自动生成增强型视频素材资源。

规划

• （仅限列入许可名单的账号）添加了 ContentCreatorInsightsService.GenerateTrendingInsights，让用户可以根据指定的受众群体定义查看 YouTube 上的热门内容主题。
• 添加了 GenerateCreatorInsightsRequest.country_locations[]，用于指定要按给定条件搜索的国家/地区
• 添加了 GenerateCreatorInsightsRequest.search_brand，用于指定要搜索的品牌
• 向 YouTubeChannelInsights 添加了新字段，以便为 search_channels 请求提供其他渠道信息：
  • channel_url
  • channel_description
  • top_videos
• 向 AudienceInsightsAttributeMetadata 添加了新的元数据字段：
  • youtube_video_metadata
  • user_interest_attribute_metadata
  • knowledge_graph_attribute_metadata

视频

• 在 DataLinkService.CreateDataLink 发布后，我们添加了以下方法，以允许更改之前创建的数据关联：
  • RemoveDataLink，用于在 Google Ads 账号中移除数据关联
  • UpdateDataLink - 用于在 Google Ads 账号中接受、拒绝和撤消数据关联
• 从以下枚举中移除了对 VIDEO_OUTSTREAM 的支持：
  • AdType
  • AdvertisingChannelSubType
  • AdGroupType

v18 (2024-10-16)

v18 中添加了以下新功能和更新。

账号管理

• （仅限列入许可名单的账号）添加了 DataLinkService.CreateDataLink，可将 Google Ads 账号与创作者在其 YouTube 频道上托管的创作者视频相关联。通过视频关联，Google Ads 账号可以使用创作者视频投放合作伙伴广告。

广告组

• 添加了 AdGroup.exclude_demographic_expansion，可让您在 optimized_targeting_enabled 为 true 时禁止展开受众特征（此功能之前仅适用于需求开发广告系列）。

Ads

• 添加了 AdGroupAd.ad_group_ad_asset_automation_settings，可让广告选择启用或停用自动素材资源生成功能。
• 向 AssetAutomationType 添加了以下值：
  • GENERATE_VERTICAL_YOUTUBE_VIDEOS
  • GENERATE_SHORTER_YOUTUBE_VIDEOS
• 添加了 AdNetworkType.GOOGLE_OWNED_CHANNELS，供在 Google 自有渠道（例如 YouTube、Gmail 和 Google 探索信息流）上投放的广告使用。

素材资源

• 将 AssetType.DISCOVERY_CAROUSEL_CARD 重命名为 AssetType.DEMAND_GEN_CAROUSEL_CARD。

广告系列

• 添加了 metrics.store_visits_last_click_model_attributed_conversions，用于返回根据广告系列的最终点击归因模型归因的实体店光顾次数。
• 为广告系列添加了以下与视频观看次数相关的指标：
  • metrics.video_view_rate_in_feed
  • metrics.video_view_rate_in_stream
  • metrics.video_view_rate_shorts
• 添加了 metrics.results_conversions_purchase，用于返回广告系列统一目标结果的转化购买次数。
• 将 DemandGenCampaignSettings.upgraded_targeting 的默认值从 false 更改为 true。

标准

• 添加了 content_criterion_view，用于返回展示广告系列、需求开发广告系列和视频广告系列的定位内容（例如关键字、展示位置和主题）的效果指标。

酒店和旅行

• 支持搜索广告中的旅游 Feed
  • 添加了 ClickType.TRAVEL_ASSETS，以允许对搜索广告中的旅游 Feed 的指标进行细分。
  • 添加了 AssetSetType.TRAVEL_FEED，可用于选择启用和停用搜索广告中的旅游 Feed。
• （仅适用于列入许可名单的账号）添加了行程作为新的转化价值规则，其中包含以下新字段和值：
  • ConversionValueRule.itinerary_condition 与 ValueRuleItineraryCondition 搭配使用，可指定提前预订期限、行程长度和旅行开始时间（周几）
  • ConversionValueRulePrimaryDimensionEnum.ITINERARY
  • ValueRuleSetDimension.ITINERARY
• 为 campaign 和 ad_group 报告添加了以下细分，以便您根据酒店广告系列和搜索广告系列的特定目的地（城市、国家/地区和区域）细分效果数据：
  • segments.travel_destination_city
  • segments.travel_destination_country
  • segments.travel_destination_region

本地生活服务

• 如果给定本地服务潜在客户对话没有通话录音，PhoneCallDetails.call_recording_url 将为空，而不是提供无效的网址。
• 添加了 CategoryBid.target_cpa_bid_micro，可通过 Campaign.local_services_campaign_settings 为类别设置目标每次转化费用。

效果最大化广告系列

• 支持品牌推广指南
  • 添加了 Campaign.brand_guidelines_enabled，用于显示是否为给定效果最大化广告系列启用了品牌规范。如果启用此功能，则将 field_type 设置为 BUSINESS_NAME、LOGO、LANDSCAPE_LOGO 的素材资源必须作为 CampaignAsset 资源（而非 AssetGroupAsset 资源）进行关联。
  • 添加了 CampaignError.REQUIRED_BUSINESS_NAME_ASSET_NOT_LINKED 和 CampaignError.REQUIRED_LOGO_ASSET_NOT_LINKED 错误，用于指示启用了品牌推广指南的效果最大化广告系列未与所需的 CampaignAsset 资源相关联。
  • 启用品牌推广指南后，必须将至少 1 项 field_type 设为 BUSINESS_NAME 的素材资源和至少 1 项 LOGO 的素材资源作为 CampaignAsset 资源关联到广告系列。只有当有素材资源与广告系列的素材资源组相关联时，以提高线上销售额为目标且使用产品 Feed 的效果最大化广告系列才必须满足此要求。
  • 向 AssetLinkError 添加了以下值：
    • BRAND_ASSETS_NOT_LINKED_AT_ASSET_GROUP_LEVEL：在品牌推广指南未启用的情况下，如果尝试将品牌素材资源作为 CampaignAsset 资源（而非 AssetGroupAsset 资源）关联到效果最大化广告系列，系统会抛出此错误。
    • BRAND_ASSETS_NOT_LINKED_AT_CAMPAIGN_LEVEL 错误：在启用了品牌规范的效果最大化广告系列中，如果尝试将品牌素材资源作为 AssetGroupAsset 资源（而非 CampaignAsset 资源）关联到广告系列，系统会抛出此错误。
• 添加了 performance_max_placement_view，用于返回投放了效果最大化广告系列的展示位置的展示次数。
• 添加了 AssetGroupListingGroupFilterError.TREE_WAS_INVALID_BEFORE_MUTATION

规划

• （仅限列入许可名单的账号）使用 ContentCreatorInsightsService.GenerateCreatorInsights 方法添加了一项新服务，可让用户探索有关热门 YouTube 创作者的分析数据。这样，客户就可以根据受众群体定位条件和内容定位条件的组合来搜索创作者，也可以根据 YouTube 频道 ID 列表来获取创作者数据洞见。
• 对 AudienceInsightsService.GenerateSuggestedTargetingInsights 进行了更新：
  • 将 audience、baseline_audience 和 data_month 移至 audience_definition。
  • 添加了 audience_description，以便使用生成式 AI 从自由形式文本描述生成定位建议。
• 添加了 AudienceInsightsService.GenerateTargetingSuggestionMetrics，用于返回指定受众群体定位组合的潜在覆盖面指标。

建议

• 现在，您可以通过在 GenerateRecommendationsRequest.recommendation_types[] 中添加 CAMPAIGN_BUDGET 建议类型，使用 RecommendationService.GenerateRecommendations 在制作广告系列期间生成有关优化预算建议的建议。这适用于效果最大化广告系列和搜索广告系列。

报告

• 将 SearchGoogleAdsRequest 的 summary_row_setting 和 return_total_results_count 字段替换为了 search_settings 字段，该字段的类型为 SearchSettings，其中包含以下字段：
  • omit_results
  • return_summary_row
  • return_total_results_count
• 添加了以下有关常规无效点击的新指标，例如由漫游器或抓取工具生成的点击、具有不规则模式的点击。您可以使用 campaign 报告查询这些数据。
  • metrics.general_invalid_clicks
  • metrics.general_invalid_click_rate
• 向 QuotaError 添加了以下值：
  • EXCESSIVE_SHORT_TERM_QUERY_RESOURCE_CONSUMPTION
  • EXCESSIVE_LONG_TERM_QUERY_RESOURCE_CONSUMPTION

v17.1.0 (2024-08-07)

v17_1 中添加了以下新功能和更新。

素材资源

• 借助 AdGroupAdService.RemoveAutomaticallyCreatedAssets()，您可以移除与自适应搜索广告关联的指定自动制作的素材资源。

受众群体

• 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

广告系列

• ShareablePreviewService.GenerateShareablePreviews() 会为已启用和已暂停的素材资源组生成可共享的广告预览的网址（响应中的 shareable_preview_url）。
  • expiration_date_time 字段表示响应中网址的到期日期。
  • 如果发生错误，该方法将返回 partial_failure_error，而不是网址。

更改历史记录

• 新增了更改状态资源类型：ASSET_GROUP。

转化次数

• SKAdNetwork 版本的新细分字段：segments.sk_ad_network_version
• offline_conversion_upload_conversion_action_summary，用于显示转化操作一级的转化上传诊断信息。
• 系统会在线下诊断报告中添加以下指标，以反映仍在处理的上传转化数据的数量：
  • offline_conversion_upload_client_summary
    • pending_event_count
    • pending_rate
  • offline_conversion_upload_conversion_action_summary：
    • pending_count

规划

• AudienceInsights.GenerateAudienceOverlapInsights()，用于接受输入的主要属性和一系列受众群体属性，并返回主要属性与受众群体属性之间潜在 YouTube 覆盖面重叠情况的估算值。

报告

• 支持基于 segments.date 对 per_store_view 进行细分

视频

• 支持使用报告（例如 ad_group、campaign）检索与以下标准出价策略相关的信息：
  • Campaign.fixed_cpm（固定 CPM [每千次展示费用]）
  • Campaign.target_cpv（目标每次观看费用）
• Campaign.video_campaign_settings，您可以使用以下报告字段确定视频广告可以在哪些广告资源中展示：
  • 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，可让您根据视频广告格式类型细分以下报告：
  • ad_group
  • ad_group_ad
  • ad_group_ad_asset_view
  • campaign
  • customer

v17 (2024-06-05)

v17 中新增了以下功能和变更。

Ads

• 移除了 AdService.getAd。这样一来，AdService 就与 Google Ads API 中的其他服务保持一致。如需了解提取广告和其他资源类型的推荐方法，请参阅检索对象。
• 针对 ImageAdInfo.image_asset 添加了更多有关尺寸和格式的验证。如果图片无效，系统可能会抛出以下错误：
  • ImageError.UNEXPECTED_SIZE
  • ImageError.FORMAT_NOT_ALLOWED

素材资源

• 添加了新枚举：ClickType.AD_IMAGE
• 为效果最大化广告系列和搜索广告系列添加了以下包含新指标的新报告：
  • campaign_aggregate_asset_view
  • channel_aggregate_asset_view

受众群体

• 添加了 OfflineUserDataJobError.OPERATION_LEVEL_CONSENT_PROVIDED

批处理作业

• 添加了 BatchJobError.REQUEST_TOO_LARGE，当提交的 AddBatchJobOperationsRequest 大于 10484504 字节时，系统会抛出此错误。
• 添加了对使用 BatchJobService 时设置 MutateOperation.asset_group_operation 的支持。这样，您就可以使用批量处理功能来制作和管理整个效果最大化广告系列。请参阅我们的专用指南。

广告系列

• 在 Google Ads API 中所有资源（例如广告系列、广告和素材资源）的所有字段、枚举和错误中，将“发现”重命名为“需求开发”。例如，AdvertisingChannelType.DISCOVERY 现在是 AdvertisingChannelType.DEMAND_GEN。
• 添加了 Campaign.keyword_match_type，以便您为广告系列中的所有关键字设置关键字匹配类型。

转化次数

• 对于 SKAdNetwork 转化，
  • 将 segments.sk_ad_network_conversion_value 重命名为 segments.sk_ad_network_fine_conversion_value。
  • 添加了 segments.sk_ad_network_redistributed_fine_conversion_value。
• 现在，系统会在响应中返回以下指标，即使其值为零也是如此。这样，它们就与其他指标保持一致。
  • metrics.all_conversions_value_by_conversion_date
  • metrics.all_conversions_by_conversion_date
  • metrics.conversions_value_by_conversion_date
  • metrics.conversions_by_conversion_date

条件

• 向 AdGroupCriterion 添加了以下字段，以显示广告组条件是否正在投放，或未投放的原因：
  • primary_status
  • primary_status_reasons
• 为 gender_view 添加了对 metrics.search_impression_share 的支持
• 为 keyword_view 添加了对 metrics.phone_calls 的支持

本地生活服务

• 添加了 LocalServicesLeadService.AppendLeadConversation()，用于将新的 LocalServicesLeadConversation 附加到 LocalServicesLead，后者会根据潜在客户的创建方式，通过适当的渠道（例如短信）向用户发送消息。
  • AppendLeadConversationRequest.conversations 的大小上限为 1,000。
  • 在 Conversation.local_services_lead 中，只能指定 LocalServicesLead，且 lead_type 必须设置为 LeadType.MESSAGE。
• 向 ConversationType 添加了新的枚举值：
  • WHATSAPP，表示通过 WhatsApp 引入的对话。
  • ADS_API，表示使用新 LocalServicesLeadService.AppendLeadConversation() 方法引入的对话。
• 向 local_services_verification_artifact 添加了以下新字段：
  • local_services_verification_artifact.insurance_verification_artifact.expiration_date_time
  • local_services_verification_artifact.license_verification_artifact.expiration_date_time

报告

• 现在，在查询 product_link 时，您只能选择与一个 关联的产品相关的字段。选择多个关联商品的多个字段将会抛出 QueryError.PROHIBITED_FIELD_COMBINATION_IN_SELECT_CLAUSE。例如，不能在同一查询中选择 product_link.advertising_partner.customer 和 product_link.data_partner.data_partner_id。
• 将 page_size 传递给 GoogleAdsService.Search 会导致 RequestError.PAGE_SIZE_NOT_SUPPORTED 错误。

购物

• 新增了报告 shopping_product，该报告对应于 Google Ads 界面的产品页面。该函数支持返回与关联到 Google Ads 账号的 Google Merchant Center 账号中商品的当前状态相关的数据。
  • 使用 GoogleAdsService.Search 或 GoogleAdsService.SearchStream 时，您可以使用 segments.date 过滤 shopping_product 报告中的指标。不允许按日期细分，否则将返回 ShoppingProductError.UNSUPPORTED_DATE_SEGMENTATION 错误。

统一目标

• 添加了 UserListCustomerTypeService.MutateUserListCustomerTypes()，用于配置受众群体客户类型。
• 移除了 CustomerLifecycleGoal.lifecycle_goal_customer_definition_settings。如需配置客户生命周期目标的受众群体设置，请改用 UserListCustomerTypeService.MutateUserListCustomerTypes()。
  • 将 UserListCustomerType.customer_type_category 设置为 UserListCustomerTypeCategory.PURCHASERS 可分别将用户名单附加或取消附加到客户生命周期目标的现有客户定义中。如需了解详情，请参阅细分受众群体。

视频

• 向 ContentLabelType 添加了以下值。您可以在客户级别排除以下 ContentLabelTypes：
  • 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
• 添加了 AdVideoAsset.ad_video_asset_info，以便在创建 DemandGenVideoResponsiveAdInfo 时支持视频素材资源的广告资源偏好设置。
• （仅限列入许可名单的账号）使 Campaign.video_brand_safety_suitability 可变。

归档版本说明

如需查看归档的版本说明，请参阅已弃用的版本。