Подключение JS API

Страница игры

  1. Платформа Mail.ru отображает игру партнера на странице https://games.mail.ru/app/[GMRID]. Все пользователи будут направлены на эту страницу. Значение параметра GMRID игры можно найти в кабинете разработчика на вкладке "Системные свойства".
  2. Партнер подготавливает iFrame URL, который будет загружаться на странице игры из пункта 1 через iFrame. Вне iFrame корректная работа игры невозможна.
  3. iFrame URL необходимо указать в кабинете разработчика на вкладке "Основные свойства" в поле "Ссылка на страницу для отображения в iFrame". URL должен содержать в схеме протокол https. 
  4. После того как указан iFrame URL контент разработчика игры начинает отображаться на странице https://games.mail.ru/app/[GMRID]. Эта страница  является основной точкой входа и точкой регистрации в игре.
  5. При открыти iFrame URL партнера на лендинге https://games.mail.ru/app/[GMRID] авторизованным и зарегистрированым пользователем платформа будет добавлять 3 параметра для проверки подлиности пользователя https://partner.com/game.php?sign=xxxxxxxxx&uid=xxxxx&appid=xxxx. В качестве значения appid используется четырехзначный идентификатор проекта GMRID
  6. Для проектов которым необходимо получать все параметры из оригинального запроса к странице https://games.mail.ru/app/[GMRID]?param1=1&param2=2 есть возможность включить проброс GET параметров в iFrame URL партнера. Пробрасываются только уникальные параметры, то есть из двух параметров с одинаковым называнием прийдет только один. Параметры sign, uid и appid всегда заменяются на параметры которые подсчитывает платформа. Для включения этого поведения обратитесь к сотрудникам Платформы.
  7. Платформа Mail.ru предлагает JS API, который предоставляет следующие возможности:

          a) зарегистрировать пользователя;

          b) получить статус авторизации;

          c) запросить окно авторизации;

          d) запросить информацию о пользователе;

          e) запросить окно оплаты;

          f) запросить url фрейма оплаты (в основном используется для встраивания в игру);

          g) запросить токен авторизации;

          h) получить информацию о профиле пользователя.

Взаимодействие с JS API осуществляется на базе postmessage, ограничения на браузеры: http://caniuse.com/#feat=x-doc-messaging.

Интеграция с JS API

  1. Необходимо подключить js файл:
<script type="text/javascript" src="//games.mail.ru/app/[GMRID]/static/mailru.core.js"></script>

      2. Вставить перед </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: [GMRID],

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

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

        function connected(api) {
            externalApi = api;
        }

        // пример вызова действия "Регистрация"
        $('#register').on('click', function(e) {
            e.preventDefault();
            externalApi.registerUser();
        });

        // пример вызова действия "Вход"
        $('#auth').on('click', function(e) {
            e.preventDefault();
            externalApi.authUser();
        });

        // пример получения профиля
        $('#profile').on('click', function(e) {
            e.preventDefault();
            externalApi.userProfile();
        });

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

JS API методы и колбеки

  1. getLoginStatus

Получение текущего статуса авторизации пользователя. После выполнения запроса платформа вызывает getLoginStatusCallback(object status), в api на странице партнера.

Формат ответа:

Успешно:

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

где Int loginStatus:

    0 - пользователь не авторизован;

    1 - пользователь авторизован, не зарегистрирован;

    2 - пользователь авторизован, зарегистрирован;

    3  - пользователь авторизован, зарегистрирован, и совершил покупку игры (для P2P игр).

Ошибка:

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

“errcode": "[int errcode]" - внутренний код ошибки партнера;

"errmsg": "[string errmsg]" - описание кода ошибки партнера.

      2. userInfo

Получение информации о пользователе. После выполнения запроса платформа вызывает userInfoCallback(object status), в api на странице партнера.

Формат ответа:

Успешно:

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

где: 

    int uid - id пользователя в платформе;

    md5 hash -  md5 hash от почты пользователя.

Ошибка:

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

“errcode": "[int errcode]" - внутренний код ошибки партнера;

"errmsg": "[string errmsg]" - описание кода ошибки партнера.

     3.1 registerUser

Регистрация пользователя. При вызове метода появляется окно с подтверждением EULA. Если пользователь согласился, платформа выполняет запрос на регистрацию и вызывает метод registerUserCallback(object info), в api на странице партнера. Формат объекта info аналогичен userInfo.

     3.2. registerUserNoConfirm

Аналогично registerUser, но без согласия с EULA. Всегда после вызова registerUser происходит вызов метод registerUserCallback(object info). В момент когда разработчик считает уместным показать принятие EULA и разработчик должен вызвать метод userConfirm.

     4. authUser

Авторизация пользователя. При вызове метода появляется окно авторизации. После авторизации страница будет перезагружена, далее можно получить статус и информацию пользователя.

    5. paymentFrame(object args)

Вызов платежного фрейма. Параметры вызова:

paymentFrame({
  'merchant_param':{
     'amount': 100,       // обязательный параметр (рубли)
     'description': 100,  // обязательный параметр, описание получаемой услуги и т.д.
     'any_other_param1': 'any_other_param_value1', // доп. параметры, возвращаются в (уведомление о платеже)
      ...
     'any_other_paramN': 'any_other_param_valueN'
  }
});

Важное примечание:

  • Параметр merchant_param.amount указывается в рублях.
  • В merchant_param можно указывать различные параметры как показано в листинге выше. Весь блок merchant_param вернется в уведомлении при передаче информации о платеже.

Примеры комбинации параметров:

a) покупка игрового предмета за 100 рублей:

paymentFrame({
  "merchant_param": {
    "amount": 100,                   // цена товара в рублях
    "description": "Золотой сундук", // описание товара в форме оплаты
    "item_id": "776",                // идентификатор заказа товара
    "additional_param": 1            // дополнительный параметр
  }
});

b) покупка игровой валюты на 100 рублей:

paymentFrame({
  "merchant_param": {
    "amount": 100,                          // цена валюты в рублях
    "description": "200 золотых кристалов", // описание валюты в форме оплаты
    "item_id": "777",                       // идентификатор товара
    "additional_param": 2                   // дополнительный параметр
  }
});

6. PaymentFrameUrl(object args)

Метод аналогичен п. 5 "paymentFrame(object args)", но вместо popup вернёт ссылку на платежный фрейм.

Пример ссылки:

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

7. paymentReceivedCallback(data)

После того как платеж был успешно проведен, будет вызван колбек paymentReceivedCallback. При этом в data будет содержаться только информация о пользователе.

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

8. paymentWindowClosedCallback()

Если платежное окно было закрыто (пользователем или автоматически по приходу платежа), то будет вызван колбек paymentWindowClosedCallback. Параметр data отсутствует.

9. confirmWindowClosedCallback()

Если окно подтверждения правил при регистрации или после вызова userConfirm было закрыто без подтверждения правил, то будет вызван колбек confirmWindowClosedCallback. Параметр data отсутствует.

10. getAuthToken()

Получение токена авторизации для текущего авторизованного пользователя. Платформа выполняет запрос на получение токена и вызывает метод getAuthTokenCallback(object token), в api на странице партнера.

Формат ответа:

Успешно:

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

где: 

    int uid - id пользователя в платформе;

    string hash - авторизационный токен.

Ошибка:

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

Полученный токен (hash) необходимо проверить server-server запросом (см. описание GAS).

11. userProfile

Получение информации о профиле пользователя. После выполнения запроса платформа вызывает userProfileCallback(object status.

Формат ответа:

Успешно:

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

Для демонстраниции возможностей JS API существует тестовое приложение. Код этого приложения можно найти в репозитории.

12. userFriends

Получение списка друзей пользователя в проекте. После выполнения запроса платформа вызывает userFriendsCallback()

Формат ответа:

Успешно:

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

 

Ошибка:

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

13. userConfirmCheck

Метод используется для проверки подтверждения EULA. После выполнения запроса платформа вызывает userConfirmCheckCallback()

Формат ответа:

Успешно:

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

14. userConfirm

При вызове метода появляется окно с подтверждением EULA. Если пользователь согласился, платформа cохраняет согласие пользователя с EULA. После cохранения согласия платформа вызывает userConfirmCallback(). Используется совместно с registerUserNoConfirm.

Формат ответа:

Успешно:

{
    "status": "ok"
}

 

Ошибка:

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

14. userSocialFriends

Получение списка друзей пользователя. Т.к метод не привязан к проекту, то вызывается без указания GMRID. После выполнения запроса платформа вызывает userSocialFriendsCallback()

Формат ответа:

Успешно:

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

 

Ошибка:

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