免费商品

工作原理

免费商品是指用户无需花费虚拟货币或真实货币即可获得的商品。

免费商品适用于以下场景：

• 销售游戏内商品——虚拟物品、虚拟货币套餐和捆绑包
• 通过游戏Key销售游戏和DLC

使用案例：

• 在项目里程碑或周年等特殊日期提供免费商品，用于回馈忠诚用户。
• 为已购买基础游戏的用户提供免费附加内容，作为忠诚度奖励。
• 在网页商城提供免费新手包，吸引新用户进入游戏。

免费虚拟物品、虚拟货币和捆绑包仅对已授权用户可用。免费游戏密钥对已授权和未授权用户均可用。免费商品数量限制仅可针对已授权用户配置。

设置免费商品

2. 点击 Create manually，并在下拉列表中选择 Virtual items。

3. 在 General settings 部分，填写：
   1. SKU
   2. 商品所属的一个或多个组（可选）
   3. 名称
   4. 简短描述
   5. 扩展描述—要添加，请打开相应的开关（可选）

4. 在 Media 部分，上传一张或多张图片或视频（可选）——可从设备上传或通过链接添加。使用艾克索拉建站器创建的网站中，所有商品卡片都会显示被标记为 Main 的文件，其余文件仅在带有媒体图库的商品卡片中可见。被标记为 Main 的文件也会在目录检索API调用的响应中返回。

5. 在 Price settings 部分，选择 Free item。

6. 若需限制可领取的商品数量：
   1. 在 Limits 部分打开开关并指定数量。
   2. 配置重置频率。从下拉列表中选择一个周期：
      1. Daily。
      2. Weekly。
      3. Monthly。
      4. Custom interval。区间从商品在商店开始显示之日开始计算。
      5. No regular refresh。
   3. 根据所选周期设置重置计划，填写相应参数。

7. 配置商品的显示时间限制（可选）：

   1. 在 Add specific display period 部分打开开关。
   2. 指定时区以及该时间段的开始和结束时间。

   如需不指定显示结束时间，请打开 No end date 开关。

8. 按以下任一方式配置属性（可选）：
   1. 以JSON格式添加属性及其值。
   2. 手动创建属性及其值，并将其链接到商品。

9. 点击Create。
10. 在打开的窗口中，选择商品状态，然后点击Continue。

创建的商品会显示在 All items 部分。

通过API设置

要将商品设置为免费，请在调用以下管理 API时在请求正文中传入“is_free”: true：

• Create virtual item or Update virtual item
• Create game, Update game by ID or Update game by SKU
• Create virtual currency or Update virtual currency
• Create virtual currency package or Update virtual currency package
• Create bundle or Update bundle 如果需要限制用户可领取的免费商品数量，请在创建或更新商品的API调用中传递以下参数：
  • limits（指定数量）
  • limits.recurrent_schedule（指定重置频率）

您还可以设置商品在商店中的显示时间限制，并设置区域限制。

在目录中显示免费商品

免费商品在目录中的显示取决于实现方式——通过建站器或通过API。

通过建站器显示

要在您的网站上显示免费商品：

1. 创建免费商品。
   2. 在发布商帐户的项目中，前往 Storefronts > Websites 部分。
   3. 在目标网站的面板中，点击 Open Site Builder。

   

2. 在移动端游戏专用帐户的项目中，前往 Web Shop 部分。
3. 点击目标网站的面板。

4. 如果您的网站包含多个页面，选择需要的页面：
   1. 点击建站器顶部的当前页面标题。
   2. 从下拉列表中选择所需页面。
5. 在 Store 部分的 Item type 字段中，选择免费商品类型，并在需要时指定其组。
6. 配置商品卡片布局。
7. 完成所有必要更改并准备发布网站后：
   1. 在建站器的右上角点击 Publish。
   2. 勾选要发布的页面。
   3. 点击 Publish。

网站发布后，包含免费商品的区块将可用。如果未显示商品，请检查其状态是否为 Available，且未启用基于时间的显示限制。

通过API获取免费商品信息

如果通过API配置目录，可通过 Catalog 子部分中的以下调用获取免费商品数据：

• Get virtual items list
• Get virtual currency list
• Get virtual currency packages list
• Get bundles list
• Get games list

向用户发放免费商品

包含免费商品的订单处理方式取决于购买过程中是否使用了购物车。

如果用户未使用购物车直接购买商品，请使用 Create order with specified free item API调用。

如果用户使用购物车购买商品，可能出现以下情况：

• 如果用户的购物车同时包含付费和免费商品，请使用订单创建API调用 Create order with all items from particular cart 或 Create order with all items from current cart。在这种情况下，用户会通过支付UI完成支付。
• 如果用户的购物车只包含免费商品，请使用 Create order with free cart 或 Create order with particular free cart API调用。在这种情况下，不会使用支付UI。

  两种情况下，艾克索拉都会发送 Successful payment for order Webhook，其中包含用于向用户发放商品的商品数据。对于免费商品，Webhook 中的 order.invoice_id 参数为 null。

免费商品订单对象示例：

 1{
 2  "method": "POST",
 3  "url": "https://mybestgame.com/xsolla/notification",
 4  "body": {
 5    "items": [
 6      {
 7        "sku": "gift_direct_game_reward-supercoin",
 8        "type": "virtual_currency",
 9        "is_pre_order": false,
10        "quantity": 500,
11        "amount": "0",
12        "promotions": [
13
14        ]
15      },
16      {
17        "sku": "package-500_supercoin",
18        "type": "bundle",
19        "is_pre_order": false,
20        "quantity": 1,
21        "amount": "0",
22        "promotions": [
23
24        ]
25      },
26      {
27        "sku": "xsolla-giveaway_offer_11_14_22",
28        "type": "bundle",
29        "is_pre_order": false,
30        "quantity": 1,
31        "amount": "0",
32        "promotions": [
33
34        ]
35      }
36    ],
37    "notification_type": "order_paid",
38    "order": {
39      "id": 12345678,
40      "mode": "default",
41      "currency_type": "unknown",
42      "currency": null,
43      "amount": "0",
44      "status": "paid",
45      "platform": "xsolla",
46      "comment": null,
47      "invoice_id": null,
48      "promotions": [
49
50      ]
51    },
52    "user": {
53      "external_id": "1234567812345678",
54      "email": null
55    }
56  },
57  "headers": {
58    "Authorization": "Signature 3b840ccefea111dcdfd111db1fdc6df969a3ec11",
59    "Accept": "application/json",
60    "Content-Type": "application/json"
61  },
62  "type": "webhook_payment",
63  "callback_parameters": {
64    "order_id": 12345678
65  }
66}

根据您的项目集成设置，商品将通过以下方式之一发放给用户：

• 如果您已集成 PlayFab，虚拟货币和虚拟物品会自动发放到用户的 PlayFab 物品库中。
• 如果您使用自定义发货系统，所有虚拟物品和虚拟货币都由您方发放。建议设置 Webhook 处理程序，在后端接收订单数据。所需数据包含在 Successful payment for order Webhook 中。 详细说明及其他获取购买数据的方式，请参见设置订单状态跟踪部分。