腾讯广告

升级指引

本节将为您介绍如何从V1.0版本升级至V1.1版本。（所有接口指引内容仅供参考，请您在使用时先查阅V1.1的具体接口详情）。

1、advertiser

• 1.1 mp_info 改名为wechat_spec；
• 1.2 get接口的wechat_spec结构中新增字段reject_message，用于同步微信开户审核拒绝原因；
• 1.3 get接口删除icp_number、icp_image_id、icp_image字段（icp信息可从websites结构中获取）；

2、fund

• 2.1 fund_statements_detailed/get支持单次查询的时间跨度最长为2年，返回参数增加分页（page_info）；
• 2.2 fund_statements_daily/get支持单次查询多天数据，date改为date_range（包含start_date、end_date），支持单次查询的时间跨度最长为10天，
• 2.3 fund_type的枚举值命名修改：

3、campaign

• 3.1 开放QQ消息（PROMOTED_OBJECT_TYPE_QQ_MESSAGE）推广目标；
• 3.2 product_type 字段名改为 promoted_object_type，对应枚举值修改如下：

• 3.3 接口中的campaign_id参数下线，filtering参数支持campaign_id的 IN 操作，当过滤条件中的 campaign_id中包含不存在或当前token无权限操作的campaign时，接口不返回；

4、adgroup

• 4.1 time_series 改为必填字段，不允许全部传 0；
• 4.2 end_date对非朋友圈广告（campaign_type！= CAMPAIGN_TYPE_WECHAT_MOMENTS）允许传空，传空表示长期投放；
• 4.3 product_type 字段名改为 promoted_object_type，对应枚举值详见枚举值【推广目标】；
• 4.4 product_refs_id 字段名改为 promoted_object_id；
• 4.5 sub_product_refs_id 字段名改为 app_android_channel_package_id；
• 4.6 对于非朋友圈广告可使用targeting和targeting_id，两者二选一填写；对于朋友圈广告仅可选择targeting；
• 4.7 targeting结构升级
  • 4.7.1 custom_audience、excluded_custom_audience定向支持组合人群，定向人群和排除人群累加总数最多50个；V1.0版本的custom_audience、excluded_custom_audience 在V1.1版本中改为deprecated_custom_audience、deprecated_excluded_custom_audience字段，仅支持读；
  • 4.7.2 新增wechat_official_account_category定向（微信公众号类型定向），当且仅当投放微信公众号广告时可使用；
  • 4.7.3 新增mobile_union_category定向（移动媒体类型定向），当且仅当投放移动联盟广告版位时可使用；
  • 4.7.4 geo_location删除 “单选或同时选择RECENTLY_IN（近期）以及VISITED_IN（去过）”的限制，其余限制保持不变；
  • 4.7.5 定向relationship_status、living_status、paying_user_type、shopping_capability、online_scenario、player_consupt分别改名为marital_status、working_status、consumption_type、consumption_status、network_scene、gamer_consumption_ability；
  • 4.7.6 device_price定向的枚举值修正如下：
    • PRICE_1500_LESS：1500元以下
    • PRICE_1500_2500：1500 ~ 2500元
    • PRICE_2500_3500：2500 ~ 3500元
    • PRICE_3500_4500：3500 ~ 4500元
    • PRICE_4500_MORE：4500以上
  • 4.7.7 开放定向network_scene、air_quality_index；
  • 4.7.8 age、gamer_consumption_ability、temperature定向改为区间定向结构，包含min、max两个字段；
  • 4.7.9 对朋友圈广告，V1.1版本对比V1.0版本将不再支持以下定向：living_status（生活状态）、keyword（关键词定向）、new_device（新设备定向）、dressing_index（穿衣指数）、uv_index（紫外线指数）、makeup_index（化妆指数）、climate（气象）、temperature（温度）、player_consupt（游戏用户消费能力）、residential_community_price（居民社区价格）；
• 4.8 开放scene_spec（场景定向），支持mobile_union定向（联盟场景定向），当且仅当投放移动联盟广告版位时可使用；
• 4.9 oCPA相关功能升级
  • 4.9.1 optimization_goal新增枚举值：

  值	描述
  OPTIMIZATIONGOAL_ONE_DAY_RETENTION	次日留存
  OPTIMIZATIONGOAL_DELIVERY	发货
  OPTIMIZATIONGOAL_TELEPHONE_CONSULTATION	电话咨询
  OPTIMIZATIONGOAL_ONLINE_CONSULTATION	网页咨询

  • 4.9.2 新增枚举值仅能在指定推广目标下使用，对应关系如下所示：

  优化目标	推广目标	BidAmount
  OPTIMIZATIONGOAL_ONE_DAY_ RETENTION （次日留存）	PROMOTED_OBJECT_TYPE_APP_ANDROID PROMOTED_OBJECT_TYPE_APP_IOS PROMOTED_OBJECT_TYPE_APP_ANDROID_UNION	xxx元/次日留存
  OPTIMIZATIONGOAL_DELIVERY （发货）	PROMOTED_OBJECT_TYPE_LINK PROMOTED_OBJECT_TYPE_ECOMMERCE	xxx元/发货
  OPTIMIZATIONGOAL_TELEPHONE _CONSULTATION （电话咨询）	PROMOTED_OBJECT_TYPE_LINK PROMOTED_OBJECT_TYPE_ECOMMERCE	xxx元/电话咨询
  OPTIMIZATIONGOAL_ONLINE_ CONSULTATION （网页咨询）	PROMOTED_OBJECT_TYPE_LINK PROMOTED_OBJECT_TYPE_ECOMMERCE	xxx元/网页咨询

  • 4.9.3 对PROMOTED_OBJECT_TYPE_ECOMMERCE、PROMOTED_OBJECT_TYPE_LINK推广目标，支持无需数据门槛即可投放oCPA广告；
  • 4.9.4 oCPA广告开放CPM扣费，即当billing_event = BILLINGEVENT_IMPRESSION时，optimization_goal支持设置除OPTIMIZATIONGOAL_IMPRESSION外的优化目标；
  • 4.9.5 开放oCPA自动扩量（灰度开放），新增字段expand_enabled、expand_targeting，对非微信流量的oCPA广告支持开启自动扩量（expand_enabled），当开启此功能时，需设置不可突破定向（expand_targeting），系统会在不可突破定向的范围内寻找相似人群，例如您在不可突破定向中设置地理位置定向为上海，系统在自动扩量阶段，将不会把广告展示给非上海地区的用户。如您想把广告展示给所有用户，可以将不可突破定向设置为空。值得注意的是，不可突破定向的某一定向的具体设置需与定向中的设置保持一致，如当且仅当定向中的地理位置定向为上海时，才可将不可突破定向的地理位置定向设置为上海。
• 4.10 开放转化归因功能，新增user_action_sets字段，支持对PROMOTED_OBJECT_TYPE_LINK、PROMOTED_OBJECT_TYPE_ECOMMERCE、PROMOTED_OBJECT_TYPE_APP_ANDROID、PROMOTED_OBJECT_TYPE_APP_IOS推广目标设置数据源id，详情请见【转化归因功能】；；
• 4.11 get接口删除system_status、reject_message字段，不支持按照system_status进行过滤（根据ad模块的system_status判断广告的审核状态）
• 4.12 接口中的adgroup_id参数下线，filtering参数支持adgroup_id的 IN 操作，当过滤条件中的adgroup_id中包含不存在或当前token无权限操作的adgroup时，接口不返回；

5、ad

• 5.1 product_type 字段名改为 promoted_object_type，对应枚举值详见枚举值【推广目标】；
• 5.2 product_refs_id 字段名改为 promoted_object_id；
• 5.3 新增conversion_tracking_enable字段，表示是否开启转化归因，如开启，则会根据adgroup设置的user_action_sets中上传的数据进行转化归因；
• 5.4 接口中的ad_id参数下线，filtering参数支持 ad_id 的 IN 操作，当过滤条件中的 ad_id中包含不存在或当前token无权限操作的ad时，接口不返回。

6、 adcreative

• 6.1 product_type 字段名改为 promoted_object_type，对应枚举值详见枚举值【推广目标】；
• 6.2 product_refs_id 字段名改为 promoted_object_id；
• 6.3 V1.1版本支持创建的创意形式列表如下：

{2,8,9,10,13,19,20,21,22,24,25,27,29,44,53,59,65,66,69,70,71,79,88,89,90,94,96,106,113,115,120,133,134,148,150,155,173,184,185,190,193,194,195,199,202,206,207,208,210,211,212,215,254,261,262,263,276,278,285,310,311,346,347,351,361,366,382,388,394,400,421,423,443,445,449,450,455,456,466,467,468,470,471,473,484,486,487,488,492,493,494,495,496,497,502,506,515,529,533,541,548,551,552,553,554,555,563,564,565,567,585,586,588,592,600,601,608,610,611,612}

• 6.4 V1.1版本支持写入的创意形式元素如下：

{animation_effect, phone,mini_program_id, image, title, description, video, url, image2, corporate, corporate_name, corporate_img, element_story, button_text, bottom_text, countdown, image3, mini_program_path, image_list, link_name_type, left_bottom_txt, label, logo, logo_description}

• 6.5 新增字段page_type、page_spec，其中page_type为必填字段，投放时，需指定落地页类型，目前支持自定义落地页以及落地页工具创建的落地页，不同page_type所填写的信息不同，且page_type的选择与推广目标有关，对应关系如下：

• 6.6 支持朋友圈广告同时使用简易原生页和小程序落地页；
• 6.7 开放朋友圈视频广告投放（创意形式id：452、589、618）；
• 6.8 接口中的adcreative_id参数下线，filtering参数支持adcreative_id的 IN 操作，当过滤条件中的adcreative_id中包含不存在或当前token无权限操作的adcreative时，接口不返回。

7、promoted_object（原product）

• 7.1 products/add、products/update、products/get 接口改名为 promoted_objects/add、promoted_objects/update、promoted_objects/get；
• 7.2 字段名修改如下：

• 7.3 promoted_object_type对应枚举值详见枚举值【推广目标】；
• 7.4 promoted_objects/add、promoted_objects/update接口删除product_name 字段，系统默认拉取应用名称作为商品名称；
• 7.5 promoted_objects/get接口支持拉取推广目标列表，删除一级结构中的promoted_object_type、promoted_object_id字段，开放filtering结构以及分页功能（page、page_size），支持根据多个promoted_object_type、promoted_object_id进行过滤；
• 7.6 promoted_objects/get接口的返回字段改为list、page_spec结构，channel_package_spec移到app_android_spec、app_android_myapp_spec 结构中；

8、targeting

• 8.1 targetings/add接口创建的定向包可被多条广告复用，adgroups/add创建的定向不可被其他广告复用；
• 8.2 targetings/get接口仅返回targetings/add接口创建的定向；
• 8.3 targeting结构升级
  • 8.3.1 custom_audience、excluded_custom_audience定向支持组合人群，定向人群和排除人群累加总数最多50个；V1.0版本的custom_audience、excluded_custom_audience在V1.1版本中改为deprecated_custom_audience、deprecated_excluded_custom_audience字段，仅支持读；
  • 8.3.2 geo_location删除 “单选或同时选择RECENTLY_IN（近期）以及VISITED_IN（去过）”的限制，其余限制保持不变；
  • 8.3.3 定向relationship_status、living_status、paying_user_type、shopping_capability、online_scenario、player_consupt分别改名为marital_status、working_status、consumption_type、consumption_status、network_scene、gamer_consumption_ability；
  • 8.3.4 device_price定向的枚举值修正如下：
    • PRICE_1500_LESS：1500元以下
    • PRICE_1500_2500：1500 ~ 2500元
    • PRICE_2500_3500：2500 ~ 3500元
    • PRICE_3500_4500：3500 ~ 4500元
    • PRICE_4500_MORE：4500以上
  • 8.3.5 开放定向network_scene、air_quality_index；
  • 8.3.6 age、gamer_consumption_ability、temperature定向改为区间定向结构，包含min、max两个字段；
• 8.4 接口中的targeting_id参数下线，filtering参数支持targeting_id 的 IN 操作，当过滤条件中的targeting_id中包含不存在或当前token无权限操作的targeting时，接口不返回。

9、estimation/get

• 9.1 time_series 改为必填字段，不允许全部传 0；
• 9.2 product_type 字段名改为 promoted_object_type，对应枚举值详见枚举值【推广目标】；
• 9.3 product_refs_id 字段名改为 promoted_object_id
• 9.4 targeting结构升级
  • 9.4.1 custom_audience、excluded_custom_audience定向支持组合人群，定向人群和排除人群累加总数最多50个；V1.0版本的custom_audience、excluded_custom_audience在V1.1版本中改为deprecated_custom_audience、deprecated_excluded_custom_audience字段，仅支持读；
  • 9.4.2 geo_location删除 “单选或同时选择RECENTLY_IN（近期）以及VISITED_IN（去过）”的限制，其余限制保持不变；
  • 9.4.3 定向relationship_status、living_status、paying_user_type、shopping_capability、online_scenario、player_consupt分别改名为marital_status、working_status、consumption_type、consumption_status、network_scene、gamer_consumption_ability；
  • 9.4.4 device_price定向的枚举值修正如下：
    • PRICE_1500_LESS：1500元以下
    • PRICE_1500_2500：1500 ~ 2500元
    • PRICE_2500_3500：2500 ~ 3500元
    • PRICE_3500_4500：3500 ~ 4500元
    • PRICE_4500_MORE：4500以上
  • 9.4.5 开放定向network_scene、air_quality_index；
  • 9.4.6 age、gamer_consumption_ability、temperature定向改为区间定向结构，包含min、max两个字段；

10、adcreative_templates

• 10.1  adcreative_template_info/get 接口改名为 adcreative_templates/get；
• 10.2 product_type 字段名改为 promoted_object_type，对应枚举值详见枚举值【推广目标】；
• 10.3 返回list结构中新增adcreative_template_name、adcreative_template_description、adcreative_template_size、adcreative_template_style、support_billing_spec_list（billing_event、max_price、min_price）字段，其中support_billing_spec_list为创意形式支持的出价信息；
• 10.4 返回list结构中新增adcreative_attributes、ad_attributes字段，分别表示广告创意属性、广告属性，其中广告属性信息表示与广告版位+推广目标有关，但不通过adcreative_elements进行同步，而通过ad接口进行同步的信息，包括impression_tracking_url、click_tracking_url、feeds_interaction_enabled；广告创意属性表示与创意形式+推广目标+广告版位有关，但不通过adcreative_elements进行同步，而通过adcreative接口中和adcreative_elements平级的字段进行同步的信息，包括以下字段：deep_link_url、deep_link_type、share_content_spec；
• 10.5 删除list结构中的privilege_enable字段，当请求参数中有account_id时，输出该广告主可投放的信息，即对于无权限的创意形式、元素或属性信息不进行返回；

11、targeting_tags

• 11.1 type的枚举值LOCATION改名为BUSINESS_DISTRICT，删除DISTRICT，新增WECHAT_OFFICIAL_ACCOUNT_CATEGORY、MOBILE_UNION_CATEGORY，用于获取微信公众号类型定向标签、移动联盟类型定向标签
• 11.2 当type = REGION时，返回结果包含国家省市区县的所有region_id；
• 11.3 请求参数删除region_id，当type =  BUSINESS_DISTRICT 时，返回所有商圈信息；
• 11.4 city_level的枚举值修改如下：

12、images

• 12.1 新增upload_type字段，开放UPLOAD_TYPE_FILE, UPLOAD_TYPE_BYTES枚举值，其中UPLOAD_TYPE_FILE为图片文件上传, UPLOAD_TYPE_BYTES为图片内容上传；
• 12.3 新增字段bytes，当type = UPLOAD_TYPE_BYTES时必填；
• 12.4 原字段file改为选填，当type = UPLOAD_TYPE_FILE时必填；
• 12.5 接口中的image_id参数下线，filtering参数支持image_id的 IN 操作，当过滤条件中的 image_id中包含不存在或当前token无权限操作的image时，接口不返回。

13、videos

• 13.1 接口中的video_id参数下线，filtering参数支持video_id的 IN 操作，当过滤条件中的 video_id中包含不存在或当前token无权限操作的video时，接口不返回；
• 13.2返回结构改为list+page_info结构，多个video对象置于list数组结构中。

14、dynamic_ad_images

• 14.1 接口中的image_id参数下线，filtering参数支持image_id 的 IN 操作，当过滤条件中的 image_id中包含不存在或当前token无权限操作的image时，接口不返回。

15、insights（包含tracking_reports/get、daily_reports/get、hourly_reports/get）

• 15.1 product_type 字段名改为 promoted_object_type，对应枚举值详见枚举值【推广目标】；
• 15.2 product_refs_id 字段名改为 promoted_object_id；

16、ecommerce_order

• 16.1 date改为date_range，支持跨日期进行查询；
• 16.2 更新接口返回字段新增ecommerce_order_id；

17、qualifications

• 17.1 qualifications/add、qualifications/delete接口的返回字段新增qualification_id；

18、pages

• 18.1 新增pages/get接口，用于拉取落地页工具制作的落地页；

19、async_tasks

• 19.1 新增async_tasks/add 、async_tasks/get接口，支持获取广告小时离线报表，该功能为灰度开放；

20、adcreative_previews

• 20.1 新增adcreative_previews/add、adcreative_previews/get，开放朋友圈广告的在线预览功能；

21、其他

• 21.1 get接口增加fields字段，用于指定返回的字段列表，为选填字段，如不填写，则根据默认值进行返回

• 21.2 非广告投放及管理模块相关接口部分字段名有所变更