Receiving authorization from Game Center app

To begin playing a client-based game, the user must create or register an existing Mail.ru account on the game site, log into the Mail.ru Game Center with this account, download the game, and click Play.

Game Center (labeled below as "@Mail.Ru Launcher") will launch the game client with the following command line parameters:

game_client.exe --sz_pers_id=[uid] --sz_token=[OTP hash]

The names of the parameters --sz_pers_id= and --sz_token= can be modified at the game developers' request.

The game client is responsible for transferring the parameters received from Game Center to the game's server. The game server must then verify the parameters via the server-to-server protocol described below.

Game server protocol description

The game server and GAS communicate via HTTP. Calling a method to verify authorization must be done only once by the game server. The second and subsequent calls with the same hash parameter will cause an error.

GET, https://games.mail.ru/app/[GMRID]/gas?uid=[int uid]&hash=[string hash]&ip=[string ip]&sign=[md5 sign]

Main parameters:

https://games.mail.ru/app/[GMRID] - the URL to which requests are sent

  • [GMRID] - the unique game identifier (which can be found in the developer dashboard in the "System Properties" tab.)
  • <uid> - the ID of the user, received from "@Mail.Ru Launcher";
  • <uid> - the OTP hash received from "@Mail.Ru Launcher";
  • <ip> - the user's IPv4 address, in the format 'xxx.xxx.xxx.xxx';
  • sign - a unique digital signature. Calculation of the signature must include all POST parameters passed by the request as well as the appid=[GMRID] parameterMore about calculating signatures. Help calculating signatures is available from the signature calculator.

The server sends a response in JSON format with utf-8 encoding.

If the request is processed successfully, the following response will be returned:

{
    "status": "ok"
}

Possible errors include:

// Incorrect signature
{"status": "error", "errcode": 0, "errmsg": "gas_invalid_sign"}

// User not found
{"status": "error", "errcode": 0, "errmsg": "gas_invalid_user"}

// Invalid hash parameter
{"status": "error", "errcode": 10, "errmsg": "gas_otp_error"}

// Access is restricted to whitelist
{"status": "error", "errcode": 20, "errmsg": "gas_whitelist_error"}

// Access is restricted to whitelist
{"status": "error", "errcode": 30, "errmsg": "gas_whitelist_uid_error"}

// User is banned
{"status": "error", "errcode": 40, "errmsg": "Время бана с '' до ''"}

// User has not paid for this game (for P2P games)
{"status": "error", "errcode": 50, "errmsg": "gas_no_payment"}

Interaction Scheme

Objects:

  • @Mail.Ru Launcher - the Game Center client, which the user uses to download the game;
  • GAS - Game Authorization Service - the Platform's authorization system.

1. The user enters an email and password into the "@Mail.Ru Launcher" (Game Center).

2. "@Mail.Ru Launcher" obtains a one-time token (OTP hash) for the user's ID from Mail.ru.

3. "@Mail.Ru Launcher" sends the ID/OTP hash to the game client.

4. The game client sends the ID/OTP hash to the game server.

5. The game server sends the ID/OTP hash to the system (GAS).

6. GAS verifies the OTP hash, checks the user's status (whether banned or not), registers the user's login, and returns a response containing the user's ID and authentication status.

Depending on the response code received, the game server instructs the game client to either let the user into the game or to inform the user of the error that has occurred.

An example game client and game server implementation authorization via Game Center can be found in this archive.