移动任务集市接入技术文档

目录

1. 移动任务集市接入流程

移动任务集市是一种分步式CPA模式广告形式。
“任务”为开发者自行设定的、期望用户达到的推广目标,仅对未安装该APP的用户曝光,用户完成任务后可获得奖励。 任务分为三个步骤,每个步骤完成后用户均可获得奖励,步骤内容和奖励内容均由开发者自行设定。 其中,步骤1内容由系统默认为“ 从本页面下载并安装该APP”。


1.1 接入流程

(1) 产品需先接入腾讯应用宝平台(在Open.qq.com注册移动app)。
(2) 产品的开发、运营人员需仔细阅读本文档,确认接入可行性和接入人力资源。经验数据:接入联调需 2-3天/人。
(3) 推广的渠道包需接入MSDK以及MTA
MSDK简介及接入流程:http://wiki.mg.open.qq.com/index.php?title=MSDK%E6%8E%A5%E5%85%A5%E6%B5%81%E7%A8%8B
MTA简介及接入流程:http://mta.qq.com/
(4) 运营人员设计任务内容和奖励内容,但三个任务奖励至少要有1个是Q币或流量奖励
(5) 渠道包需开发、部署并联调通过“移动任务集市广告主回调接口”。
应用通过本接口和系统进行交互。应用需判断用户是否完成任务步骤,并按照系统通知给完成步骤的用户发放奖励。 协议内容详见本文档;
(6) 进入 http://e.qq.com/task/index 配置任务并进行投放。


1.2 注意事项

(1)移动任务集市推广的是 渠道包,投放移动任务集市,需在Open.qq.com 上传 满足本文档要求的渠道包。
(2)请遵守《任务集市服务使用协议》,如实返回用户真实任务进度。
(3)需严格遵守本文档约定返回码规范。违约将导致用户无法领奖。
(4)可咨询企业QQ 800013811 获取技术支持。

2. 移动任务集市广告主回调接口协议

2.1 接口说明

本接口由广告主实现,开发者在 任务投放端 创建移动推广任务界面填写本接口地址,由平台回调。
当用户领取任务后去应用做任务,完成任务后在平台点击“领取奖励”按钮时,平台将回调该接口向开发者应用发出“任务步骤是否完成,完成就发货”请求,应用收到请求后,查询该用户是否完成某步骤,若完成,则给用户发货,发货成功后返回给平台“发货成功”。

本操作属于整体流程中的第4步:
mobilerenwujishijieruliucheng-01.png


2.2 协议参数

参数名称 类型 描述
cmd string 命令字。平台根据任务步骤的奖励配置和步骤完成判断逻辑,返回不同的命令字,开发者做相应操作。

如下是本字段返回值和说明:
check:开发者仅需要查询任务步骤是否完成,返回步骤完成状态。
check_award: 开发者需要查询任务步骤是否完成,若步骤已完成,直接给用户发货(payitem),并返回发货是否成功。
award:平台通知开发者直接给给用户发货,开发者返回发货是否成功。

openid string 注意!!!本字段值为MID,为手机的唯一机器标识id,客户端集成MTA SDK 即可获取 MID。MID为0-9 a-f 共40位的字符串。
appid uint32 应用在移动开放平台上接入获得的appid。
ts uint32 unix时间戳(从UTC时间1970年1月1日00:00:00到当前时刻的秒数)。
version string 协议版本号,返回码固定为 “V3M”
contractid string 任务id。发布任务后,系统给任务分配的的唯一ID。为字符串。
step uint32 任务的步骤,step从1开始计。step=1表示第一步,各个步骤都是必选。

第一步内容固定为下载应用,由平台判断用户是否完成。
第二步、第三步内容和完成判断均由开发者自由实现(内容不可为连续登陆、充值等条件)。

payitem string 道具礼包id。(不能有特殊字符)。

若本次回调需要发货(cmd字段值为check_award 或 award),本字段值为该步骤道具礼包id,开发者需直接给用户发放该id的道具礼包。
其他情况,本字段值为空。

billno string 发放奖励流水号,由平台生成,传给应用。应用需记录该流水号,用于开发商与平台对帐。
pkey string 本字段旨在生成一个辅助签名,用于增强任务回调接口安全性。pkey算法:md5(mid+密文串+ts)。

其中,密文串为开发者在投放任务时手工输入的一个字符串。若开发者未手工录入密文串,系统将默认用该投放app的appkey作为密文串参与签名pkey计算。
密文串仅包含大小写英文字母或数字、10-32位的字符串。每个任务均可录入不同密文串。

示例:
mid=aaa,密文串填写的是ccc,ts时间是1399541144,则
pkey=md5(aaaccc1399541144)= de2e41905a65fe507d0da7db91b34ff9

sig string 请求串的签名,由需要签名的参数生成。

(1)签名方法请见文档:腾讯开放平台第三方应用签名参数sig的说明。
(2)按照上述文档进行签名生成时,需注意回调协议里多加了一个步骤:?
在构造源串的第3步“将排序后的参数(key=value)用&拼接起来,并进行URL编码”之前,需对value先进行一次编码(编码规则为:除了 0~9 a~z A~Z?!*() 之外其他字符按其ASCII码的十六进制加%进行表示,例如“-”编码为“%2D”、”_”编码为”%5F”)。(增加)
(3)以每次接收到的参数为准,接收到的所有参数除sig以外都要参与签名。为方便平台后续对协议进行扩展,请不要将参与签名的参数写死。


2.3 特别说明

(1)在任务投放端“创建移动推广任务”页面填写的接口地址,可自行填写测试环境或正式环境地址。提交审核前,务必将回调接口更新为正式地址。
(2)回调接口超时时间为2秒。若2秒内没收到返回码,平台会记录接口超时,并提示用户系统繁忙。
(3)系统回调本接口峰值 500次/秒,务必确保接口性能。
(4)接口回调逻辑:不同步骤和配置下的cmd字段值:

步骤 Cmd字段值 广告主操作
Step1:下载应用 award 给用户发放步骤1礼包
Step2:广告主自定义 check 查询用户是否完成该任务步骤2(系统自动扫描时触发)
check_award 查询用户是否完成步骤2,若完成,则给用户发放步骤2礼包

(用户领奖时触发)

Step3:广告主自定义 check 查询用户是否完成该任务步骤3(系统自动扫描时触发)
check_award 查询用户是否完成步骤3,若完成,则给用户发放步骤2礼包

(用户领奖时触发)

(5)务必严格遵守回调接口返回码规范,包括返回字段类型、返回码数值等。(出现bug任务直接下线,且进行处罚!)
(6)任务创建成功后,任务步骤、任务奖励不可再编辑。
(7)测试过程中不会产生任何费用。
(8)接口中所有字段都要做encode。

(9)广告主需做mid和用户应用内账户的映射。
(10)可能会出现同一部手机(mid)在应用内有多个账户。或者同一个账户在应用内有多个角色。
当出现这种情况是,广告主方自行决定给哪个账户或角色发放奖励。(建议给最近登录的角色发放)。
(11)投放任务时,可通过 MidDemo.apk 获取测试手机的mid进行接口联调。可在 任务联调页面下载MidDemo.apk。
(12)集成MTA SDK、获取Mid的具体方式请进入 http://mta.qq.com/ 了解并获取帮助。


2.4 请求示例

下面演示了sig签名的生成细节。开发者可以下面的示例来验证sig的详细过程,但不能直接复制。
回调移动任务集市V3M请求的签名生成较为复杂,许多应用在此出错,因此下面演示了sig签名的生成细节。开发者可以用下面的示例来验证sig的详细过程,但不能直接复制。

第一步: 应用接收到腾讯平台发送过来的请求。
该请求通过平台发送,因此所有参数都未进行URL编码。但是该请求中所带的sig却进行了URL编码(这一点请开发者关注,在回调协议中这里比较特殊)。
请求示例如下:
<font color=blue>http://xx.yy.com:10004/cgi-bin/mob_callback.fcg?appid=8888&billno=64192ea29e8cf6404ce59aaa634df8320fd8ce5c_8888T3M20140528171657_1&cmd=check_award&contractid=8888T3M20140528171657&openid=64192ea29e8cf6404ce59aaa634df8320fd8ce5c&payitem=pkg1&pkey=8ab0696f11276a1a21761bb8945564ea&sig=DZZN2Z3kI66Txr4ix608jmziFWI%3D&step=2&ts=1401283809&version=V3M </font>

特别提示:
(1)示例中的IP即买方在任务集市投放端“任务V3接口”页面中配置的服务器IP。
(2)示例中的“/cgi-bin/mob_callback.fcg”为买方在任务集市投放端“任务V3接口”页面中配置的url里的uri(域名后的CGI完整路径),供腾讯发货时调用。
mobilerenwujishijieruliucheng-02.png

第二步: 应用对该请求进行解析,根据得到的请求源参数来计算pkey。
其中pkey的生成规则为: pkey=md5(64192ea29e8cf6404ce59aaa634df8320fd8ce5c1112223331401283809)=8ab0696f11276a1a21761bb8945564ea 如果自己计算得到的pkey与请求带有的pkey不一致,则请求非法。

第三步: 应用对该请求进行解析,根据得到的请求源参数来计算sig。
对上面的请求进行解析,得到源参数如下:
method: GET
url_path:/cgi-bin/mob_callback.fcg
假设appkey为:111222333

请求源参数以及对应的值为:
(注意:请以接收到的参数为准,除sig外的所有参数都需要参与签名。请仔细核对,如果拆分结果不对,则后面的步骤都是错误的。)
[appid] : [8888]
[billno] : [64192ea29e8cf6404ce59aaa634df8320fd8ce5c_8888T3M20140528171657_1]
[cmd] : [check_award]
[contractid] : [8888T3M20140528171657]
[openid] : [64192ea29e8cf6404ce59aaa634df8320fd8ce5c]
[payitem] : [pkg1]
[pkey] : [8ab0696f11276a1a21761bb8945564ea]
[step] : [2]
[ts] : [1401283809]
[version] : [V3M]

需特别说明的是在回调发货协议中,在进行签名sig生成时,回调协议里多加了一个步骤:
在构造源串的第3步之前(sig生成通用步骤说明详见这里),需对value先按照如下编码规则进行编码(注意这里不是urlencode): 除了 0~9 a~z A~Z !*() 之外其他字符按其ASCII码的十六进制加%进行表示,例如“-”编码为“%2D”,“_”编码为”%5F”。

编码后的参数为:
[appid] : [8888]
[billno] : [64192ea29e8cf6404ce59aaa634df8320fd8ce5c%5F8888T3M20140528171657%5F1]
[cmd] : [check%5Faward]
[contractid] : [8888T3M20140528171657]
[openid] : [64192ea29e8cf6404ce59aaa634df8320fd8ce5c]
[payitem] : [pkg1]
[pkey] : [8ab0696f11276a1a21761bb8945564ea]
[step] : [2]
[ts] : [1401283809]
[version] : [V3M]

执行构造源串的第3步:“将排序后的参数(key=value)用&拼接起来,并进行URL编码”(sig生成通用步骤说明详见这里 http://open.qq.com/tools )。

则源串为:GET&%2Fcgi-bin%2Fmob_callback.fcg&appid%3D8888%26billno%3D64192ea29e8cf6404ce59aaa634df8320fd8ce5c%255F8888T3M20140528171657%255F1%26cmd%3Dcheck%255Faward%26contractid%3D8888T3M20140528171657%26openid%3D64192ea29e8cf6404ce59aaa634df8320fd8ce5c%26payitem%3Dpkg1%26pkey%3D8ab0696f11276a1a21761bb8945564ea%26step%3D2%26ts%3D1401283809%26version%3DV3M

密钥为:111222333&

根据HMAC-SHA1加密算法将源串以及密钥进行加密,然后对加密后的字符串经过Base64编码后,得到的Sig的值。 生成的签名为:DZZN2Z3kI66Txr4ix608jmziFWI=

发送请求时所有参数都要进行URL编码。如果对签名Sig进行编码,会得到如下结果:
DZZN2Z3kI66Txr4ix608jmziFWI%3D

因此得到完整的请求URL是:
<font color=blue>http://xx.yy.com:10004/cgi-bin/mob_callback.fcg?appid=8888&billno=64192ea29e8cf6404ce59aaa634df8320fd8ce5c_8888T3M20140528171657_1&cmd=check_award&contractid=8888T3M20140528171657&openid=64192ea29e8cf6404ce59aaa634df8320fd8ce5c&payitem=pkg1&pkey=8ab0696f11276a1a21761bb8945564ea&sig=DZZN2Z3kI66Txr4ix608jmziFWI%3D&step=2&ts=1401283809&version=V3M </font>

第四步: 应用将自己生成的sig与腾讯支付后台发送的请求中的sig进行比对。
注意: 应用接收到的腾讯支付平台发送过来的请求后,请先对请求中的sig值做一次URL解码;
然后再将解码后的sig值与应用自己生成的sig值进行比对。
在PHP中,通过$_GET['sig']获取sig值,PHP语言本身对sig值进行了URL解码,不需要再次解码。

如果sig值一致,表示该请求合法,应用可以处理该请求并将结果返回给腾讯支付后台。


2.5 协议返回包

应用的返回包应该包含如下参数:
ret: 返回码。需要为 “整数” 类型
msg: 错误信息。编码格式:utf8


2.6 协议返回码

应用的返回码 分为标准返回码和自定义返回码两类。

标准返回码如下:
0: 步骤已完成 或 奖励发放成功
1: 查找不到该用户
2:用户尚未完成本步骤
3:该步骤奖励已发放过

100: token已过期
101: token不存在
102: 奖励发放失败
103: 请求参数错误

注:返回码0-200为平台保留,广告主自定义返回码务必在200-10000之间。返回码必须严格遵守规范,若不遵守,将出现外网故障。


2.7 返回示例

正确返回示例:

Content-type: text/html; charset=utf-8
{"ret":0,"msg":"OK”}

错误返回示例:(开发者返回给平台的自定义错误码一定要控制在200-10000的正整数之间)

Content-type: text/html; charset=utf-8
{"ret":200,"msg":"参数错误"}

以上信息是否解决您的问题?

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部