プッシュ通知

仕組み

ウェブショップでは、プッシュ通知を設定できます。これは、ユーザーがブラウザで直接受け取る個別または一括メッセージです。プッシュ通知を使用すると、新しいアイテム、プロモーション、特別オファーについてユーザーに知らせることができます。

ユーザーに通知を送信するには、例えばユーザーが戦闘で敗れた際や、リソースが切れた際など、ゲームサーバー側から通知送信用のエクソーラAPIを呼び出します。

通知をクリックすると、ユーザーはウェブショップに移動し、必要なアイテムを購入することができます。

プッシュ通知はエクソーラサイトビルダーで設定され、公開されたウェブショップでのみ機能します。

エクソーラはゲーム内イベントを追跡しません。ゲームサーバーが通知を送信するためのAPIコールを行うタイミングを定義します。例を以下に示します：

インタラクションフロー

1. ユーザーがブラウザまたはインストールされた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. ウェブショップはユーザーをエクソーラシステムの登録者として登録します。サブスクリプションはユーザーのデバイス上のブラウザまたはインストールされた 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. プッシュ通知セクションに移動します。
4. 通知を有効にするトグルをオンにします。
5. アプリケーションID、クライアントID、クライアント秘密鍵フィールドから値をコピーします。これらはゲームサーバーからAPIリクエストを送信するために必要です。パラメータは一度作成され、通知を有効にするトグルが初めてオンになったときにプロジェクト全体で使用されます。プロジェクトに複数のサイトがある場合、同じ値がすべてのサイトで使用されます。
6. 必要に応じてサブスクリプションバナーを設定します：タイトル、説明、アイコン、ボタンのテキストを変更します。
7. サイトが開かれたときに自動的にユーザーの通知送信許可をリクエストするには、自動リクエスト許可トグルをオンにします（任意）。トグルがオフの場合、ユーザーが登録ボタンをクリックした後にのみ許可がリクエストされます。
8. 変更を適用するには、サイトを公開します。

9. ゲームサーバーでプッシュ通知送信ロジックを実装します。ゲームサーバーは通知送信のためのAPIコールを行い、リクエストにユーザーIDを含める必要があります。

通知の送信

エクソーラは自動的に通知を送信することはありません。送信は常にゲームサーバーからAPIコールを介して開始する必要があります。

ベースURL: https://messaging-platform.xsolla.com

認証

リクエストはOAuth 2.0プロトコルを介して認証されます。JWTを生成するAPIコールを使用してサーバーJWTを取得し、次のパラメータを渡します：

• grant_type — JWTのグラントタイプ、client_credentials値を渡します
• client_id — プッシュ通知セクション設定のクライアントIDフィールドの値
• client_secret — プッシュ通知セクション設定のクライアント秘密鍵フィールドの値

受け取ったトークンを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}