Push-уведомления

Как это работает

В Web Shop можно настроить push-уведомления — персональные или массовые сообщения, которые пользователи получают прямо в браузере. Push-уведомления позволяют сообщать пользователям о новых товарах, акциях и специальных предложениях.

Чтобы отправить пользователю уведомление — например, после поражения в бою или при нехватке ресурсов, на стороне сервера игры вызовите метод API Xsolla для отправки уведомлений.

После нажатия на уведомление пользователь переходит в Web Shop, где может приобрести необходимые товары.

Push-уведомления настраиваются в конструкторе сайтов Xsolla и работают только для опубликованных Web Shop.

Xsolla не отслеживает игровые события. Вы можете сами определить моменты, в которые сервер игры вызывает метод API для отправки уведомления, например:

Сценарий взаимодействия

1. Пользователь открывает Web Shop в браузере или через установленное PWA и видит баннер с предложением подписаться на уведомления.
2. Пользователь нажимает Подписаться и разрешает отправку уведомлений в системном окне браузера.

    flowchart LR
      A[User opens Web Shop] --> B{Permission already granted?}
      B -- Yes --> C[Automatic subscription]
      B -- No --> D{Can the browser show the system prompt?}
      D -- Yes --> E[System prompt]
      D -- No --> F[Subscribe banner]
      F --> E
      E -- Allow --> G[Subscribed]
      E -- Block --> H[Not subscribed]
  

3. Web Shop регистрирует пользователя как подписчика в системе Xsolla. Подписка привязывается к браузеру или установленному PWA на устройстве пользователя. От статуса авторизации зависит, какие уведомления можно отправлять пользователю:

   • если пользователь авторизован в Web Shop, с подпиской связывается его ID — такому пользователю можно отправлять персональные уведомления;
   • если пользователь не авторизован, ему можно отправлять только массовые уведомления; после авторизации подписка автоматически связывается с ID пользователя.

4. Сервер игры вызывает метод API Xsolla для отправки уведомлений.

5. Пользователь получает push-уведомление.

6. Пользователь нажимает на уведомление и переходит в Web Shop — на страницу из параметра data.url или на главную страницу, если параметр не передан. Если у пользователя есть активная сессия в Web Shop, он остается авторизованным.

  sequenceDiagram
    participant U as User
    participant WS as Web Shop
    participant G as Game
    participant X as Xsolla
    note over U,X: Subscription
    U->>WS: Opens the site / PWA
    WS->>U: Displays the subscription banner
    U->>WS: Subscribes and allows notifications
    WS->>X: Registers the subscriber (User ID, browser / PWA)
    X-->>WS: Confirms the subscription
    note over U,X: Sending a notification
    G->>X: Calls POST /messages/push/send
    X-->>G: Returns message_id
    X->>U: Sends the push notification
    U->>WS: Clicks the notification, follows data.url
    WS->>U: Displays store offers

Как настроить

3. Перейдите в раздел Push notifications.
4. Активируйте переключатель Enable notifications.
5. Скопируйте значения из полей Application ID, Client ID и Client secret key — они понадобятся для отправки запросов API с сервера игры. Параметры создаются один раз при первой активации переключателя Enable notifications и используются для всего проекта: если в проекте несколько сайтов, для всех используются одни и те же значения.
6. При необходимости настройте баннер подписки: измените заголовок, описание, иконку и текст кнопки.
7. Чтобы сайт сам запрашивал у пользователя разрешение на отправку push-уведомлений при открытии, активируйте переключатель Auto-request permission (опционально). Если переключатель неактивен, разрешение запрашивается только после нажатия пользователем кнопки Подписаться.
8. Чтобы применить изменения, опубликуйте сайт.

9. На сервере игры реализуйте логику отправки push-уведомлений. Сервер игры должен вызвать метод API для отправки уведомлений и передать в запросе ID пользователя.

Отправка уведомлений

Xsolla не отправляет уведомления автоматически — инициатором отправки всегда выступает ваш проект. Вызывайте соответствующий метод API в момент, когда нужно уведомить пользователей (например, при старте акции, обновлении статуса заказа и т.д.).

Базовый URL: https://messaging-platform.xsolla.com

Аутентификация

Запросы аутентифицируются по протоколу OAuth 2.0. Получите серверный JWT с помощью метода Generate JWT, передав параметры:

• grant_type — тип получения JWT, передайте значение client_credentials;
• client_id — значение поля Client ID из настроек раздела Push notifications;
• client_secret — значение поля Client secret key из настроек раздела Push notifications.

Полученный токен передается в заголовке Authorization: Bearer <token>.

Отправка уведомления пользователю

Отправляет персональное push-уведомление пользователю по его ID. Уведомление доставляется во все браузеры и установленные PWA, где пользователь подписался на уведомления.

HTTP-запрос

POST https://messaging-platform.xsolla.com/api/v1/messages/push/send

Заголовки запроса

Параметры запроса

Параметры ответа

Пример запроса

 1{
 2  "notification_type": "user_validation",
 3  "settings": {
 4    "project_id": 123456,
 5    "merchant_id": 789012
 6  },
 7  "user": {
 8    "id": "11111111-1111-1111-1111-111111111111"
 9  }
10}

Пример ответа

1{
2  "message_ids": [
3"aa8ef5c2-front-4a3b-9d2e-example00001",
4"bb9fa6d3-front-4b4c-8e3f-example00002"
5    ]
6}

Отправка уведомления всем пользователям

Отправляет push-уведомление всем или выбранным подписавшимся пользователям. Уведомление доставляется во все браузеры и установленные PWA, где пользователь подписался на уведомления.

HTTP-запрос

POST https://messaging-platform.xsolla.com/api/v2/messages/push/send_batch

Заголовки запроса

Параметры запроса

Параметры ответа

Пример запроса

 1POST /api/v2/messages/push/send_batch HTTP/1.1
 2Host: messaging-platform.xsolla.com
 3Authorization: Bearer <token>
 4Idempotency-Key: 5c1f0d2a-9b7e-4f36-8a1d-example00002
 5Content-Type: application/json
 6
 7{
 8  "app_id": "your_app_id",
 9  "recipients": {
10    "type": "all"
11  },
12  "title": "Seasonal sale!",
13  "body": "Up to 50% off in the Web Shop until the end of the week."
14}

 1POST /api/v1/messages/push/send_batch HTTP/1.1
 2Host: messaging-platform.xsolla.com
 3Authorization: Bearer <token>
 4Idempotency-Key: 7d2e1f3b-8c6a-4e57-9b2f-example00003
 5Content-Type: application/json
 6
 7{
 8  "app_id": "your_app_id",
 9  "recipients": {
10    "type": "external_user_id",
11    "external_user_id": ["player_123", "player_456"]
12  },
13  "title": "Seasonal sale!",
14  "body": "Up to 50% off in the Web Shop until the end of the week."
15}

Пример ответа

1{
2  "summary": {
3    "failed_count": 0,
4    "success_count": 20
5  }
6}

 1{
 2  "results": [
 3    {
 4      "message_id": "cc0ab7e4-front-4c5d-9f4a-example00003",
 5      "player_id": "player_123",
 6      "status": "success"
 7    },
 8    {
 9      "message_id": "dd1bc8f5-front-4d6e-8a5b-example00004",
10      "player_id": "player_456",
11      "status": "success"
12    }
13  ]
14}