Notificações push

Como funciona

Na Web Shop, você pode configurar notificações push — mensagens pessoais ou em massa que os usuários recebem diretamente em seu navegador. As notificações push permitem que você informe os usuários sobre novos itens, promoções e ofertas especiais.

Para enviar uma notificação a um usuário — por exemplo, após ele perder uma batalha ou ficar sem recursos — chame a API Xsolla para enviar notificações no lado do servidor do jogo.

Após clicar na notificação, o usuário é direcionado à Web Shop, onde pode comprar os itens de que precisa.

As notificações push são configuradas no Xsolla Site Builder e funcionam apenas para Web Shops publicadas.

A Xsolla não rastreia eventos no jogo. Você define quando o servidor do jogo faz a chamada de API para enviar uma notificação, por exemplo:

Fluxo de interação

1. O usuário abre a Web Shop em um navegador ou via um PWA instalado e vê um banner oferecendo a assinatura de notificações.
2. O usuário clica em Subscribe e permite notificações no prompt do sistema do navegador.

    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. A Web Shop registra o usuário como assinante no sistema da Xsolla. A assinatura é vinculada ao navegador ou ao PWA instalado no dispositivo do usuário. As notificações que você pode enviar ao usuário dependem do status de autorização dele:

   • Se o usuário estiver logado na Web Shop, seu ID é vinculado à assinatura — você pode enviar notificações pessoais para esse usuário.
   • Se o usuário não estiver logado, você só pode enviar notificações em massa; após o usuário fazer login, a assinatura é automaticamente vinculada ao ID do usuário.

4. O servidor do jogo faz a chamada da API Xsolla para enviar notificações.

5. O usuário recebe a notificação push.

6. O usuário clica na notificação e acessa a Web Shop — para a página especificada no parâmetro data.url, ou para a página principal se o parâmetro não for passado. Se o usuário tiver uma sessão ativa na Web Shop, ele permanece logado.

  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

Como obter

3. Acesse a seção Push notifications.
4. Ative a opção Enable notifications.
5. Copie os valores dos campos Application ID, Client ID e Client secret key — você precisará deles para enviar solicitações de API do servidor do jogo. Os parâmetros são criados uma vez, quando a opção Enable notifications é ativada pela primeira vez, e são usados para todo o projeto: se houver vários sites no projeto, os mesmos valores são usados para todos eles.
6. Configure o banner de assinatura, se necessário: altere o título, descrição, ícone e texto do botão.
7. Para que o site solicite automaticamente a permissão do usuário para enviar notificações push ao ser aberto, ative a opção Auto-request permission (opcional). Se a opção estiver desativada, a permissão é solicitada apenas após o usuário pressionar o botão Subscribe.
8. Para aplicar as alterações, publique o site.

9. No servidor do jogo, implemente a lógica de envio de notificações push. O servidor do jogo deve fazer a chamada de API para enviar notificações e passar o ID do usuário na solicitação.

Enviando notificações

A Xsolla não envia notificações automaticamente — o envio é sempre iniciado pelo servidor do seu jogo via chamada de API.

URL base: https://messaging-platform.xsolla.com

Autenticação

As solicitações são autenticadas via o protocolo OAuth 2.0. Obtenha um JWT do servidor usando a chamada de API Generate JWT, passando os seguintes parâmetros:

• grant_type — tipo de concessão JWT, passe o valor client_credentials
• client_id — o valor do campo Client ID nas configurações da seção Push notifications
• client_secret — o valor do campo Client secret key nas configurações da seção Push notifications

Passe o token recebido no cabeçalho Authorization: Bearer <token>.

Enviar notificação para o usuário

Envia uma notificação push pessoal para um usuário pelo ID dele. A notificação é entregue a todos os navegadores e PWAs instalados onde o usuário se inscreveu para receber notificações.

Solicitação HTTP

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

Cabeçalhos da solicitação

Parâmetros da solicitação

Parâmetros da resposta

Exemplo de solicitação

 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}

Exemplo de resposta

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

Enviar notificação para todos os usuários

Envia uma notificação push para todos ou para usuários inscritos específicos. A notificação é entregue a todos os navegadores e PWAs instalados onde o usuário se inscreveu para receber notificações.

Solicitação HTTP

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

Cabeçalhos da solicitação

Parâmetros da solicitação

Parâmetros da resposta

Exemplo de solicitação

 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}

Exemplo de resposta

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}