多点广告对接文档
一、试玩流程
- 用户领取的任务的时候多点广告调用广告主提供的查询接口来判断该用户之前是否下过该app
- 用户领取任务后,多点广告将调用广告主提供的点击接口告知用户idfa及其他信息
- 用户自行去App Store搜索下载并且联网打开
- 当广告主监测玩家已经打开app后,调用多点广告回调接口告多点广告用户已经打开app(非必须)
- 用户试玩达到时长完成任务后,多点广告调用广告主提供的激活上报接口告知用户完成状态
二、接口说明
接口名称 | 接口说明 | 提供者 |
---|---|---|
查询/排重接口 | 查询某个玩家的IDFA是否下载过广告主的应用 | 广告主提供 |
点击接口 | 玩家领取任务后,发送玩家IDFA等信息到广告主 | 广告主提供 |
激活上报接口 | 用户完成任务后,发送玩家IDFA等信息到广告主 | 广告主提供 |
回调接口 | 当广告主监测到用户打开app后回调多点广告的回调接口 | 多点广告提供 |
三、对接流程
- 广告主开发查询接口、点击接口、激活上报接口。
- 在自助对接页面配置后,模拟测试流程走通后提交即可。
注意事项
- 查询/排重接口多点广告每次只提交一个idfa,例如返回1表示安装过,返回0表示未安装过可以领任务,注意同一个idfa重复请求查询接口时,只要未激活一直返回0,激活后就返回1。
- 点击通知接口和激活上报接口,广告主收到信息即可,激活上报接口有失败重试,可能会多次调用,请广告主注意幂等。
- 三个接口的超时时间均为1.5秒,并发量每秒不低于300+次为宜。
- 回调接口,广告主尽量能在用户激活后及时回调多点广告通知我们用户试玩成功。仅作为统计数据,不以广告主回调数据为结算依据。
四、例子
查询/排重、点击、激活上报接口:如下图
- http请求方法:支持GET POST 两种任选一种。
- url地址:支持restful风格,不过参数需要手动填写,变量可以在多点广告内置变量中选取。
- Content-Type:目前暂时支持两种,application/x-www-form-urlencoded application/json
- Header请求头:value值支持自定义和内置变量,内置变量格式与参数值一致,参见后面的表格
- 参数:参数名、参数值一一对应,参数名称可以根据自己需求调整,参数值目前分为自定义、多点广告内置变量两种,自定义顾名思义就是自己填写的固定值,多点广告内置变量是与广告投放相关的变量,在实际执行接口时,多点广告会统一替换内置变量为实际参数值。参数第二个输入框为默认值,如果内置变量为空,就会将内置变量替换为填写的默认值(适用于不传参数就报错的接口)。参见后面的表格。
解析类型目前支持以下三种格式
标准格式 返回值为多点广告统一格式即:{“6FD79122-8308-4804-A497-5D7BFE7FB554”:1} 或{“6FD79122-8308-4804-A497-5D7BFE7FB554”:0}
查询/排重接口返回1表示该idfa已经存在,返回0表示该idfa不存在,用户可以领取任务。
点击接口返回1表示请求成功,返回0表示请求失败
httpCode
查询/排重接口 httpcode返回200 表示该idfa已经存在,返回非200表示该idfa不存在,用户可以领取任务。
点击接口httpcode返回200表示请求成功,返回非200表示请求失败
json
目前json格式解析支持多层解析,例如返回格式为如下格式,这种是需要解析的结果中含有变量,稍微复杂一些,需要解析data层级内idfa对应的value 为1的情况
>{ "data": { "83F06F55-00F8-4B70-A25C-CF27A6323DCE": "0" }, "rtn_code": "0", "rtn_msg": "success" }
配置如下图
当例如返回格式为如下格式,一层解析,并且不含有变量,比较简单,仅解析rtn_msg 为success的时候
>{ "rtn_code": "0", "rtn_msg": "success" }
配置如下图
查询/排重接口有两种解析版本,默认v1.0:
第一种是v1.0,需要配置已下载(不能做任务)的返回,当匹配到解析返回值的情况下认为idfa已经存在,当无法匹配的时候认为idfa不存在,用户可以领取任务。适用于只有一种不能领取任务的返回。
第二种是v2.0,与第一种相反,需要配置未下载(允许做任务)的返回,当匹配到解析返回值的情况下认为idfa不存在(可以领取任务),当无法匹配的时候认为idfa存在(不能领取任务)。适用于只有一种可以领取任务的返回。点击接口和激活上报接口匹配到解析返回值认为请求成功,当无法匹配的时候认为请求失败。激活上报接口请求失败后会重试。
多点广告内置变量表 | 对应参数值描述、示例 |
---|---|
${appid} | 1197828327 |
${mac1} | MAC格式一(2C:20:0B:37:D3:1F) |
${mac2} | MAC格式二(2c:20:0b:37:d3:1f) |
${mac3} | MAC格式三(2c200b37d31f) |
${idfa1} | IDFA格式一(D8C262D6-5B18-4289-BB28-CFE6DE1EDAAD) |
${idfa2} | IDFA格式二(D8C262D65B184289BB28CFE6DE1EDAAD) |
${idfa3} | IDFA格式三(d8c262d65b184289bb28cfe6de1edaad) |
${ip} | ip地址(192.168.1.1) |
${os} | ios版本(9.3) |
${timestamp} | 时间戳(自1970年以来的毫秒数) |
${callback1} | 回调接口格式一(UrlEncode) |
${callback2} | 回调接口格式二(无需UrlEncode) |
- 回调接口:回调接口现在由多点广告在点击接口配置时传入callback参数,地址由多点广告拼接完成,广告主无需自己拼接,当用户完成激活后,保证回调正常到达多点广告即可。