目录

Disassociating an Account

Function

This API is used to disassociate an official game account from teamPlayerId.

Scenario

After a player signs in to the game using a HUAWEI ID, the official game account will be associated teamPlayerId.

To disassociate an official game account from teamPlayerId, the unbindPlayer API can be called on the client side, and this API can be called on the server side.

Prototype

Request Parameters

Body parameters

Parameter Mandatory Type Description
method Yes String

This parameter must be set to external.hms.gs.player.unbindPlayer.

The value contains a maximum of 64 characters.
appId No String

App ID of your game in AppGallery Connect. For details about how to obtain the ID, please refer to Viewing App Information. This parameter is mandatory if the association type of the game level is disassociated.

The value contains a maximum of 32 characters.
cpId Yes String

ID of the game developer in AppGallery Connect. For details about how to obtain the ID, please refer to Viewing App Information.

The value contains a maximum of 32 characters.
teamPlayerId Yes String

Player ID in the game of HarmonyOS 5.0 or later, which can be obtained through the unionLogin API.

The value contains a maximum of 256 characters.
ts Yes Long Timestamp of the current time, which is the number of milliseconds between the current time and 00:00:00 on January 1, 1970 (GMT).
sign Yes String

Signature string used by the Huawei game server to verify request parameters.

To prevent requests from being tampered with, the game needs to generate a signature string based on Signing Mechanism. After receiving a request, the Huawei server verifies the signature string. Subsequent processing can be performed only after the signature verification is successful. Otherwise, an error code is returned. All body parameters except sign and method in the request are used for signing.

The value contains a maximum of 1,024 characters.

Request Example

POST /gameservice/api/gbClientApi HTTP/1.1
Host: jos-open-api.cloud.huawei.com
Content-Type: application/x-www-form-urlencoded
// The values of all request parameters must be URL-encoded before being concatenated.
method=external.hms.gs.player.unbindPlayer&appId=135***568&cpId=123***21f&teamPlayerId=******&ts=1670841860308&sign=**************

Response Parameters

Parameter Mandatory Type Description
rtnCode Yes int

Code returned by the server.

-1: Response failed. This is usually caused by an unknown error.

0: Disassociation succeeded.

1: Signature verification failed. This is usually caused by inconsistent signatures.

3001: Invalid parameter. A request parameter is missing or the format is incorrect.

2031002: The player account information is incorrect.

2031006: The game information is incorrect. No game information is found.

2031007: The Huawei player account has been associated with another game player account.
errMsg No String Error message.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "rtnCode":0
}

Signing Mechanism

To ensure HTTPS transmission security and prevent request parameters from being tampered with, an app must include a signature string of the request parameters for calling the API. The signature string is used by the Huawei server to verify the request parameters. The rules for generating a signature string are as follows:

  1. Sort the parameters except sign and method in the request body in ascending order according to the ASCII codes of the initial letters of their names. If the initial letters of two parameters are the same, their second letters will be used for sorting, and so on.

    The parameters sign and method are not used for signing.

  2. Add dependencies.

    <dependencies>
       <dependency>
            <groupId>commons-codec</groupId>
            <artifactId>commons-codec</artifactId>
            <version>1.15</version> <!--Use the latest stable version.-->
        </dependency>
        <dependency>
            <groupId>org.bouncycastle</groupId>
            <artifactId>bcprov-jdk18on</artifactId>
            <version>1.74</version> <!--Use the latest stable version.-->
        </dependency>
</dependencies>

  3. Use ampersands (&) toconcatenate the key-value pairs of all parameter names and values involved in signing to a character string to be signed, for example, a=xxxxxx&b=xxxxxxx&c=xxxxxxxxxxx.... The parameter values need to be URL-encoded.

    The Java sample code is as follows:

    // Assemble parameters except sign and method in the body. The parameter values here are only examples.
Map<String, String> paramsMap = new HashMap<>();
paramsMap.put("appId", "135***568");
paramsMap.put("cpId", "123***21f");
paramsMap.put("teamPlayerId", "E5B***E9B");
paramsMap.put("ts", 123456L);

// Sort the parameters in alphabetical order.
Map<String, String> tempMap = new TreeMap<>(paramsMap);
StringBuffer base = new StringBuffer();

// Concatenate parameters.
for (Map.Entry<String, String> entry : tempMap.entrySet()) {
    String key = entry.getKey();
    String value = entry.getValue();
    base.append(key).append('=').append(null == value ? '' : URLEncoder.encode(value, "UTF-8")).append('&');
}

if (base.length() > 0) {
    base.deleteCharAt(base.length() - 1);
}

  4. Use the game private key to sign the generated string, applying the RSA algorithm (SHA256WithRSA/PSS). Use Base64 to encode the signed string. The obtained string is the signature string.

    • For details about how to obtain the private key of a game, please refer to Obtaining the Game Key.

    • The signature string needs to be URL-encoded before being added to the request.

    The Java sample code is as follows:

    // Obtain the private key for signing. The implementation method is determined by yourself. The following is only an example.
String privateKey = "xxxxxx";

// Add a signature.
byte[] keyBytes = Base64.decodeBase64(privateKey);
PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(keyBytes);
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
PrivateKey privateK =  keyFactory.generatePrivate(pkcs8KeySpec);
Signature signature = Signature.getInstance("SHA256withRSA/PSS", new BouncyCastleProvider());
signature.initSign(privateK);
signature.update(base.getBytes(StandardCharsets.UTF_8));
String sign =  Base64.encodeBase64String(signature.sign());