Connecting the JS API

Game page

  1. The Mail.Ru platform displays the partner’s game on the page https://games.mail.ru/app/[GMRID]. All users will be directed to this page. The GMRID parameter value can be found in the developer area in the "System properties" tab.
  2. The partner prepares an iFrame URL that will be loaded into the game’s page from paragraph 1 through iFrame. The game will not work correctly outside of iFrame.
  3. The iFrame URL must be set in the developer area in the "General properties" tab, in the field "Link to page for display in iFrame." The URL must contain https within it.
  4. After the iFrame URL is set, the game developer’s content will be shown on the page https://games.mail.ru/app/[GMRID]. This page is the game’s main entry and registration point.
  5. When an authorized and registered opens the partner iFrame URL on the landing page https://games.mail.ru/app/[GMRID] , the platform will add 3 parameters to verify the user's authenticity https://partner.com/game.php?sign=xxxxxxxxx&uid=xxxxx&appid=xxxx .
  6. For projects in which it is necessary to get all parameters from the original page queryhttps://games.mail.ru/app/[GMRID]?param1=1&param2=2 , it is possible to enable pass-through GET parameters in the partner iFrame URL. Only unique parameters are passed through, so if two parameters have the same designation, only one will go through. sign, uid, and appid parameters are always replaced with parameters that are counted by the platform. To enable this behavior, contact Platform staff.
  7. The Mail.Ru platform offers a JS API that provides the following possibilities:register a user

▪ get authorization status
▪ request authorization window
▪ request user info
▪ request payment window
▪ request payment frame URL (mainly used embedded in the game)
▪ request authorization token
▪ get information about a user's profile.

Interaction with the JS API is done based on postmessage, with the following browser limitations: http://caniuse.com/#feat=x-doc-messaging.

Integration with the JS API

  1. You must refer to the JS file:
<script type="text/javascript" src="//games.mail.ru/app/[GMRID]/static/mailru.core.js"></script>

      2. Enter the following code before </body>:

<script>
    (function apiHandshake(iframeApi) {
        if (typeof iframeApi === 'undefined') {
            console.log('Cannot find iframeApi function, are we inside an iframe?');
            return;
        }

        var externalApi = null;

        var callbacks = {
            appid: [APPID],

            getLoginStatusCallback: function(status) {},
            userInfoCallback: function(info) {},
            registerUserCallback: function(info) {},
            paymentFrameUrlCallback: function(url) {},
            getAuthTokenCallback: function(token) {},
            paymentReceivedCallback: function(data) {}
        };

        function error(err) {
            throw new Error('Could not init external api ' + err);
        }

        function connected(api) {
            externalApi = api;
        }

        // example of calling "Register" function
        $('#register').on('click', function(e) {
            e.preventDefault();
            externalApi.registerUser();
        });

        // example of calling "Auth" function
        $('#auth').on('click', function(e) {
            e.preventDefault();
            externalApi.authUser();
        });

        iframeApi(callbacks).then(connected, error);
    }(window.iframeApi));
</script>

JS API methods and callbacks

  1. getLoginStatus

Gets the current login status of the user. After this request is made, the platform calls getLoginStatusCallback(object status) in the partner page API.

Response format:

Successful:

{
    "status": "ok",
    "loginStatus": "[0,1,2,3]"
}

where Int loginStatus is:

0 - user not authorized
1 - user authorized, not registered
2 - user authorized, registered
3 - user authorized, registered and purchased game (for P2P games)

Error:

{
    "status": "error",
    "errcode": "[int errcode]",
    "errmsg": "[string errmsg]"
}

"errcode": "[int errcode]" - partner’s internal error code

"errmsg": "[string errmsg]" - partner’s error code description.

      2. userInfo

Get information about the user After this request is made, the platform calls userInfoCallback(object status), in the partner page API.

Response format:

Successful:

{
    "status": "ok",
    "uid": "[int uid]",
    "hash": "[md5 hash]"
}

where: 

    int uid - the user’s ID on the platform

    md5 hash - an md5 hash of the user’s email address

Error:

{
    "status": "error",
    "errcode": "[int errcode]",
    "errmsg": "[string errmsg]"
}

"errcode": "[int errcode]" - partner’s internal error code

"errmsg": "[string errmsg]" - partner’s error code description.

     3.1 registerUser

Register a user. Calling this method creates an EULA confirmation window. If the user agrees, the platform creates a registration query and calls the method registerUserCallback(object info), in the partner page API. The format of the info object is identical to the userInfo object.

     3.2 registerUserNoConfirm

Similar to registerUser, but without agreement to EULA. Always after calling registerUser, the method registerUserCallback(object info) is called. The moment the developer finds it appropriate to show EULA acceptance, the developer should call the method userConfirm.

     4. authUser

Authorize a user. Calling this method creates an authorization window. After authorization, the page will be refreshed, and then the user’s status and information can be obtained.

    5. paymentFrame(object args)

Call a payment frame. Call parameters:

paymentFrame({
  'merchant_param':{
     'amount': 100,       // mandatory parameter (rubles)
     'description': 100,  // mandatory parameter (description of services received etc.)
     'any_other_param1': 'any_other_param_value1', // additional parameters, returned in payment notification
      ...
     'any_other_paramN': 'any_other_param_valueN'
  }
});

Important note:

  • The merchant_param.amount parameter must be in rubles.
  • In merchant_param various parameters can be set, as shown in the listing above. The entire merchant_param block will be returned in a notification when payment information is sent.

Examples of combining parameters:

a) purchase of an in-game item for 100 rubles:

paymentFrame({
  "merchant_param": {
    "amount": 100,                   // price of goods in rubles
    "description": "Золотой сундук", // product description in payment form (eg Gold Chest)
    "item_id": "776",                // product order identifier
    "additional_param": 1            // additional parameter
  }
});

b) purchase of game currency for 100 rubles:

paymentFrame({
  "merchant_param": {
    "amount": 100,                          // price of currency in rubles
    "description": "200 золотых кристалов", // description of currency in payment form (eg 200 gold crystals)
    "item_id": "777",                       // product ID
    "additional_param": 2                   // additional parameter
  }
});

6. PaymentFrameUrl(object args)

This method is identical to p. 5 "paymentFrame(object args)", but instead of a popup, it returns a link to the payment frame.

Link example:

https://pw.money.mail.ru/pw/2-02-01/?merchant_id=530585&data=eyJzY2VuYXJpbyI6Iml0ZW0iLCJtZXJjaGFudF9wYXJhbSI6eyJhbW91bnQiOiIyMDAiLCJkZXNjcmlwdGlvbiI6Ilx1MDQxN1x1MDQzZVx1MDQzYlx1MDQzZVx1MDQ0Mlx1MDQzZVx1MDQzOSBcdTA0NDFcdTA0NDNcdTA0M2RcdTA0MzRcdTA0NDNcdTA0M2EgKFx1MDQ0N1x1MDQzNVx1MDQ0MFx1MDQzNVx1MDQzNyBwYXltZW50RnJhbWVVcmwpIn0sImlzc3Vlcl9pZCI6ImRiY2I2NWY5LTFiYjctNDRlMC04MTgzLWFlMTc3YTc0ZjU5NCIsInRzIjoxNDY2MDY3MjU0LCJ1c2VyX2luZm8iOnsidXNlcl9pZCI6ImQudG9rYXJldkBjb3JwLm1haWwucnUiLCJidXllcl9pcCI6IjE4NS42LjI0NS4xMzQiLCJ1c2VyX3ZlcmlmaWVkIjoxfSwiZGVzY3JpcHRpb24iOiJcdTA0MTdcdTA0M2VcdTA0M2JcdTA0M2VcdTA0NDJcdTA0M2VcdTA0MzkgXHUwNDQxXHUwNDQzXHUwNDNkXHUwNDM0XHUwNDQzXHUwNDNhIChcdTA0NDdcdTA0MzVcdTA0NDBcdTA0MzVcdTA0MzcgcGF5bWVudEZyYW1lVXJsKSIsImFtb3VudCI6IjIwMCIsImN1cnJlbmN5IjoiUlVCIn0%3D&signature=e5726738a7b622059bffb9165ed5c25f6c5163d5

7. paymentReceivedCallback(data)

After payment is successfully made, the callback paymentReceivedCallback will be called. "Data" will contain only information about the user.

{
    "uid": "[int uid]"
}

8. paymentWindowClosedCallback()

If the payment window was closed (by the user or automatically upon payment), then the callback paymentWindowClosedCallback will be called. There is no data parameter.

9. confirmWindowClosedCallback()

If the rules confirmation window was closed upon registration or after calling userConfirm without confirming the rules, then the callback confirmWindowClosedCallback will be called. There is no data parameter.

10. getAuthToken()

Get an authorization token for the current authorized user. The platform makes a request to get a token and calls the getAuthTokenCallback(object token) method in the partner page API.

Response format:

Successful:

{
    "status":"ok",
    "uid":"[int uid]",
    "hash":"[string hash]"
}

where: 

    int uid - the user’s ID on the platform

    string hash - the authorization token.

Error:

{
    "status": "error",
    "errcode": "[int errcode]",
    "errmsg": "[string errmsg]"
}

The resulting token (hash) must be checked with a server-server request (see description of GAS).

11. userProfile

Get an infomation about user frofile. After this request is made, the platform calls userProfileCallback(object status.

Response format:

{
    "status": "ok",
    "uid": "[int uid]",
    "nick": "[str nick]",
    "avatar": "[url avatar]",
    "birthyear": "[str birthyear]",
    "sex": "[str male or female]",
    "slug": "[str unique user identificator]"
}

To demonstrate the capabilities of the JS API, a test application is available. This application’s code can be found in the repository.

12. User friends

Getting a list of the user's friends After this request is made, the platform calls userFriendsCallback()

Response format:

Successful:

{
    "status": "ok",
    "friends": [
        {
            "uid": [int uid],
            "nick": "[str nick]",
            "slug": "[str unique user identificator]",
            "avatar": "[url avatar]"
        },
        ...
    ]
}

Error:

{
    "status": "error",
    "errcode": "[int errcode]",
    "errmsg": "[string errmsg]"
}

13. userConfirmCheck

This method is used to verify EULA confirmation. After this request is made, the platform calls userConfirmCheckCallback()

Response format:

Successful:

{
    "status": "ok",
    "confirm": true
}

14. userConfirm

Calling this method creates an EULA confirmation window. If the user agrees, the platform saves the user's agreement to the EULA. After saving the agreement, the platform calls userConfirmCallback(). This is used in conjunction with registerUserNoConfirm.

Response format:

Successful:

{
    "status": "ok"
}

Error:

{
    "status": "error",
    "errcode": "[int errcode]",
    "errmsg": "[string errmsg]"
}

15. userSocialFriends

Getting a list of the user's friends. Since this method is not tied to the project, it is called without indicating the GMRID. After this request is made, the platform calls userSocialFriendsCallback()

Response format:

Successful:

{
    "status": "ok",
    "friends": [{
         "nick": "NICK",
         "online": 0,
         "slug": ".....",
         "avatar": "https://filin.mail.ru/pic?d=-0....."
    }]
}

Error:

{
    "status": "error",
    "errcode": "[int errcode]",
    "errmsg": "[string errmsg]"
}