04/29/2024 11:54:53

成就

一、成就上报（排行榜展示数据上报）

1.1 接口名

/v2/acvm/report

1.2 请求参数

特别说明：

• 上报内容需要和平台侧约定，双平台接口人请咨询 MSDK 助手；
• 微信成就上报不校验 token，所以 token 只要不为空即可（但还是建议填写正确的 token，因为以后可能会增加对 token 的校验）。另外，目前 MSDK 的微信上报接口也没做 token 校验；
• 微信成就上报 MSDK 只对 achievements 对应的数据进行透传（如果是 json object，会转换为字符串再透传）；
• QQ 成就上报 MSDK 会检查 achievements 的格式，详见后面的格式说明；

1）QQ 成就上报achievements格式说明

QQ achievements 是一个数组，每个数组元素都是一个 object，这个 object 包含如下字段：

• data(string) 成就值；
• expires(string) unix 时间戳，单位 s，标识哪个时间点数据过期，0 标识永不超时，不传递默认为 0；
• type(int) 上传字段对应的类型，具体类型参照手Q游戏中心给出的文档，如1代表等级；
• bcover(int) 与排行榜有关的数据 bcover = 0，其他 bcover = 1。游戏中心排行榜与游戏排行榜保持一致；1 表示覆盖上报，本次上报会覆盖以前的数据，不传递或者传递其它值表示增量上报，只会记录比上一次更高的数据；

2）微信成就上报achievements格式建议

（来源于 MSDKV3文档 ）

格式建议

```json
// 单个用户数据：
{
    "baseinfo":
    {
        "gamename":"全民飞机大战", //字符串型，游戏名称，建议填上
        "platid": 0, //整型，平台类型 0：iOS 1：Andriod，必填
        "partitionid": "9", //字符串型，分区 ID，游戏没有分区概念可省略该项，如果有则建议填上
        "roleid": "wongcai", //字符串型，角色 ID，游戏没有角色概念可省略该项，如果有则建议填上
        "level": 2 //整型，用户等级，游戏用户没有等级概念可省略该项，如果有则建议填上
    },
    "battleinfo":
    {
        "score": 4288625, //整型，该数值影响微信游戏排行榜，非必填，但没有该数据就没有排行榜（以《全民飞机大战》为例，该项填游戏中获得的分数）
        "iswin": true //布尔型，当前局是否胜利，适合棋牌类，没有胜局概念可省略该项，如果有则建议填上
    },
    "userdefined":
    { //游戏自定义数据，由平台侧提需求上报，游戏侧暂无需自主上报，比如平台要求《全民飞机大战》上报金币、体力、战机等自定义数据，其中value类型一般为整型或字符串型：
        "goldcoin": { //自定义数据 ID1
        "name": "金币", //字符串型，数据名称
        "value": 358267, //整型，数据数值
    },
    "power":
    { //自定义数据ID2
        "name": "体力", //字符串型，数据名称
        "value": 86542, //整型，数据数值
    },
    "plane":
    { //自定义数据ID3
        "name": "战机", //字符串型，数据名称
        "value": "炽天使", //字符串型，数据内容
    },
    //自定义数据可不断扩展
 } //同时支持多个用户批量数据，可将以上多个单例组合成json数组格式：[{用户数据1},{用户数据2},...]
```

3）Steam 成就上报格式

格式建议

```json
{
    "openid": "xxx",
    "token": "xxx",
    "achievements": [
    {
        "name": "aaa",
        "value": 12
    },
    {
        "name": "bbb",
        "value": 23
    }
    ]
}
```

4）Demo

QQ参考

```sh
curl 'http://hktest.itop.tencent-cloud.net/v2/acvm/report?channelid=2&gameid=12&os=4&source=1&ts=1999999999&version=2.2.0.0&sig=ssssssssssssssssssssssssssssssss' -d '{"openid":"1234567891234567890","token":"TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT","achievements":[{"type": 3,"bcover": 1,"data": "999","expires":"1999999999"},{"type": 2,"bcover": 1,"data": "1999","expires": "1999999999"}]}'
```

返回

```json
{
    "ret":0,
    "msg":"success"
}
```

微信参考

```sh
curl 'http://hktest.itop.tencent-cloud.net/v2/acvm/report?channelid=1&gameid=12&os=4&source=1&ts=1999999999&version=2.2.0.0&sig=ssssssssssssssssssssssssssssssss' -d '{"openid":"1234567891234567890","token":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","achievements":{"baseinfo": {"gamename": "iTOP_Test","platid": 0,"partitionid": "9","roleid": "hunter","level": 2 },"battleinfo": {"score": 4288625,"iswin": true}}}'
```

返回

```json
{
    "ret":0,
    "msg":"success"
}
```

二、成就查询（仅支持Steam）

2.1 接口名

/v2/acvm/stats

2.2 请求参数

2.3 返回

• 示例

    {
        "data":
        {
            "stats":
            {
                "aaa":
                {
                    "value": 23
                }
            },
            "gameName": "ARK",
            "achievements":
            {
                "bbb":
                {
                    "achieved": 1
                }
            }
        },
        "ret": 0,
        "msg": "success"
    }
  

三、查询玩家成就（仅支持Steam）

3.1 接口名

/v2/acvm/query

3.2 请求参数

3.3 返回

• 示例

    {
        "data":
        {
            "achievements": [
            {
                "apiname": "bbb",
                "achieved": 1,
                "unlocktime": 1557916916
            }],
        "gameName": "ARK"
        },
        "ret": 0,
        "msg": "success"
    }
  

四、查询整个游戏的统计数据（仅支持Steam）

4.1 接口名

/v2/acvm/stats_global

4.2 请求参数

4.3 返回

• 示例

    {
        "data":
        {
            "globalstats":
            {
                "aaa":
                {
                    "total": "23"
                }
            },
            "result": 1
        },
        "ret": 0,
        "msg": "success"
    }