10/22/2024 16:10:39

Achievement

I. Achievement reporting(The leaderboard displays data reporting)

1.1 Interface name

/v2/acvm/report

1.2 Request parameters

Special notes:

• The reporting content needs to be agreed with the platform. As for dual platform contact persons, please consult MSDK Assistant;
• WeChat achievement reporting interface does not verify token, so token is acceptable as long as it is not empty (but it is still recommended to fill in token correctly, because the interface may add the verification of token in the future).In addition, MSDK's WeChat reporting interface does not perform token verification, either;
• For WeChat achievement reporting, MSDK only transparently transmits the data corresponding to achievements (if it is a json object, it will be converted to a string and then transparently transmitted);
• For QQ achievement reporting, MSDK will check the format of achievements. For details, please see the format description later;

1) Format description of achievements for QQ achievement reporting

QQ achievements is an array, and each element of the array is an object. Such an object contains the following fields:

• data (string): achievement value;
• expires (string): unix timestamp, unit s, indicating at which time point the data expires. The 0 time point identifies that the data never times out. If the data is not passed, the time point is defaulted as 0;
• type (int): the corresponding type of the uploaded field. For the description of specific types, please refer to the documentation provided by QQ Game Center. For example, 1 means level;
• bcover (int): for the data related to the leaderboard, bcover = 0; for others, bcover = 1. The leaderboard of the Game Center is consistent with the game ranking list; 1 means to overwrite the reporting, which means this reporting will overwrite the previous data. Not passing the data or passing other values indicate incremental reporting, which only records higher data than the last time;

2) Recommendations on the achievements format of WeChat achievement reporting

(Originated from MSDKV3 Documentation)

Recommendations on the format

```json
// A single user's data:
{
    "baseinfo":
    {
        "gamename":"Universal Aircraft War", // String; game name; it is suggested to fill in the field
        "platid": 0, // Integer; platform type 0: iOS 1: Andriod; required
        "partitionid": "9", // String; partition ID. If the game doesn't have the "partition" concept, this field can be omitted. If it has the concept, it is suggested to fill in the field  
        "roleid": "wongcai", // String; role ID. If the game doesn't have the "role" concept, this field can be omitted. If it has the concept, it is suggested to fill in the field  
        "level": 2 // Integer; user level. If the game doesn't have the "level" concept, this field can be omitted. If it has the concept, it is suggested to fill in the field  
    },
    "battleinfo":
    {
        "score": 4288625. // Integer; this value affects WeChat game ranking list; it is not Required; but without this data, there will not be the game ranking lis (Take "Universal Aircraft War" as an example. This field is filled with the score obtained in the game)
        "iswin": true //boolean; whether or not the player wins the current match; the field is suitable for chess and cards. If the game doesn't have the "win" concept, this field can be omitted. If it has the concept, it is suggested to fill in the field
    },
    "userdefined":
    { // The game's self-defined data, which is reported by the platform. The game does not need to report it for the time being. For example, the platform requires the game "Universal Aircraft War" to report its self-defined data such as gold coins, physical strength, and fighter planes, where the "value" type is generally an integer. or string:
        "goldcoin": { // user-defined data ID1
        "name": "gold coin", // String; data name 
        "value": 358267. // Integer; data value 
    },
    "power":
    { // User-defined dataID2
        "name": "physical strength", // String; data name 
        "value": 86542, // Integer; data value 
    },
    "plane":
    { // User-defined dataID3
        "name": "fighter plane", // String; data name 
        "value": "Seraphim", // String; data content 
    },
    // The user-defined data can be constantly extended 
 } // Support multiple user batch data at the same time; able to combine the above multiple singletons into a Json array format: [{user data 1}, {user data 2}, ...]
```

3) Steam achievement reporting format

Recommendations on the format

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

4) Demo

• QQ

Reference

```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"}]}'
```

Return

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

• WX

Reference

```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}}}'
```

Return

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

II. Achievement query (currently only supports Steam)

2.1 Interface name

/v2/acvm/stats

2.2 Request parameters

2.3 Return

• Demo

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

III. Check the player's achievement (currently only supports Steam)

3.1 Interface name

/v2/acvm/query

3.2 Request parameters

3.3 Return

• Demo

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

IV. Query the statistics of the entire game (currently only supports Steam)

4.1 Interface name

/v2/acvm/stats_global

4.2 Request parameters

4.3 Return

• Demo

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