概要

デジタル配信ソリューション — ゲーム開発者と、ゲーム、仮想アイテム、仮想通貨及びバンドルの配信のための独自のプラットフォームやエコシステムを持つ複数の配信パートナーとをつなぐソリューションです。

配信者パートナー — ゲームとゲーム内アイテムを配信し、独自のストアフロントと請求を行うことができるデジタルプラットフォームまたはエコシステム。エクソーラの販売パートナーの例：

• 複数のサービスをバンドルするスーパーアプリ
• バンキングアプリケーション
• 通信＆インターネットサービスプロバイダー
• キャッシュキオスク
• キャッシュバックおよびリワードプログラムプロバイダー
• ECマーケットプレイス

ゲーム開発者側のメリット：

• 急成長している配信パートナーと直結し、ゲームの視聴者を拡大します。
• ユニークなユーザー層を持つ新たな流通チャネルにゲームを追加することで、収益を拡大します。
• 広告やバナーを通じて、第三者のプラットフォームにおけるオーガニックな発見力を高めます。

配信パートナー側のメリット：

• ゲームコンテンツへのアクセス拡大によるユーザーのロイヤリティ向上します。ユーザーは、アプリやサービスから直接ゲームキー、仮想アイテム、仮想通貨及びバンドルを購入することができるようになります。
• ゲーム業界の人気の高まりを通じて、現在のユーザーを維持し、新しいユーザーを引き付けています。
• ゲーム産業市場の大手パブリッシャーからのゲームキー、仮想アイテム、仮想通貨の販売手数料による収入を増加します。

どのように動作するか

ゲームキー購入時のユーザーフロー

仮想アイテムや仮想通貨を購入する際のユーザーフロー

統合フロー

1. ゲーム開発者は、パブリッシャーアカウントでプロジェクトを作成し、ゲームキー、仮想アイテム、仮想通貨、およびバンドルをアップロードします。
2. 配信パートナーは次のユーザーデータをリクエストします：
   • ゲームを販売する場合 — キーとレシートが送信されるユーザーのメールアドレス
   • ゲーム内アイテムを販売する場合 — ゲーム内IDアイテムが追加されるユーザー、および領収書の送信先となるユーザーのメールアドレス
3. ユーザーは、配信パートナーインターフェイスに次のデータを入力します：
   • ゲーム購入の場合 — キーと領収書を受け取るためのメールアドレス
   • ゲーム内アイテムの購入の場合 — アイテムをインベントリに追加するためのゲーム内IDと領収書を受け取るためのメールアドレス
4. 配信パートナーはユーザートークンを作成するメソッドを呼び出し、メールアドレス（必須）とユーザーID（仮想アイテム、仮想通貨、バンドルの販売時に必須です）をパラメータとして渡します。
5. エクソーラは、ゲーム開発者がウェブフックを設定している場合、ユーザーがゲーム内に存在するかどうかをチェックします。ウェブフックの設定は、仮想アイテムや仮想通貨の販売では必須ですが、ゲームキーでは任意です。
6. エクソーラはユーザーデータでトークンを作成し、そのトークンを配信パートナーに送信します。
7. 配信パートナーは、ゲームカタログまたはゲーム内アイテムカタログをリクエストします。
8. エクソーラは、要求されたカタログを応答で返します。
9. 配信パートナーはカタログを受け取り、ユーザーに表示します。
10. ユーザーが購入を行います。配信パートナーはカートを作成します。
11. 配信パートナーは、ユーザーのカートを送信して注文を作成します。
12. エクソーラは、注文IDと割引や税金を含むカート価格を返します。
13. 配信パートナーは、カートの合計金額をユーザーに表示します。
14. ユーザーが支払いを続行した場合、配信パートナーはユーザーの資金を引き落とし、決済ステータスのページを表示します。
15. 販売パートナーはエクソーラに注文の支払いが完了したことを通知し、決済情報を送信します。
16. エクソーラはゲーム開発者に購入を通知します。
17. ゲームを購入したユーザーは、購入の詳細が記載された電子メールを受信し、ゲームキーを有効にすることができます。ユーザーが仮想アイテムや仮想通貨を購入した場合、それはインベントリに追加されます。

ゲーム開発者側での統合

デジタル配信ソリューションの接続方法

1. アドミンページでストアを接続して以下のことをダウンロードします：
   • ゲームキーを販売する場合はゲームキーまたはゲームキーバンドル；
   • ゲーム内アイテムを販売する場合は仮想アイテム、仮想通貨またはバンドル。
2. ウェブフックをセットアップします。
3. プロジェクトのデジタル配信ソリューションをアクティブ化するには、カスタマーサクセスマネージャーに連絡するか、csm@xsolla.comにメールを送信てください。

ウェブフックをセットアップする方法

以下の場合、ウェブフックのセットアップは必須です：

• ユーザーを検証し、ゲーム内のユーザーIDによってカタログをパーソナライズする
• ユーザーを検証し、購入したゲーム内アイテムをインベントリに追加する
• エクソーラ側のトランザクションIDとゲーム開発者側のシステムのトランザクションIDをリンクする
• 注文で追加ユーザーパラメータを渡す
• 購入通知を受信する

ウェブフックをセットアップにするには：

1. アドミンページであなたのプロジェクトを開きます。
2. サイドメニューでプロジェクト設定をクリックしてウェブフックに移動します。
3. ウェブフックトグルをオンにします。
4. ウェブフックURLを指定します。
5. プロジェクトのウェブフックに署名するための秘密鍵は、デフォルトで生成されます。新しい秘密鍵を生成する場合は、更新アイコンをクリックします。
6. 設定を保存するをクリックします。

ユーザー検証

エクソーラはユーザー検証ウェブフックを送信し、ユーザーがゲーム内に存在することを検証します。ユーザー検証では、以下のことが可能です：

• 応答にユーザー属性を渡すと、そのユーザー用にパーソナライズされたカタログを表示する。
• 購入後、ユーザーのインベントリにアイテムを追加する。

ウェブフックの受信を確認するには、サーバーは以下の情報を返す必要があります：

• ゲーム内にユーザーが存在する場合、メッセージボディのないHTTPコード204が表示されます。
• 指定されたユーザーが見つからないか、無効な署名が渡された場合、問題を説明するHTTPコード400が表示されます。

ウェブフックの全リストと仕組みは、例を含めてAPIリファレンスで詳しく説明されています。

応答として、custom_parametersオブジェクトで追加の取引パラメータを渡すことができます。

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"additionalProperties": false,
"properties": {
  "user_attributes": {
    "type": "object",
    "required": false,
    "minProperties": 1,
    "maxProperties": 100,
    "patternProperties": {
      "^[\\w-_.]{1,255}$": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 255
            },
            "minItems": 1,
            "maxItems": 1000
          }
        ]
      }
    },
    "additionalProperties": false
  }
}
}

応答の例：

{
  "user_attributes": {
    "age": 18,
    "level": 1,
    "game": "WoW",
    "is_baned": false,
    "registration_date": "2022-01-01"
  }
}

トランザクションのID連携

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "notification_type": {
      "type": "string"
    },
    "order_id": {
      "type": "integer"
    },
    "project_id": {
      "type": "integer"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_id": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "item_id": {
            "type": "integer"
          },
          "sku":  {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "type": {
            "type": "string"
          }
        }
      }
    }
  }
}

リクエストの例：

{
  "notification_type": "create_external_transaction",
  "order_id": 1,
  "project_id": 51336,
  "user": {
    "external_id": "user_id",
    "email": "public_email@test.com"
  },
  "items": [
    {
      "item_id": 101,
      "sku": "mithril_dagger",
      "quantity": 2,
      "type": "virtual_good"
    }
  ]
}

応答として、custom_parametersオブジェクトで追加の取引パラメータを渡すことができます。

予期された応答：

{
  "id": "validation_transaction_info_response.json",
 "$schema": "http://json-schema.org/draft-07/schema#",
 "description": "DDH Project Transaction Info Response",
 "type": "object",
 "additionalProperties": true,
 "properties": {
   "id": {
     "type": "string",
     "minLength": 1
   },
  "custom_parameters": {
     "type": "object",
     "additionalProperties": true,
     "minProperties": 1,
     "maxProperties": 200
   }
 }
}

応答の例：

{
    "id":"123"
}

トランザクションIDを連携するためのウェブフックパラメータのリスト：

購入通知

• 決済情報を含む決済ウェブフック。
• インベントリに追加されるアイテムに関する情報が含まれているカートのコンテンツウェブフック。

配信パートナー側での統合

統合マネージャー（psbusiness@xsolla.com）までメールでお問い合わせいただき、デジタル配信ソリューション APIと連携するために必要なパラメータを取得します：

• geotype；
• project_id；
• distribution_hub_idまたはapi_key。

エクソーラとの統合中に、支払い完了や支払いキャンセルの通知を送信する必要があります（ステップ9）。エクソーラ側で通知を正しく処理するために、通知を送信するサーバーのIPアドレスをマネージャーにお知らせください。IPアドレスが変更された場合は、できるだけ早くマネージャーにお知らせください。

1. 以下の入力フォームを表示します：
   • ユーザーのメールアドレス — ゲームを販売する場合。
   • ユーザーのメールアドレスとゲーム内ID — ゲーム内アイテムを販売する場合。

1. ユーザーIDは、仮想アイテムや仮想通貨、アイテムや通貨とのバンドルなどを販売するプロジェクトで使用されます。この場合、ユーザーがゲームに登録する際に受け取ったIDを入力するためのヒントを表示する必要もあります。

1. 例：

2. 以下の受信したユーザーデータを渡します：
   • ユーザーのメールアドレス。常に必須です。
   • ユーザーのゲーム内ID。ゲーム内アイテムを販売する際に必要です。

1. このデータは、ゲーム内でユーザーの存在を確認し、認証トークンを受け取るために使用されます。

1. ユーザートークンを作成するメソッドを使用します。リクエストで以下のパラメータを渡します：

1. ユーザーデータを含む認証トークンが応答で返されます。

3. インポート：
   • ゲームカタログ。ゲームリストを取得するメソッドを使用します。
   • 仮想アイテムカタログ、仮想アイテムを取得するリストメソッドを使用する。
   • 仮想通貨カタログ。仮想通貨リストを取得するメソッドを使用します。
   • ゲームまたはゲーム内アイテムカタログのバンドル。バンドルリストを取得するメソッドを使用します。

1. リクエストには、手順2で受け取ったトークンと、以下のパラメータを渡します：

4. ゲームとゲーム内アイテムのカタログをストアフロントに表示します。インターフェースでは、選択する機能を実装しています：
   • ゲームキーとゲームパブリッシングプラットフォームの数量。
   • 仮想アイテムの数量。
   • 固定金額の仮想通貨または仮想通貨パッケージの数量。
   • バンドルの数量。

1. カートを使用する場合は、ユーザーのカートでアイテムの数量を指定することができます。カートを使用しない場合、アイテムの数量の選択はカタログに実装することができます。

1. カート内のアイテム数量を指定する例：

1. カタログ内のアイテム数量を指定する例：

1. カートを使用しない場合は、ステップ6に進み、指定されたアイテムで注文を作成するメソッドを使用します。

5. カートにアイテムを入れるには、カートにアイテムを入れるメソッドを使用します。

1. ユーザーは、1つの注文でアイテムを追加および削除したり、数量を変更したりできます。以下のメソッドを使ってカートを更新することができます：
   • ユーザーがカートの中身を変更するたびにはカートにアイテムを入れるメソッド
   • カートを更新する、商品を削除するメソッド：
     • 現在のカートからカートアイテムを更新する。
     • 現在のカートからすべてのカートアイテムを削除する。
     • 現在のカートからアイテムを削除する。

1. この場合、カートを更新した後に現在のユーザーのカートを取得するを使用します。

1. カートの入力および更新方法のリクエストで、次のパラメータを渡します：

1. カートにアイテムを入れるまたは現在のユーザーのカートを取得するを呼び出した後、レスポンスは選択された商品に関する最新の情報（割引前と割引後の価格、ボーナス商品）を返します。

6. 注文を作成し、カート内のアイテムの代金を支払うには、現在のカートの全アイテムを含む注文を作成するメソッドを使用します。リクエストには、以下のパラメータを渡します：

1. 応答には、注文IDと税込みカート価格が返されます。

7. カートの合計金額をユーザーに表示します。
8. プラットフォームからユーザーの資金を引き落とします。ユーザーに決済状況を表示します。
9. 支払い通知を送信します。支払いが返金された、または完了しなかった場合は、決済キャンセルに関する通知を送信します。

1. エクソーラ側で通知を正しく処理するために、通知を送信するサーバーのIPアドレスをエクソーラマネージャーにお知らせください。IPアドレスが変更された場合は、できるだけ早くマネージャーにお知らせください。