OK: Подписка на события игр и приложений через Webhook

Платформа Одноклассники (OK) обновила документацию OK Games Widgets API, добавив подробное описание функционала подписки на события для игр и приложений. Теперь сервисы могут получать актуальные данные о действиях пользователей в OK в реальном времени, используя Webhook. Это специальный URL, на который платформа отправляет HTTP POSTзапросы с информацией о событиях.

Альтернативный способ получения событий — через events.updates в long polling API.

Как настроить подписку на события

Настройка Webhook осуществляется в параметрах приложения, в разделе Event Subscription Settings.

Для успешной отправки событий необходимо выполнить следующие шаги:

1. Указать Webhook Link: Введите адрес вашего сервиса, который будет принимать запросы с событиями.

2. Пройти подтверждение Webhook: Сервис должен быть готов принять специальный проверочный запрос от OK.

3. Сформировать список событий: Выберите, на какие именно события должна приходить информация.

4. Сохранить настройки: Примените изменения в параметрах вашего приложения.

После выполнения этих действий, выбранные события начнут поступать на указанный Webhook в течение нескольких минут.

Подтверждение Webhook

Чтобы OK мог безопасно отправлять сообщения о событиях, Webhook должен быть подтвержден. Это гарантирует, что указанный URL действителен и готов к приему данных.

Процесс подтверждения:

Введите адрес вашего сервиса в поле Webhook Link.

Убедитесь, что ваш Webhook готов к приему проверочного запроса.

Нажмите кнопку "Confirm" для запуска процесса проверки.

Важные моменты при обработке проверочного запроса:

CORS: Ваш Webhook не должен блокироваться изза политики CORS. Разрешите прием запросов с домена nap.okapps.ru.

Заголовки: При запросах с nap.okapps.ru отправляйте заголовки AccessControlAllowOrigin и AccessControlAllowHeaders.

Структура проверочного запроса:

Метод: POST request

ContentType: application/json

Тело запроса: {"webhookType": "CONFIRMATION"}

Ожидаемый ответ от вашего сервиса:

Код ответа: 200

ContentType: application/html или application/text

Тело ответа: Строка, указанная в настройках вашего приложения.

Получение сообщений о событиях

Когда в OK происходит событие, на которое подписана ваша игра или приложение, платформа отправляет HTTP POSTзапрос на указанный Webhook.

Параметры запросов от OK:

UserAgent: OK/1.0 Webhook API

Тело запроса: Зависит от типа события (см. ниже).

Важно: Ваш сервис должен вернуть код ответа 200. Это подтверждает успешную обработку запроса и обеспечивает стабильность доставки уведомлений. Если сервис не отвечает кодом 200, OK не получит подтверждение, и доставка может быть нарушена.

Доступные типы событий

Тело запроса, получаемого Webhook, зависит от типа события. На данный момент доступны следующие типы:

События группы:

Вступление пользователя в группу.

Выход пользователя из группы.

Разрешение пользователем отправки сообщений от группы.

Запрет пользователем отправки сообщений от группы.

События приложения:

Добавление пользователем отзыва к игре.

Все события, связанные с группами, обрабатываются только для официальных групп игр или приложений. Чтобы связать группу с игрой или приложением, используйте поле "Official group" в настройках приложения.

Вступление и выход из группы

Когда пользователь вступает в группу:

```json

{

"type": "JOIN",

"timestamp": 1618250409915,

"userId": "user:1234567890",

"userName": "Имя Фамилия",

"groupId": "group:1234567890123456",

"webhookType": "GROUP"

}

```

Когда пользователь выходит из группы:

"type": "LEAVE",

Примечание: timestamp 1618250409915 соответствует 12 апреля 2021 года, 18:00:09.915 UTC.

Управление сообщениями от группы

Когда пользователь включает сообщения от группы:

"type": "MESSAGESON",

Когда пользователь отключает сообщения от группы:

"type": "MESSAGESOFF",

Отзывы об игре

Когда пользователь добавляет отзыв к игре:

"prevComment": "",

"webhookType": "APP",

"prevRating": 0,

"appId": "app:123123123",

"type": "RATINGCOMMENT",

"timestamp": 1691947736017,

"rating": 5,

"comment": "Отличная игра!",

"userId": "user:123123123"

Примечание: timestamp 1691947736017 соответствует 13 августа 2023 года, 17:28:56.017 UTC.

Требования для включения функции

Для использования подписки на события через Webhook необходимы:

Официальная группа в OK.

Приложение или игра в OK.

Группа должна быть связана с игрой или приложением как официальная группа.

Подробнее о настройках можно узнать в документации OK Games Widgets API.

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

Риск: изменение контракта может потребовать правок в интеграции, генерации типов или пользовательских сценариях.