推送通知

工作原理

在网充商店中，您可以设置推送通知⸺即用户可直接在浏览器中接收的个人或批量消息。您可以通过推送通知，向用户告知新商品、促销活动和特别优惠等信息。

如需向用户发送通知⸺例如在用户战斗失败或资源耗尽后发送通知⸺请在游戏服务器侧调用艾克索拉发送通知API。

用户点击通知后，将进入网充商店，并可在其中购买所需商品。

推送通知需在艾克索拉建站器中配置，且仅适用于已发布的网充商店。

艾克索拉不会跟踪游戏内事件。您可以自行定义游戏服务器在何时调用API发送通知，例如：

交互过程

1. 用户在浏览器中或通过已安装的PWA打开网充商店，并看到提示订阅通知的横幅。
2. 用户点击Subscribe，并在浏览器系统提示中允许接收通知。

    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. 网充商店会在艾克索拉系统中将用户注册为订阅者。该订阅会与用户设备上的浏览器或已安装的PWA关联。可向用户发送的通知类型取决于其授权状态：

   • 如果用户已登录网充商店，其ID会与订阅关联⸺您可以向该用户发送个人通知。
   • 如果用户未登录，您只能向其发送批量通知；用户登录后，订阅会自动与其用户ID关联。

4. 游戏服务器调用艾克索拉API发送通知。

5. 用户收到推送通知。

6. 用户点击通知并进入网充商店⸺如果传递了data.url参数，则进入该参数指定的页面；如果未传递该参数，则进入主页。如果用户在网充商店中存在活动会话，则会保持登录状态。

  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. 如需让站点在打开时自动请求用户授权发送推送通知，请打开Auto-request permission开关（可选）。如果该开关关闭，则仅在用户点击Subscribe按钮后请求权限。
8. 要应用更改，请发布网站。

9. 在游戏服务器上，实现推送通知发送逻辑。游戏服务器必须调用API发送通知，并在请求中传递用户ID。

发送通知

艾克索拉不会自动发送通知⸺通知始终由您的游戏服务器调用相应API发起。

基础URL：https://messaging-platform.xsolla.com

身份认证

请求通过OAuth 2.0协议进行身份认证。调用生成JWTAPI获取服务器JWT，并传递以下参数：

• grant_type — JWT授权类型，传入client_credentials值
• client_id — Push notifications部分设置中的Client ID字段值
• client_secret — Push notifications部分设置中的Client secret key字段值

在Authorization: Bearer <token>请求头中传递收到的令牌。

向用户发送通知

通过用户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}

向所有用户发送通知

向所有或指定订阅用户发送推送通知。通知会送达该用户已订阅通知的所有浏览器和已安装的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}