Store API集成

运行机制

您可以连接Store API来实现商店的服务器部分,如果您已实现服务器与艾克索拉的(令牌)集成,则也可以改用新的Store API方法。

主要功能:

  • 通过艾克索拉登录管理器或支付中心访问令牌进行认证
  • 虚拟物品管理
  • 用户物品库管理
  • 购物车和订单管理

使用者

  • 开发了商店界面、并希望使用第三方解决方案实现服务器侧的合作伙伴。
  • 已实现服务器与艾克索拉的集成、并希望使用新的Store API方法连接到商店的合作伙伴。

如何获取

要连接Store API至应用程序:

  1. 发布商帐户中设置虚拟物品模块。
  2. 设置认证方式。
  3. 实现商店管理的方法。

集成过程中需使用项目ID,可在项目设置 > Webhook中找到。项目ID用于Store API的请求中。

在发布商帐户中设置虚拟物品模块

  1. 前往项目,然后单击创建项目按钮。
  2. 添加项目名称,然后单击创建

  1. 前往项目设置 > 集成设置,确保已启用集成新商店管理方法开关。
  2. 连接商店至您的项目。
  3. 连接虚拟物品模块。

  1. 创建物品组。

  1. 创建物品。

  1. 创建物品后,打开在商店中显示组开关。

认证设置

有以下用户认证选项可用:

通过艾克索拉登录管理器进行认证

  1. 按照说明设置发布商帐户项目。
  2. 通过JSON Web令牌或OAuth 2.0协议实现授权方法的调用。

如果用户数据保存在艾克索拉数据存储中,请实现以下方法的调用:

如果用户数据保存在PlayFab数据存储中,请使用PlayFab高级诀窍。

如果用户数据保存在您自己一侧,请使用自定义存储高级诀窍。

通过支付中心访问令牌认证

认证过程:

  1. 应用程序(客户端)发送认证请求至您的服务器。
  2. 您的服务器发送商户ID和API密钥至艾克索拉服务器并请求access_token
  3. 艾克索拉服务器发送access_token至您的服务器。
  4. 您的服务器发送access_token至客户端。

返回的access_token用作授权令牌,用于在Store API中和生成商店界面时进行认证。

商店管理方法

商店管理方法包含以下几组方法:

Get Virtual Items List

实现Get virtual items list API方法以显示添加到商店的虚拟物品的完整列表。

示例

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以物品在发布商帐户中组合的方式进行匹配。

示例

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 IDGet current user’s cart的API方法。Cart ID用于添加/删除物品。

示例

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. Create order with all items from particular cart(如果通过ID获取购物车)
    2. Create order with all items from current cart(如果获取当前购物车)

创建的订单将为New订单状态。

  1. 如要在新窗口中打开支付UI,请使用下列链接:https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN,其中ACCESS_TOKEN是在创建订单时收到的令牌。
  2. 如要测试支付过程:
    1. 使用下列URL:https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
    2. 将请求中的sandbox参数设置为true
    3. 使用用于测试的银行卡列表

示例

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: 应以一定频率进行状态检查,因为一次性检查可能会错过订单的新状态。

示例

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方法获取购买后要添加到物品库的物品列表。

示例

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"
    }
  ]
}