版本说明

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 为类别设置目标每次转化费用。

效果最大化广告系列

• 品牌推广指南支持 <ph type="x-smartling-placeholder">
  </ph>
  • 添加了 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 资源。
  • 启用品牌推广指南后，必须至少将一项“field_type”设置为 BUSINESS_NAME 的素材资源以及至少一项具有“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
• 针对效果最大化广告系列和搜索广告系列，添加了以下包含新指标的新报告： <ph type="x-smartling-placeholder">
  </ph>
  • campaign_aggregate_asset_view
  • channel_aggregate_asset_view

受众群体

• 添加了OfflineUserDataJobError.OPERATION_LEVEL_CONSENT_PROVIDED

批处理作业

• 已添加 BatchJobError.REQUEST_TOO_LARGE, 当提交的 AddBatchJobOperationsRequest 大于 10484504 字节时，将抛出该异常。
• 添加了对设置 MutateOperation.asset_group_operation 的支持 使用 BatchJobService 时。这样，您就可以使用批量处理功能来制作和管理整个效果最大化广告系列。不妨参阅我们新推出的专属指南。

广告系列

• 在所有字段、枚举和所有错误中将发现广告系列重命名为需求开发广告系列 整个 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 的支持
• 添加了对 metrics.phone_calls 的支持 关于“keyword_view”

本地生活服务

• 添加了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 Merchant Center 中与商品的当前状态相关的数据 与 Google Ads 账号相关联的账号。
  • 使用 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 可变。

v16.1.0 (2024-04-24)

v16.1 中新增了以下功能和变更。

账号管理

• CustomerNegativeCriterion.ip_block，支持在客户一级将 IP 地址添加为否定条件。
• 新的枚举值： ProductLinkError.LINK_EXISTS。
• 新的枚举值： ProductLinkInvitationError.CUSTOMER_NOT_PERMITTED_TO_CREATE_INVITATION。

素材资源

• 支持与需求开发相关的素材资源， ad_group_ad_asset_view和 asset_field_type_view。
• 新枚举值：AssetFieldType.DISCOVERY_CAROUSEL_CARD。

受众群体

• 新增枚举值：ResourceLimitType.LOOKALIKE_USER_LISTS_PER_CUSTOMER，该值将客户可以拥有的相似用户列表数量限制为 1,000 个。

广告系列

• 支持返回 Target 广告支出回报率广告系列出价模拟结果： 应用广告系列 campaign_simulation 报告。
• 新枚举值：CampaignError.DYNAMIC_TEXT_ASSET_CANNOT_OPT_OUT_WITH_FINAL_URL_EXPANSION_OPT_IN。
• 新的枚举值： AdGroupPrimaryStatusReason.AD_GROUP_PAUSED_DUE_TO_LOW_ACTIVITY。
• 新的枚举值： CampaignCriterionError.CANNOT_REMOVE_ALL_LOCATIONS_DUE_TO_TOO_MANY_COUNTRY_EXCLUSIONS。

转化次数

• SkAdNetworkConversionValueSchema.postback_mappings 它支持 SKAdNetwork 4.0 功能。
• 添加了对 CustomerSkAdNetworkConversionValueSchemaService 作为 MutateCustomerSkAdNetworkConversionValueSchemaRequest.enable_warnings 的警告的支持。设置为 true 时，与操作失败相关的任何非阻塞错误 将作为 MutateCustomerSkAdNetworkConversionValueSchemaResponse.warning。
• CustomerSkAdNetworkConversionValueSchemaError 中的新枚举值：
  • INVALID_EVENT_COUNTER
  • INVALID_EVENT_NAME

条件

• BrandInfo 中的新字段：
  • display_name
  • primary_url
  • rejection_reason
  • status
• 新枚举： BrandRequestRejectionReason。
• 新枚举值：CriterionType.LIFE_EVENT。

实验

• 新的枚举值：ExperimentError.INVALID_DURATION_FOR_AN_EXPERIMENT。

本地生活服务

• local_services_lead.credit_details.credit_state 和 local_services_lead.credit_details.credit_state_last_update_date_time，分别用于返回抵用金状态和抵用金状态更新时的时间戳。
• local_services_lead_conversation.message_details.attachment_urls，用于返回可用于下载附件内容的网址。

视频

• customer.video_brand_safety_suitability 和 BrandSafetySuitability，它们支持在客户一级检索视频品牌保障适宜性。
• 新的枚举值：VideoCampaignError.MUTATE_REQUIRES_RESERVATION。

v16 (2024-02-21)

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

账号管理

• advertising_partner 从 AccountLink更改为 ProductLink和 ProductLinkInvitation。
• 已将data_partner和google_ads从以下群组中移除： AccountLink。
• 添加了 IdentityVerificationService，用于管理广告客户验证。
  • StartIdentityVerification() 用于启动验证会话，方法为使用提供的 verification_program。 它会创建新的验证会话，并针对成功创建的验证返回空响应。
    • 添加了 IdentityVerificationProgram.ADVERTISER_IDENTITY_VERIFICATION。
  • GetIdentityVerification() 可用于检索验证信息，该信息会返回多个 IdentityVerification 对象。每个 IdentityVerification 都包含：
    • verification_program 也就是身份验证程序类型
    • identity_verification_requirement 其中包含与提交 广告主应完成验证
    • verification_progress ，其中包含与验证会话相关的详细信息，包括：
      • program_status 表示 验证会话
      • action_url 会将客户定向到一个网址以完成 验证。
      • invitation_link_expiration_time 表示 action_url 的失效日期
  • 枚举： <ph type="x-smartling-placeholder">
    </ph>
    • IdentityVerificationProgram
    • IdentityVerificationProgramStatus
  • 错误：
    • IdentityVerificationError
• 已添加 AuthorizationError.ACTION_NOT_PERMITTED_FOR_SUSPENDED_ACCOUNT。

素材资源

• asset_group 的变更：
  • 添加了对时间相关细分的支持，例如 segments.year和 segments.month。
  • 将 campaign 设为了归因资源，而非归因资源 对资源进行细分

广告系列

• 对需求开发广告系列的更改：
  • 新增了对为现有需求开发广告系列设置 Campaign.shopping_setting 的支持。
  • 已添加 ShoppingSetting.disable_product_feed 以停用需求开发广告系列的可选商品 Feed。
  • 添加了Ad.demand_gen_product_ad 和相应的 DemandGenProductAdInfo，提供给 采用非 null 值的需求开发广告系列 Campaign.shopping_setting。
• 已向 AdGroup 的以下字段添加，以显示是否 广告组正在投放或未投放的原因：
  • primary_status
  • primary_status_reasons
• 向 AdGroupAd 添加了以下字段，以显示广告组广告是否正在投放或未投放的原因：
  • primary_status
  • primary_status_reasons
• 将以下值添加到 AdGroupError:
  • CANNOT_ADD_AD_GROUP_FOR_CAMPAIGN_TYPE
  • INVALID_STATUS

实验

• 已将Experiment.sync_enabled添加到 指定是否应在实验中启用同步功能。启用同步后，在实验运行期间对原始广告系列所做的更改会自动复制到实验广告系列中。
• 添加了 ExperimentError.CANNOT_ENABLE_SYNC_FOR_UNSUPPORTED_EXPERIMENT_TYPE。
• 添加了 CampaignError.CANNOT_MODIFY_TEXT_ASSET_AUTOMATION_WITH_ENABLED_TRIAL。

酒店和旅行

• 为推荐活动广告的 ListingDimensionInfo 添加了以下字段，以便根据旅行活动的适用州和城市创建商家信息群组：
  • activity_state
  • activity_city
• 新增了对以下细分的支持 travel_activity_performance_view:
  • segments.activity_city
  • segments.activity_country
  • segments.activity_state

本地生活服务

• 已添加 LocalServicesVerificationArtifact.business_registration_check_verification_artifact 和 BusinessRegistrationCheckArtifact 供广告客户监控工商登记的进展情况 验证流程。
• 添加了一项新资源 local_services_employee即可允许 来检索他们添加的员工信息。

规划

• 已将score从以下位置移除： AudienceInsightsAttributeMetadata。

建议

• 已添加 RecommendationService.GenerateRecommendations() 该函数会根据指定的设置返回推荐内容，例如 以及广告渠道类型这在广告系列制作过程中特别有用。
• 添加了 RecommendationMetrics.conversions_value。
• 现在，对于未设置关键字匹配类型的推荐关键字， recommended_match_type 已设置为 UNSPECIFIED，而不是 UNKNOWN。
• 添加了以下类型的建议：
  • MAXIMIZE_CONVERSION_VALUE_OPT_IN，建议您选择启用“尽可能提高转化价值”出价策略
  • IMPROVE_GOOGLE_TAG_COVERAGE，建议在更多网页上部署 Google 代码
  • PERFORMANCE_MAX_FINAL_URL_OPT_IN，建议您为效果最大化广告系列启用最终到达网址扩展功能
  • REFRESH_CUSTOMER_MATCH_LIST 建议您更新在 过去 90 天
  • CUSTOM_AUDIENCE_OPT_IN 建议你创建自定义受众群体
  • LEAD_FORM_ASSET 建议为广告系列或客户添加潜在客户表单素材资源 级别
  • IMPROVE_DEMAND_GEN_AD_STRENGTH 建议提高需求开发广告系列的广告效力

购物

• 添加了 CampaignError.CANNOT_LINK_TO_COMPARISON_SHOPPING_SERVICE_ACCOUNT 和 CampaignError.CANNOT_TARGET_NETWORK_FOR_COMPARISON_SHOPPING_SERVICE_LINKED_ACCOUNTS，以便为与 Comparison Shopping Service Center 账号关联的购物广告系列提供更详细的错误信息。
• 将以下值添加到 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

生命周期目标

• 向 CustomerLifecycleGoalOperation 和 CampaignLifecycleGoalOperation 添加了 update，以使这些操作类型与 API 中的其他操作类型保持一致。## 归档的版本说明

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