任务集市V3买方APP开发联调说明

目录

1 重要说明


V3系统中,任务创建成功后不可再编辑任务步骤和任务内容。
每个任务都有一个唯一的任务id。应用的接入方案需灵活,尽量不要把任务id和游戏版本绑定,以方便任务运营。
任务集市v3系统,有如下接口需要接入:

接口名称 接口功能
任务集市v3任务完成查询和发货协议说明
实现任务步骤完成状态判断和发货控制


2 接入开发流程


Step1:设定任务的任务内容。
任务内容和形式由开发者自行决定(不可为连续登陆、充值等特殊条件),同时需要能识别到用户是否完成任务步骤。

Step2:识别来自任务集市的用户。
当用户第一次从任务集市进入买方应用时,平台将向买方传递如下参数:
app_user_source:值为marketV3,用于标识用户源自交叉推广渠道任务集市V3版本;
app_contract_id:任务id,标识用户通过那个任务进入应用;
app_custom:自定义参数,应用可以自由设置参数内容

建议开发者不要把任务id和游戏版本绑定,便于任务灵活调整。

开发者需记录用户第一次进入应用的数据,确保后续用户从其他入口进入游戏时也能正常完成任务并领奖。

Step3:买方答复平台查询任务步骤完成状态请求。
平台会主动查询用户是否完成某任务的步骤,进行步骤完成率的统计。
此时,买方需按照“任务集市v3任务完成查询和发货协议说明”来解析请求,并答复平台该用户是否完成任务步骤和用户完成步骤所在的zoneid。

Step4:买方向用户发放奖励。 当用户点击“领取奖励”按钮时,平台向买方应用发出任务步骤是否完成并发货请求。买方需遵循协议“任务集市v3任务完成查询和发货协议说明”,进行回调URL的开发,内部完成判断任务步骤是否完成,如完成就给用户奖励发货,并答复奖励是否成功及用户发货所在的zoneid。

3. 开发商回调接口协议

3.1 接口说明

本接口由开发者实现,开发者在 任务投放端 创建任务界面填写本接口地址,由平台回调。
由于部分业务扩展,上海服务器暂时不支持内网IP回调发货,请各位留意,建议暂时可以使用广州服务器。
当用户领取任务后去应用做任务,完成任务后在平台点击“领取奖励”按钮时,平台将回调该接口向开发者应用发出“任务步骤是否完成,完成就发货”请求,应用收到请求后,查询该用户是否完成某步骤,若完成,则给用户发货,发货成功后返回给平台“发货成功”。

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

3.2 协议参数

请开发者特别关注:
平台后续可能对协议进行扩展,请不要将参与签名的参数写死。
计算签名时,请以每次接收到的参数为准,接收到的所有参数除sig以外都要参与签名。

平台回调本接口 返回给开发者如下参数:

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

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

openid string 用户的Openid。用户通过任务集市进入应用时,URL会带该参数。
appid string 应用的appid。
pf string 跳转到应用首页后,URL后会带该参数,表示应用的来源平台。由平台直接传给应用。
ts string linux时间戳(从UTC时间1970年1月1日00:00:00到当前时刻的秒数)。
version string 协议版本号,返回码固定为“V3”。
contractid string 任务id。 在任务集市v3系统发布任务后,系统给任务分配的的唯一ID。
step int 任务的步骤,step从1开始计。step=1表示第一步,四个步骤都是必选。

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

payitem string 道具礼包id。

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

billno string 发放奖励流水号,由平台生成,传给应用。应用需记录该流水号,用于开发商与平台对帐。
providetype string 发货类型,请固定传入2。

0表示道具购买,1表示每日礼包营销活动中的道具赠送,2表示交叉营销任务集市中的奖励发放。

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

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

3.3 特别说明 (一定要看)


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

task_market_v3_Development_documents_02.png

6:如果用户在游戏多个区拥有角色,应用方自行决定给哪个角色发放奖励。(建议给最近登录的角色发放)。
7:务必严格遵守回调接口返回码规范,包括返回字段类型、返回码数值等。(出现bug任务直接下线,且进行处罚!)
8:任务创建成功后,任务步骤、任务奖励不可再编辑。
9:注意:计算sig报错,检查配置任务集市v3回调接口路径最前端是否多填写了一个 “/”,创建任务后配置任务集市v3回调接口路径前端不需要添加“/” 。
10:测试过程中不会产生任何费用。
11:接口中所有字段都要做encode。

3.4 请求示例


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

第一步: 应用接收到腾讯平台发送过来的请求。
该请求通过平台发送,因此所有参数都未进行URL编码。但是该请求中所带的sig却进行了URL编码(这一点请开发者关注,在回调协议中这里比较特殊)。
请求示例如下: http://IP:9001/cgi-bin/check_award?appid=24885&billno=4BE1D6AE-5324-11E3-BC76-00163EB7F40B&cmd=check_award&contractid=24885T320131118114134&openid=00000000000000000000000002
5900A0&payitem=pkg&pf=qzone&providetype=2&step=3&ts=13850897
80&version=V3&sig=E%2BS6dC%2BhooDCtwvhnGTFIFGrfng%3D
特别提示:
1. 示例中的IP即买方在任务集市投放端“任务V3接口”页面中配置的服务器IP。
2. 示例中的“cgi-bin/check_award”为买方在任务集市投放端“任务V3接口”页面中配置的cgi,供腾讯发货时调用。

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

请求源参数以及对应的值为:
(注意:请以接收到的参数为准,除sig外的所有参数都需要参与签名。请仔细核对,如果拆分结果不对,则后面的步骤都是错误的。)
[appid] : [24885]
[billno] : [4BE1D6AE-5324-11E3-BC76-00163EB7F40B]
[cmd] : [check_award]
[contractid] : [24885T320131118114134]
[openid] : [000000000000000000000000025900A0]
[payitem] : [pkg]
[pf] : [qzone]
[providetype] : [2]
[step] : [3]
[ts] : [1385089780]
[version] : [V3]

需特别说明的是在回调发货协议中,在进行签名生成时,回调协议里多加了一个步骤:
在构造源串的第3步之前(sig生成通用步骤说明详见这里),需对value先按照如下编码规则进行编码(注意这里不是urlencode):
除了 0~9 a~z A~Z !*() 之外其他字符按其ASCII码的十六进制加%进行表示,例如“-”编码为“%2D”,“_”编码为“%5F”。
特别注意:
1、billno在现网有 _ 和 - 的情况,但是沙箱联调中没有。cmd沙箱联调和现网都可能会出现 _ 和 - 的情况,请大家要注意替换。
2、正式环境中除了用户点击领奖按钮触发回调外,平台系统回调检查时billno和payitem值为空的情况也是正常的,请大家把这部分的逻辑加入判断并以实际值为准。


编码后的参数为:
[appid] : [24885]
[billno] : [4BE1D6AE%2D5324%2D11E3%2DBC76%2D00163EB7F40B]
[cmd] : [check%5Faward]
[contractid] : [24885T320131118114134]
[openid] : [000000000000000000000000025900A0]
[payitem] : [pkg]
[pf] : [qzone]
[providetype] : [2]
[step] : [3]
[ts] : [1385089780]
[version] : [V3]

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

则源串为:GET&%2Fcgi-bin%2Fcheck_award&appid%3D24885%26billno%3D4BE1D6AE%252D5324%252D11E3%252DBC76%252D00163EB7F40B%26
cmd%3Dcheck%255Faward%26contractid%3D24885T320131118114134%26openid%3D000000000000000000000000025900A0%26payitem%3Dpkg%26
pf%3Dqzone%26providetype%3D2%26step%3D3%26ts%3D1385089780%26version%3DV3

密钥为:111222333&

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

第三步: 应用将自己生成的sig与腾讯支付后台发送的请求中的sig进行比对。
注意: 应用接收到的腾讯支付平台发送过来的请求后,请先对请求中的sig值做一次URL解码;
然后再将解码后的sig值与应用自己生成的sig值进行比对。
在PHP中,通过$_GET['sig']获取sig值,PHP语言本身对sig值进行了URL解码,不需要再次解码。
如果sig值一致,表示该请求合法,应用可以处理该请求并将结果返回给腾讯支付后台。

3.5 协议返回包


应用的返回包应该包含如下参数:
ret: 返回码。需要为“整数”类型
msg: 错误信息。编码格式:utf8
zoneid: 应用给玩家在哪个区/服的角色发放奖励。为英文字符串,不可包含中文。用于平台记录,不具备实际功能。

3.6 协议返回码

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

标准返回码如下:
0: 步骤已完成 或 奖励发放成功
1: 用户尚未在应用内创建角色
2:用户尚未完成本步骤
3:该步骤奖励已发放过
100: token已过期
101: token不存在
102: 奖励发放失败
103: 请求参数错误

沙箱联调时,ret返回码仅能返回0和3。
注:返回码0-200为平台保留, 开发者自定义返回码务必在200-10000之间。返回码必须严格遵守规范,若不遵守,将出现外网故障。

3.7 返回示例

正确返回示例:

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



错误返回示例:(开发者返回给平台的自定义错误码一定要控制在200-10000的正整数之间,必须带有zoneid,如果查不到用户zoneid,该字段返回空字符串,否则系统会报错。)

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


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

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部