# 商业化任务

场景：用户在美团业务线完成商业化行为（浏览、下单等）后，便可在游戏内领取对应奖励。
功能：平台将每个这种链路，抽取为一个商业化任务，游戏方只与平台对接一次即可，无需与具体的每个业务线做对接。

# 接口

# 查询任务列表

URL: https://mgc.meituan.com/mgc/gateway/api/v3/task/query
Method: POST
Content-Type: application/json

入参

参数名	类型	是否必填	说明
clientId	String	是	应用ID 可从开放平台查看
ts	long	是	发送请求的时间戳 1970-01-01 00:00:00.000到当前时刻的毫秒数
sign	String	是	参数签名，见附录说明
nonce	String	是	随机字符串
signType	String	是	签名算法固定为: SHA1
encryptType	String	是	加密算法固定为: AES-256-GCM
bizContent	String	是	业务参数需要加密见下表

bizContent内容

参数名类型默认值是否必填说明

mgcId String 是美团侧玩家角色号

extraInfo String 否扩展信息

参数名	类型	默认值	是否必填	说明
mgcId	String		是	美团侧玩家角色号
extraInfo	String		否	扩展信息

extraInfo内容

参数名	类型	默认值	是否必填	说明
cityId	int	无	是	城市id
appVersion	String	无	是	美团APP版本号
clientOS	String	无	是	客户端平台，取值：'iphone', 'android'
app	int	无	是	app类型，美团主app：0，美团极速版：113

出参

参数名类型默认值是否必填说明

code int 是异常码

msg String 是异常描述

taskInfoList List 否任务列表信息由 MgcTaskInfo 列表组成
```
{
    "code": 0,
    "msg": "ok",
    "data": {
        "taskInfoList": { 
          //详见任务数据 
        }
    }
}
```
code !=0 时为失败，详见异常码

# 领取任务奖励

URL: https://mgc.meituan.com/mgc/gateway/api/v3/task/reward
Method: POST
Content-Type: application/json

入参

参数名	类型	是否必填	说明
clientId	String	是	应用ID 可从开放平台查看
ts	long	是	发送请求的时间戳 1970-01-01 00:00:00.000到当前时刻的毫秒数
sign	String	是	参数签名，见附录说明
nonce	String	是	随机字符串
signType	String	是	签名算法固定为: SHA1
encryptType	String	是	加密算法固定为: AES-256-GCM
bizContent	String	是	业务参数需要加密见下表

bizContent内容

参数名类型默认值是否必填说明

mgcId String 是美团游戏平台玩家角色Id

taskId String 是任务id

extraInfo String 否扩展信息

参数名	类型	是否必填	说明
mgcId	String	是	美团游戏平台玩家角色Id
taskId	String	是	任务id
extraInfo	String	否	扩展信息

extraInfo内容

参数名	类型	默认值	是否必填	说明
cityId	int	无	是	城市id
appVersion	String	无	是	美团APP版本号
clientOS	String	无	是	客户端平台，取值：'iphone', 'android'
app	int	无	是	app类型，美团主app：0，美团极速版：113

出参

参数名	类型	是否必填	说明
code	int	是	异常码
msg	String	是	异常描述
taskInfo	MgcTaskInfo	否	任务信息

{
    "code": 0,
    "msg": "ok",
    "data": {
        "taskInfo": { 
          //详见任务数据 
        }
    }
}

code !=0 时为失败，详见异常码。

# 任务数据

任务状态:

code	名称	说明
1	初始化	任务初始化、尚未生效
2	进行中	任务正在进行，等待用户去完成
3	可领奖	任务已经达成完成条件，可以领取奖励
4	已领奖	任务已经完成领奖行为
5	已失败	任务触发失败条件，不可继续完成
6	不可用	任务不可用

对于游戏方，如无特殊说明，只关注2、3、4 三种状态即可。

任务信息 MgcTaskInfo

参数名	类型	是否必填	说明
id	int	是	任务id
status	int	是	任务状态
process	int	是	任务进度
dailyFinishTimes	int	是	当日已完成次数
dailyRewardTimes	int	是	当日已领奖次数
mgcTaskBaseInfo	MgcTaskBaseInfo	否	任务基础信息
extraContent	String	否	额外信息，不同id的任务额外信息不同，可以为空
mgcTaskExtraData	MgcTaskExtraData	否	任务扩展信息

任务基础信息 MgcTaskBaseInfo

参数名	类型	是否必填	说明
viewTitle	String	是	显示标题
viewContent	String	是	显示内容
viewProcessName	String	是	进度名称
viewTips	String	是	提示内容
viewJumpUrl	String	是	跳转链接
minLimit	int	否	进度下限
maxLimit	int	否	进度上限

任务扩展信息 MgcTaskExtraData

参数名	类型	是否必填	说明
nextAvailableFinishTime	long	否	任务下一次可完成时间
curPeriodParams	Map<Integer,String>	否	当前周期参数
allPeriodParams	Map<Integer,String>	否	全周期参数

# 任务时机上报

URL: https://mgc.meituan.com/mgc/gateway/api/v3/task/report
Method: POST
Content-Type: application/json

入参

参数名	类型	是否必填	说明
clientId	String	是	应用ID 可从开放平台查看
ts	long	是	发送请求的时间戳 1970-01-01 00:00:00.000到当前时刻的毫秒数
sign	String	是	参数签名，见附录说明
nonce	String	是	随机字符串
signType	String	是	签名算法固定为: SHA1
encryptType	String	是	加密算法固定为: AES-256-GCM
bizContent	String	是	业务参数需要加密见下表

bizContent内容

参数名类型默认值是否必填说明

mgcId String 是美团侧玩家角色号

timing int 是上报时机（具体任务相关）

content String 否上报内容
出参

参数名类型默认值是否必填说明

code int 是异常码

msg String 是异常描述
```
{
    "code": 0,
    "msg": "ok",
    "data": null
}
```
code !=0 时为失败，详见异常码。

参数名	类型	是否必填	说明
mgcId	String	是	美团侧玩家角色号
timing	int	是	上报时机（具体任务相关）
content	String	否	上报内容

# 完成任务

URL: https://mgc.meituan.com/mgc/gateway/api/v3/task/finish
Method: POST
Content-Type: application/json

入参

参数名	类型	是否必填	说明
clientId	String	是	应用ID 可从开放平台查看
ts	long	是	发送请求的时间戳 1970-01-01 00:00:00.000到当前时刻的毫秒数
sign	String	是	参数签名，见附录说明
nonce	String	是	随机字符串
signType	String	是	签名算法固定为: SHA1
encryptType	String	是	加密算法固定为: AES-256-GCM
bizContent	String	是	业务参数需要加密见下表

bizContent内容

参数名类型默认值是否必填说明

mgcId String 是美团游戏平台玩家角色Id

taskId String 是任务id

extraInfo String 否扩展信息
extraInfo内容

参数名类型默认值是否必填说明

cityId int 无是城市id

appVersion String 无是美团APP版本号

clientOS String 无是客户端平台，取值：'iphone', 'android'
出参

参数名类型默认值是否必填说明

code int 是异常码

msg String 是异常描述
```
{
    "code": 0,
    "msg": "ok",
    "data": null
}
```
code !=0 时为失败，详见异常码。

参数名	类型	是否必填	说明
mgcId	String	是	美团游戏平台玩家角色Id
taskId	String	是	任务id
extraInfo	String	否	扩展信息

# 完成任务并领取奖励

URL: https://mgc.meituan.com/mgc/gateway/api/v3/task/finishAndReward
Method: POST
Content-Type: application/json

入参

参数名	类型	是否必填	说明
clientId	String	是	应用ID 可从开放平台查看
ts	long	是	发送请求的时间戳 1970-01-01 00:00:00.000到当前时刻的毫秒数
sign	String	是	参数签名，见附录说明
nonce	String	是	随机字符串
signType	String	是	签名算法固定为: SHA1
encryptType	String	是	加密算法固定为: AES-256-GCM
bizContent	String	是	业务参数需要加密见下表

bizContent内容

参数名类型默认值是否必填说明

mgcId String 是美团游戏平台玩家角色Id

taskId String 是任务id

extraInfo String 否扩展信息
extraInfo内容

参数名类型默认值是否必填说明

cityId int 无是城市id

appVersion String 无是美团APP版本号

clientOS String 无是客户端平台，取值：'iphone', 'android'

参数名	类型	是否必填	说明
mgcId	String	是	美团游戏平台玩家角色Id
taskId	String	是	任务id
extraInfo	String	否	扩展信息

出参

参数名	类型	是否必填	说明
code	int	是	异常码
msg	String	是	异常描述
taskInfo	MgcTaskInfo	否	任务信息

{
    "code": 0,
    "msg": "ok",
    "data": {
        "taskInfo": { 
          //详见任务数据 
        }
    }
}

code !=0 时为失败，详见异常码。

# 退单检查

URL: https://mgc.meituan.com/mgc/gateway/api/v3/task/checkOrderRefund
Method: POST
Content-Type: application/json

入参

参数名	类型	是否必填	说明
clientId	String	是	应用ID 可从开放平台查看
ts	long	是	发送请求的时间戳 1970-01-01 00:00:00.000到当前时刻的毫秒数
sign	String	是	参数签名，见附录说明
nonce	String	是	随机字符串
signType	String	是	签名算法固定为: SHA1
encryptType	String	是	加密算法固定为: AES-256-GCM
bizContent	String	是	业务参数需要加密见下表

bizContent内容

参数名类型默认值是否必填说明

mgcId String 是美团游戏平台玩家角色Id

activityId String 是活动编码，见附录
出参

参数名类型默认值是否必填说明

code int 是异常码

msg String 是异常描述
```
{
    "code": 0,
    "msg": "ok"
}
```
code !=0 时为失败，详见异常码。

参数名	类型	默认值	是否必填	说明
mgcId	String		是	美团游戏平台玩家角色Id
activityId	String		是	活动编码，见附录

# 跨游戏任务事件上报

URL: https://mgc.meituan.com/mgc/gateway/api/v3/collector/reportSingleEvent
Method: POST
Content-Type: application/json

入参

参数名	类型	是否必填	说明
clientId	String	是	应用ID 可从开放平台查看
ts	long	是	发送请求的时间戳 1970-01-01 00:00:00.000到当前时刻的毫秒数
sign	String	是	参数签名，见附录说明
nonce	String	是	随机字符串
signType	String	是	签名算法固定为: SHA1
encryptType	String	是	加密算法固定为: AES-256-GCM
bizContent	String	是	业务参数需要加密见下表

bizContent内容

参数名类型默认值是否必填说明

mgcId String 是美团游戏平台玩家角色Id

baseInfo String 是基础信息

eventInfo String 是事件信息
baseInfo内容

参数名类型默认值是否必填说明

gameName String 是游戏名称

gameSn long 是幂等号，业务自定义长度必须<=36

cityId int 否城市id

deviceId String 否设备id

参数名	类型	是否必填	说明
mgcId	String	是	美团游戏平台玩家角色Id
baseInfo	String	是	基础信息
eventInfo	String	是	事件信息

参数名	类型	是否必填	说明
gameName	String	是	游戏名称
gameSn	long	是	幂等号，业务自定义长度必须<=36
cityId	int	否	城市id
deviceId	String	否	设备id

eventInfo内容

参数名	类型	是否必填	说明
happenTime	long	是	触发时间，时间戳，当前时间
eventId	long	是	事件id，业务自定义
eventName	String	是	事件名称，业务自定义

出参

参数名类型默认值是否必填说明

code int 是异常码

msg String 是异常描述
```
{
    "code": 0,
    "msg": "ok"
}
```
code !=0 时为失败，详见异常码。

# 附录

异常码

异常码	异常说明
3000001	失败，系统错误
3001001	游戏类型不存在
3001002	玩家不存在
3001003	参数错误，游戏类型不合法
3001004	游戏配置不存在
3001005	任务id不存在
3001006	当前游戏不存在该任务
3001007	任务已经完成过
3001008	任务不可通过这个方式完成
3001009	任务已结束
3000010	状态异常，任务不可领奖
3000012	奖励发送失败

活动编码

编码活动说明

100001 JJ斗地主开宝箱活动

编码	活动说明
100001	JJ斗地主开宝箱活动

Sign签名的计算算法为

String data = "" //bizContent参数按照参数名字典排序，以&符连接，例如:a=1&b=2&c=3
data += String.format("&uri=%s", URLEncoder.encode("/api/v3/task/query")); // path随着访问的url改变
data += "&method=POST";
data += String.format("&secret=%s", appSecret); //开发者可以在开发者后台查询得到开放平台为其分配的appId和appSecret
// 以上生成data数据的顺序不可改变
String secretKey = AESUtil.createKey(appId + "&" + appSecret);  
String signature = SHAUtil.encryptSHA1Str(data + secretKey);

AESUtil工具类

import java.security.MessageDigest;
import javax.crypto.SecretKey;

public static String createKey(String password) {
        try {
            byte[] keyBytes = password.getBytes(StandardCharsets.UTF_8);
            MessageDigest sha = MessageDigest.getInstance("SHA-1");
            keyBytes = sha.digest(keyBytes);
            keyBytes = Arrays.copyOf(keyBytes, 32);
            SecretKey secretKey = new SecretKeySpec(keyBytes, "AES");
            return Base64.getEncoder().encodeToString(secretKey.getEncoded());
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

SHAUtil工具类

		import java.nio.charset.StandardCharsets;
		import java.security.MessageDigest;
		import org.apache.commons.codec.digest.DigestUtils;

		public static String encryptSHA1Str(String text) {
        byte[] bytes = encryptSHA(text, "SHA-1");
        return byte2hex(bytes);
    }

    private static byte[] encryptSHA(String text, String algorithm) {
        MessageDigest md;
        try {
            md = MessageDigest.getInstance(algorithm);
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalArgumentException(e);
        }

        byte[] infoBytes = text.getBytes(StandardCharsets.UTF_8);
        md.update(infoBytes);
        return md.digest();
    }

    private static String byte2hex(byte[] bytes) {
        StringBuilder stringBuilder = new StringBuilder();
        for (byte b : bytes) {
            String hex = Integer.toHexString(b & 0xFF);
            if (hex.length() == 1) {
                stringBuilder.append("0");
            }

            stringBuilder.append(hex);
        }

        return stringBuilder.toString();
    }

bizContent内容的加密使用AES_256_GCM算法加密，加密工具类如下

以下代码为AES_256_GCM的加密java示例代码，仅供参考
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.SecureRandom;
import java.util.Arrays;
import java.util.Base64;

private static final String ALGORITHM = "AES";
private static final String ALGORITHM_PADDING = "AES/GCM/NoPadding";
private static final int AES_KEY_LENGTH_BIT = 256;
public static final int GCM_NONCE_LENGTH_BIT = 128;
public static final int GCM_TAG_LENGTH_BIT = 128;

public static String encryptWithAESGCM256(String key, byte[] content) {

    try {
        byte[] keyBytes = Base64.getDecoder().decode(key.getBytes(StandardCharsets.UTF_8));
        SecretKeySpec secretKey = new SecretKeySpec(keyBytes, ALGORITHM);

        Cipher cipher = Cipher.getInstance(ALGORITHM_PADDING, "SunJCE");

        SecureRandom random = SecureRandom.getInstance("NativePRNGNonBlocking");
        final byte[] nonceBytes = new byte[GCM_NONCE_LENGTH_BIT / 8];
        random.nextBytes(nonceBytes);
        GCMParameterSpec spec = new GCMParameterSpec(GCM_TAG_LENGTH_BIT, nonceBytes);

        cipher.init(Cipher.ENCRYPT_MODE, secretKey, spec);
        byte[] contentBytes = cipher.doFinal(content);

        byte[] finalBytes = new byte[nonceBytes.length + contentBytes.length];
        System.arraycopy(nonceBytes, 0, finalBytes, 0, nonceBytes.length);
        System.arraycopy(contentBytes, 0, finalBytes, nonceBytes.length, contentBytes.length);
        String result = new String(Base64.getUrlEncoder().encode(finalBytes), StandardCharsets.UTF_8);
        return result;
    } catch (Exception e) {
        logger.error("encrypt error", e);
    }

    return null;
}