新しいCommerce APIメソッドの使い方

どのように動作するか

Commerce APIを接続して、御社のストアのサーバー部分を実装したり、既にエクソラとサーバー統合(トークンとの統合)を実装している場合には、新しいCommerce API手法に切り替えることができます。

主な機能:

  • エクソラログインまたは決済ステーションアクセストークン
  • 仮想アイテム管理
  • ユーザーインベントリ管理
  • カートおよび注文管理

使用に適した方

  • ストアインターフェースを開発し、サードパーティのソリューションを使用してサーバー側を実装したいパートナー。
  • エクソラとのサーバー統合を既に実装済みで新しいストアと新しいCommerce APIメソッドを接続したいパートナー。

入手方法

アプリにCommerce APIを接続するには:

  1. パブリッシャーアカウント仮想アイテムモジュールを設定します。
  2. 認証を設定します。
  3. ストア管理メソッドを実装します。

統合には、プロジェクト設定>ウェブフックに表示されているプロジェクトIDが必要です。プロジェクトIDはCommerce APIリクエストで使用されます。

パブリッシャーアカウントに仮想アイテムモジュールを設定します

  1. プロジェクトに移動して、プロジェクトの作成ボタンをクリックします。
  2. プロジェクト名を追加して作成をクリックします。

  1. プロジェクト設定>統合設定に移動し、Commerce APIを統合するトグルをオンに設定ことを確認します。
  2. ストアをプロジェクトに接続します。
  3. 仮想アイテムモジュールを接続します。

  1. アイテムのグループを作成します。

  1. アイテムを作成します。

  1. アイテムが作成されたら、ストアでグループディスプレイをオンにします。

認証設定

以下のユーザー認証オプションを利用できます:

エクソラログイン経由の認証

  1. 指示に従ってパブリッシャーアカウントプロジェクトをセットアップします。
  2. JSONウェブトークンまたはOAuth 2.0プロトコルを使用して、承認メソッドの呼び出しを実装します。

ユーザーデータがエクソラデータストレージに保存されている場合には、以下のメソッドの呼び出しを実装します:

ユーザーデータがPlayFabデータストレージに保存されている場合には、PlayFabレシピを使用します。

ユーザーデータが御社に保存されている場合には、カスタムストレージレシピを使用します。

決済ステーションアクセストークンを介した認証

認証フロー:

  1. お使いのアプリケーション(クライアント)は認証リクエストを御社のサーバーに送信します。
  2. サーバーはマーチャントIDとAPIキーをエクソラサーバーに送信し、access_tokenを要求します。
  3. エクソラサーバーは御社のサーバーにaccess_tokenを送信します。
  4. 御社のサーバーはaccess_tokenをクライアントに送信します。

返されたaccess_tokenCommerce APIでの認証のための認証トークンとして使用されます。また、ストアインターフェースの構築のためにも使用されます。

ストア管理の方法

ストアの管理メソッドには以下のグループのメソッドが含まれます:

Get virtual items list

ストアに追加された仮想アイテムの完全リストを表示するには、Get virtual items list APIメソッドを実装します。

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/virtual_items?locale=en");

xhr.send(data);

//RESPONSE

"items": [
    {
      "attributes": [],
      "description": "Conquer your foes with vindication using the Basic Blaster! ",
      "groups": [
        "all",
        "featured",
        "Xsolla",
        "weapons"
      ],
      "image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
      "is_free": false,
      "name": "Xsolla Basic Blaster 1",
      "order": 1,
      "price": {
        "amount": "0.9950000000000000",
        "amount_without_discount": "1.9900000000000000",
        "currency": "USD"
      },
      "sku": "gun_1",
      "type": "virtual_good"

Get item groups list

  1. ストアに追加された仮想アイテムグループの完全なリストを表示するには、Get item groups list APIメソッドを実装します。
  2. Get virtual items listメソッドで返されるそれぞれのskuパラメータの値に、所属するグループのexternal_idを指定します。アイテムがパブリッシャーアカウントでグループ化されるのと同じ方法で、skuexternal_idにマッチします。

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/groups");

xhr.send(data);

//RESPONSE

  "groups": [
    {
      "children": [],
      "description": "all",
      "external_id": "all",
      "id": 10,
      "image_url": "http://none",
      "level": 0,
      "name": "all",
      "order": null,
      "parent_external_id": null
    }

Get cart

仮想アイテムの購入には、Get cart by IDまたはGet current user’s cart APIメソッドを実装します。Cart IDはアイテムの追加/削除に使用されます。

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/cart/custom_id?locale=en&currency=USD");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "cart_id": "custom_id",
  "is_free": true,
  "items": [],
  "price": null
}

Note
(カートを作成しないで)クイックアイテム購入を有効にする場合には、Create order with specified item APIメソッドを使用します。

Create order with all items

  1. APIメソッドの1つを実装します:
    1. カートをIDで取得する場合には、Create order with all items from particular cart
    2. 現在のカートを取得する場合には、Create order with all items from current cart

作成された注文はNewオーダーステータスを受取ります。

  1. 新しいウィンドウで決済UIを開くには、次のリンクを使用してください:https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKENACCESS_TOKENは注文が作成されたときに受け取ったトークンです。
  2. 決済プロセスをテストするには:
    1. このURLを使用します:https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
    2. リクエストでサンドボックスパラメータをtrueに設定します。
    3. テストのための銀行のカードのリストを使います。

Copy
Full screen
Small screen
var data = JSON.stringify({
  "currency": "USD",
  "locale": "en",
  "sandbox": false
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://store.xsolla.com/api/v2/project/44056/payment/cart/custom_id");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE  

{
  "order_id": 641,
  "token": "f4puMEFFDZcx9nv5HoNHIkPe9qghvBQo"
}

Get order

購入が既に処理されたかを判断するにはGet order APIメソッドを実装します。以下の注文ステータスが利用できます。

  • New — 注文が作成されたものの、支払いはされていない。
  • Paid — 注文に対する支払い済み。
  • Cancelled — 注文はキャンセル済み。
  • Done — 注文は支払いが完了し、アイテムはインベントリに追加されました。

Note
ステータスの確認は一定の頻度で実行されるべきです。1度だけの確認だと、注文に新しいステータスが付与される前に確認される可能性があるためです。

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/order/656");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "content": {
    "is_free": false,
    "items": [
      {
        "is_free": false,
        "price": {
          "amount": "0.9950",
          "amount_without_discount": "1.9900",
          "currency": "USD"
        },
        "quantity": 123,
        "sku": "gun_1"
      }
    ],
    "price": {
      "amount": "122.3850",
      "amount_without_discount": "122.3850",
      "currency": "USD"
    }
  },
  "order_id": 656,
  "status": "new"
}

Get user’s inventory

購入後にインベントリに追加されたアイテムのリストを取得するには、Get user’s inventory APIメソッドを実装します。

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/user/inventory/items");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "items": [
    {
      "description": "Conquer your foes with vindication using the Basic Blaster! ",
      "image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
      "instance_id": null,
      "long_description": "Conquer your foes with vindication using the Basic Blaster! Conquer your foes with vindication using the Basic Blaster! ",
      "name": "Xsolla Basic Blaster 1",
      "quantity": 22,
      "sku": "gun_1",
      "type": "virtual_good"
    },
    {
      "description": "Protect your noggin' with style",
      "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png",
      "instance_id": null,
      "long_description": "merchant_virtual_items_virtual_item_long_description_159429",
      "name": "Xsolla Helmet",
      "quantity": 18,
      "sku": "helmet_1",
      "type": "virtual_good"
    }
  ]
}

この記事は役に立ちましたか?
ありがとうございます!
改善できることはありますか? メッセージ
申し訳ありません
この記事が参考にならなかった理由を説明してください。 メッセージ
ご意見ありがとうございました!
あなたのメッセージを確認し、体験を向上させるために利用させていただきます。