Отправка сообщений и нотификаций

Платформа Mail.ru предоставляет возможность отправлять письма и нотификации пользователю партерской игры. Письма отправляются на почту Mail.Ru которую использует пользователь для авторизации в игре. Нотификации отображаются на сайте https://games.mail.ru/ и на рабочем столе пользователя в случае если установлен Игровой Центр.

Отправка сообщения

  1. Формат ответов API - json.
  2. Протокол передачи данных - https.
  3. Запросы должны происходить только между серверами Партнера и Mail.ru.

Формат запроса:

# Отправка нотификации
POST https://games.mail.ru/app/[GMRID]/send/notification

# Отправка письма
POST https://games.mail.ru/app/[GMRID]/send/email

Основные POST-параметры:

  • <uid> - id пользователя (при регистрации сообщается партнеру)
  • <template> - шаблон сообщения, подробнее в разделе "Шаблоны сообщений"
  • <template_param> - json-объект с параметрами, которые будут подставлятся в шаблон, необязательный параметр
  • <sign> - уникальная цифровая подпись

Подсчет подписи

Для того чтобы сформировать подпись запроса отправки (параметр sign) необходимо:

1. Взять все POST-параметры, которые будут отправлены в запросе (за исключением sign, так как он еще не вычислен):

  • <uid> - 596343600
  • <template> - greetings
  • <template_param> - {}

2. Сортируем параметры по ключам

{
    "template": "greetings",
    "template_param": "{}",
    "uid": "596343600"
}

3. Склеиваем ключ-значение в строку

$str = "template=greetingstemplate_param={}uid=596343600"

4. Генерируем подпись

$sign = md5($str . $secret)

$secret - уникальный ключ игры. Партнер может узнать его в кабинете разработчика, на странице игры, на вкладке "Системные свойства". Поле "Секрет для api.games.mail.ru".

5. Добавляет параметр sign в запрос.

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

Успешно:

{
    "status": "ok"
}

Ошибки:

# Пользователь не найден
{"status": "error", "errcode': 1003, "errmsg": "user not found"}

# Неправильная подпись запроса
{"status": "error", "errcode': 5001, "errmsg": "invalid sign"}

# Превышен лимит по отправке сообщений
{"status": "error", "errcode': 7001, "errmsg": "send limit exceeded"}

# Неправильный шаблон для отправки
{"status": "error", "errcode': 7002, "errmsg": "invalid template"}

# Неправильный параметра шаблона
{"status": "error", "errcode': 7003, "errmsg": "invalid template param"}

# Ошибка отправки сообщения
{"status": "error", "errcode': 7004, "errmsg": "can't send to user"}

# Юзер не имеет email на который можно отправить письмо (социальная авторизация)
{"status": "error", "errcode': 7005, "errmsg": "user has no email"}
  • “errcode" - внутренний код ошибки
  • "errmsg" - описание кода ошибки

Ограничений сообщениям:

  1. Количество писем отправляемых партнером в сутки ограничено DAU за предыдущий день.
  2. Количество нотификаций отправляемых партнером в сутки ограничено DAU за предыдущий день.
  3. Сообщения не могут содержать произвольный текст. Отправка осущетсвляется по созданым заранее шаблонам в которые можно подставлять параметры. Подробнее в разделе "Шаблоны сообщений".

Шаблоны сообщений

1. Приветствие

Спасибо за регистрацию
Мы очень рады что вы зарегистрировались в игре {{game_name}}
  • Значение template - greetings
  • Обязательные параметры в template_param - отсутствуют
  • Необязательные параметры в template_param - отсутствуют
  • Автоматические параметры - game_name