广告创意相关API

注意:

  1. 由于系统之间的同步机制,通过AdX界面查询到的广告创意审核状态,与API查询结果可能不同。必须API同步到审核通过的素材,才可用于投放。
    创意素材(包括但不限于视频素材)大小限制150M,ADX拉取素材(dsp提供的file_url)时间限制在90秒,超过90秒未拉取完整素材会提示601错误, dsp需要保证素材url所在的CDN服务器的出口带宽,建议出口带宽最低限速在3MB/s以上。
  2. 接口开发时,可登录ADX平台,在“运营工具”页面使用“API测试工具”自助联调;联调后,可直接在ADX的线上环境做提交创意测试,但必须使用广告主“合约广告测试专用_品牌(9699840)”,且确保测试用的非正式创意,不会用于线上流量投放。(广告主需要同步到DSP账号后才能使用)

DSP通过该系列API进行广告创意的相关工作,包括新建、修改、查询、获取创意数量、更新有效期、创意下线。

PDB/PD接口说明:

  1. 在广告主下上传广告创意,审核通过的素材才能用来实时回复流量请求,否则系统将报错。
  2. 由于腾讯广告平台对于每个广告主下的创意总量有限制,因此ADX平台也需限制DSP提交的创意上限。详见:【通知】腾讯PDB/PD广告创意使用规范变更https://docs.qq.com/doc/DVXJwQnZySlZIbkh2?u=22225ec704d64c8f946fc3a3b76ff198


RTB:若广告主未审核通过,则无法上传广告创意。

 

1.创建

接口:adcreative/add
请求字段:

名称类型描述
data数组类型最多10个

data内容详细:

名称类型必填描述
dsp_order_idstringY广告创意素材id,dsp需保证该id在dsp测的唯一性
advertiser_idintY广告主id 和 name 二选一,都传的话优先使用id
advertiser_namestringY同上
display_idintY广告形式id
end_datestringN有效期,最长可设90天,示例:2022-05-19
(建议按实际投放需要填写,在线时间过长将持续占用创意额度;如不填写,默认设为90天)
targeting_urlstringY落地页,支持302
no_clickstringN(仅支持白名单客户填充)
禁止点击:当前仅支持no_click=Y,不传该字段表示默认可点击;
当值为Y时,点击监测链接和落地页链接均需要为空
ldp_demo_urlstringN落地页截图,仅针对优投客户(落地页在推广日期之前不能打开的情况)
is_only_pdintN是否只投放PD (默认为0:否,1:是,即只能投放PD)
monitor_url数组类型N曝光监测地址,最多5个
monitor_position数组类型N在设置了monitor_url的情况下配合使用。仅针对视频贴片素材,监测请求位置
(该字段的填充值仅支持0,如需要自定义其他上报时机,请联系销售走白名单申请流程)
monitor_settle_bill数组类型N在设置了monitor_url的情况下配合使用。(仅支持PDB)
visible_monitor_url 数组类型 N 可见曝光监测地址(仅支持新闻app信息流)
click_monitor_url数组类型N点击监测地址,最多3个
video_monitor_by
_time_url
数组类型 N 仅针对 信息流视频监测地址 video_monitor_by
_time_url ,对象数组
(仅PDB、PD支持使用,RTB不支持)
ad_content数组类型Y创意素材内容,包括视频、图片、文本等。需严格按照广告形式的定义顺序来指定上传
ad_ext对象类型N高级扩展参数。详见下面请求示例
ad_ext2对象类型N高级扩展参数2。详见下面请求示例
mini_program_id string N小程序id  长度(字节):最小1,最大512   可以为空
mini_program_pathstring N 小程序路径  长度(字节):最小1,最大2048   可以为空

video_monitor_by_time_url内容详细:

名称类型必填描述
url stringY 监测链接,最多5个
timeintY 上报时间点(秒)

ad_content内容详细:

名称类型必填描述
file_text stringYfile_text,file_url 必须指定其中一个,按照广告形式id的定义校验,文件大小,类型,尺寸
file_urlstringY同上
file_md5stringN仅针对视频文件,如果指定了md5值,其它两项就不再需要传了。

说明:
file_md5 字段仅针对视频文件,如果传入了该参数,则先查找该md5值的素材以前是否传入过adx系统,如果已经传入过则直接使用该文件,不在拉取素材,节省了网络传输流量和时间。

ad_ext内容详细:

名称类型必填描述
app_info对象类型Napp下载唤起特性
universal_linkstringN仅支持XQ系流量;广告点击后,优先触发ulink,其次是deeplink,最后触发“推广目标”(即product_type中设置的目标)
share_info 对象类型 N 分享特性

app_info内容详细:

名称类型必填描述
product_type intY 枚举说明: 1-普通链接(仅支持1) 2-android应用下载 3-ios应用下载(将废弃)
app_idintN下载类的app id,若product_type=2,3为安卓或iOS则必填(将废弃)
deep_linkstring N应用直达URL(deep_link包名必须与下单时设置的一致)


应用直达及跳转小程序说明:

  1. 应用直达:通过deeplink、ulink字段唤起app,使用该字段时,①必须确认媒体下单时已设置了允许使用使用直达;② 素材上也需要填写该字段;③ deeplink链接对应的包名,必须与下单时填写的一致。
  2. 跳转小程序:通过mini_program_id、mini_program_path字段唤起微信小程序,使用该字段时,① 必须确认媒体下单时已设置了允许使用小程序;② 素材上填写的小程序id,必须与下单时保持一致。

share_info内容详细:

名称 类型 必填 描述
description string Y 分享文案,4-28汉字
image stringY 分享配图, 图片的URL,尺寸114*114, jpg 格式

ad_ext2内容详细:

名称类型必填描述
feed_card数组类型N信息流轮卡片播放形式专用
注:信息流轮播卡片支持3-6组素材,且素材组数(ad_content)必须要与链接组数(ad_ext2.feed_card保持严格一致)。如当前创意有6组素材,则feed_card数组长度为6,且对应ad_content数组也必须为6组(例如display_id=200123,填6组素材时,则ad_content传15个元素值:广告主头像+广告主名称+横板大图文案+6组卡片素材(每组1个大图1个标题)= 15个素材元素;填3组素材时,则ad_content传9个元素值:广告主头像+广告主名称+横板大图文案+3组卡片素材(每组1个大图1个标题)= 9个素材元素;

feed_card内容详细:

名称类型必填描述
targeting_urlstringN轮播卡片targeting_url(H5落地页链接)
mini_program_pathstringN轮播卡片mini_program_path(小程序页面链接)
deep_linkstringN轮播卡片deeplink(应用直达链接)
universal_linkstringN轮播卡片universal_link(Ulink通用链接)
注:以上四个字段值不能同时为空

接口返回:

名称类型描述
ret_codeint返回码
ret_msg数组类型返回内容
error_codeint错误补充码

ret_msg内容详细:

名称类型描述
dsp_order_idstringdsp唯一订单号
err_codeint需要时返回,成功时不返回,失败返回具体错误码。
err_msgstring需要时返回,成功时不返回,错误具体描述

请求示例:

    {
            "data":[
                {
                    "dsp_order_id":"6001",
                    "advertiser_id":100,
                    "display_id":10389,
                    "targeting_url":"http://xinwen.qq.com/adtargetpage?a=1",
                    "is_only_pd":1,
                    "monitor_url":[
                        "http://monitor.qq.com/monitor1",
                        "http://monitor.qq.com/monitor2"
                    ],
                    "monitor_position":[
                        2,
                        5
                    ],
                    "monitor_settle_bill":[
                        1,
                        0
                    ],
                    "click_monitor_url":[
                        "http://click.qq.com/click1"
                    ],
                    "video_monitor_by_time_url":[
                     {        
                       "url":"http://tytx.m.cn.miaozhen.com/r/",
                       "time":"0"
                      },
                     {
                       "url":"http://t.cr-nielsen.com/dar?_t=r",
                       "time":"0"
                      }],
                    "ad_content":[
                        {
                            "file_text":"广告标题 t"
                        },
                        {
                            "file_url":"http://cdn.qq.com/pic640x246.jpg"
                        },
                        {
                            "file_url":"http://cdn.qq.com/pic114x114.jpg"
                        },
                        {
                            "file_text":"摘要 c"
                        },
                        {
                            "file_text":"广告主名称 a"
                        }
                    ],
                    "ad_ext":{
                        "app_info":{
                            "product_type": 3,
                            "app_id": 989673964
                        }
                    },
                 "mini_program_id": "gh_abcdef",
                 "mini_program_path": "abcdef"
                }
            ]
        }

注:
ad_ext 高级扩展参数目前仅支持app_info,如需使用请注意参数key值,evokeapp已废弃不再使用。
SDK客户端会对deeplink地址进行有效性校验,无效的话会自动转成非唤起的广告形式,打开落地页。

PDB/PD模式新增参数 is_only_pd,说明:是否只投放PD (默认为0:否,1:是,即只能投放PD)。
PDB模式新增参数 monitor_settle_bill 对应 monitor_url 参数设置指定哪条曝光监测地址是用于第三方结算的,用于结算的会进行monitor_url的强校验。
对于PDB必须指定一条用于结算的第三方监测url。
例如: monitor_url 指定了2条 [“http://a.com”,”http://b.com“], 如果要设置a.com是用于结算第三方监测url, 那么 monitor_settle_bill 应设置为 [1,0]

返回示例(成功):

    {
        "ret_code":0,
        "ret_msg":[
            {
                "dsp_order_id":"6001",
            }
        ]
    }

返回示例(失败):

    {
        "ret_code":1,
        "ret_msg":[
            {
                "dsp_order_id":"6001",
                "err_code":1107,
                "err_msg":"either file_url/file_text was needed."
            }
        ]
    }