虚拟物品
概览
虚拟物品是用户可以使用真实货币或虚拟货币购买，或作为奖励获得的游戏内物品。这些物品没有实体形态，仅在游戏内使用。虚拟物品示例：皮肤、魔法药水、武器、密钥以及其他影响游戏玩法或角色外观的元素。
主要功能：
- 灵活的定价设置：
- 支持为同一物品同时设置真实货币和虚拟货币价格。
- 支持为同一物品设置多种真实货币和虚拟货币价格。在这种情况下，您必须为每种类型指定一种默认货币：一种用于真实货币和一种用于虚拟货币。
- 创建免费物品。
- 设置区域价格。
- 自动识别货币和国家/地区。
- 可购性设置：
- 限制不同区域的物品销售。
- 限制物品可购买的数量。
- 限制物品在商店中的显示时间。
- 设置不可购买的物品。物品可以在目录中隐藏，但仍可作为捆绑包的一部分获得，或作为购买其他物品的奖励获得。
- 目录组织：
- 创建组。
- 对目录中的物品进行排序。
虚拟物品与其他物品（虚拟货币、捆绑包等）一样，可以在发布商帐户中创建、通过API创建或作为目录的一部分导入。
本指南介绍手动创建物品和使用API的方法。
如需了解导入目录的详细信息，请参阅以下部分：
在发布商帐户中进行设置
创建组
通过组可以构建多级目录。未分配到组的物品将被放入未分组组中。未分组组不能编辑或删除。
要创建组：
- 在发布商帐户中打开您的项目，前往商品目录 > 虚拟物品部分。
- 单击+，从下拉列表中选择创建组。
- 指定以下参数：
- 外部ID — 唯一组ID。
- 组名称。
- 要在商店中显示组，请将在商店中显示组开关设置为开。此时组将以已启用状态创建。您可以稍后更改组状态。
- 单击创建组。
您可以通过在现有组内添加新组来创建多级目录。但未分组组不支持创建嵌套分组。
要将现有组嵌套在另一个组下：
- 在发布商帐户中打开您的项目，前往商品目录 > 虚拟物品部分。
- 选择要嵌套在其他现有组下的分组。
- 单击•••并从下拉列表中选择编辑组。
- 从目录位置位置下拉列表中，选择要放置当前分组的父级组。
- 单击保存更改。
创建虚拟物品
要创建虚拟物品：
- 在发布商帐户中打开您的项目，前往商品目录 > 虚拟物品部分。
- 单击+，从下拉列表中选择创建物品。
- 设置虚拟物品在目录中的可购状态。从以下选项中选择：
- 不可用（默认）— 物品在目录中不可购买，不能包含在捆绑包中，也不能作为购买其他物品的奖励。
- 可用 — 物品在目录中可购买，可以包含在捆绑包中或作为购买其他物品的奖励。
- 部分可用 — 物品在目录中不可购买，但可以添加到捆绑包中或作为购买其他物品的奖励。
- 配置基本设置，指定以下内容：
- 图片（可选）
- SKU
- 物品所属的一个或多个组
- 物品名称
- 物品描述（可选）
- 物品类型保留为默认设置 — 消耗品（推荐）。
- 设置虚拟物品定价：
- 要创建免费虚拟物品，在付费或免费字段中，选择免费物品。
- 要创建付费虚拟物品，在付费或免费字段中，选择付费物品，并指定一种或多种货币的价格。
- 设置区域价格（可选）。
- 限制物品可购买的数量（可选）。操作步骤：
- 将限制单个用户可购买该物品的次数开关设置为开，并指定用户可购买的物品次数。
- 配置限制刷新频率：
- 如果不想重置限制，从下拉列表中选择不刷新。
- 如果要定期重置限制，从下拉列表中选择刷新频率，并指定重置时间。
- 限制物品在商店中的显示时间（可选）。设置方法是在在商店中显示物品字段中选择时间段，并指定时区、开始日期和结束日期。如果不想设置结束日期，请勾选无结束日期复选框。
- 添加其他属性（可选）。
- 单击创建物品。
通过API处理虚拟物品
请使用虚拟物品和货币组管理子部分下的API调用来设置虚拟物品。
用于API调用的基本认证。传入Authorization:Basic <your_authorization_basic_key>，其中<your_authorization_basic_key>是按照Base64标准加密的商户ID: API密钥对。请前往发布商帐户找到以下参数：
- 商户ID在以下位置显示：
- 在公司设置 > 公司部分。
- 在发布商帐户任意页面的浏览器地址栏的URL中。URL的格式如下：
https://publisher.xsolla.com/<merchant_id>/。
- API密钥仅在创建它时在发布商帐户中显示一次，必须存储在己侧。您可以在以下部分中创建新的密钥：
关于使用API密钥的详细信息，请参阅API参考。
关于密钥的建议：
- 请在己侧保存生成的API密钥。您仅会在创建API密钥时在发布商帐户中看见它一次。
- 请妥善保管API不被泄露。它提供对您的个人帐户及您在发布商帐户中项目的访问权限。
- API密钥必须存储在您的服务器上，切勿保存在代码或前端中。
如果所需API调用不包含project_id路径参数，请使用在您公司的所有项目中都有效的API密钥来设置授权。
请使用虚拟物品和货币组目录子部分下的API调用在客户端侧获取虚拟物品目录。这些调用不需要基本授权。
请使用获取虚拟物品列表API调用来获取未分组的物品完整列表。要从固定组获取物品列表，请向按指定组获取商品列表调用传入external_id参数。
虚拟物品高级设置
限制物品可购买的数量
您可以限制单个用户可购买特定虚拟物品的次数，从而控制物品的可购性并创建限量优惠。
使用场景包括：
- 某个虚拟物品的每日、每周或每月购买限制。
- 每位用户仅可购买一次的新人物品。
配置购买限制有两种方式：
- 在发布商帐户中：创建或编辑物品时，将限制单个用户可购买该物品的次数开关设为开，指定用户可购买的物品数量，并配置限制刷新时间。
- 通过API：创建或更新物品时，在请求正文的
limits对象中传入购买限制设置。
限制的执行完全由艾克索拉侧处理。系统会跟踪每位用户购买物品的次数，并阻止超出配置限制的购买。
如果在目录请求中包含用户访问令牌（调用虚拟物品和货币组中目录子部分的API方法时），艾克索拉会计算特定用户还可以购买的每种物品数量。响应中将包含limits对象，其中包含总允许数量（total参数）和该用户剩余可购数量（available参数）。这些值可用于在界面中显示可购性。
如果请求中未提供用户访问令牌，响应中的available参数值将始终与总限制相一致。
具有购买限制的物品响应示例：
- json
1{
2 "items": [
3 {
4 "sku": "big_rocket",
5 "name": "Big Rocket",
6 "groups": [
7 {
8 "external_id": "accessory",
9 "name": "Accessory"
10 }
11 ],
12 "attributes": [
13 {
14 "external_id": "stack_size",
15 "name": "Stack size",
16 "values": [
17 {
18 "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
19 "value": "5"
20 }
21 ]
22 }
23 ],
24 "type": "virtual_good",
25 "description": "Big Rocket - description",
26 "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
27 "is_free": false,
28 "price": {
29 "amount": "100.99",
30 "amount_without_discount": "100.99",
31 "currency": "USD"
32 },
33 "virtual_prices": [
34 {
35 "amount": 100,
36 "sku": "vc_test",
37 "is_default": true,
38 "amount_without_discount": 100,
39 "image_url": "http://image.png",
40 "name": "SHOTGUN FOR TRUE RAIDERS",
41 "type": "virtual_currency",
42 "description": "description"
43 }
44 ],
45 "can_be_bought": true,
46 "inventory_options": {
47 "consumable": {
48 "usages_count": 1
49 },
50 "expiration_period": {
51 "type": "day",
52 "value": 1
53 }
54 },
55 "virtual_item_type": "non_renewing_subscription",
56 "limits": {
57 "per_user": {
58 "total": 5,
59 "available": 5
60 },
61 "per_item": null
62 },
63}
艾克索拉在结算初始化和订单完成时均执行购买限制。如果用户打开多个选项卡或尝试同时创建多个订单，系统将防止超出限制：任何包含已购物品的未付款订单都将被取消。
限制物品在商店中的显示时间
您可以为商店中的物品指定一个显示期限，以便：
- 保持目录与某段时间的相关性，例如节假日促销期间
- 提前创建物品但不在目录中显示
- 通过在物品旁边显示计时器，激励用户购买
您可以通过以下方式配置物品在商店中的显示时间限制：
- 在发布商帐户中创建或编辑物品时，在在商店中显示物品字段中选择时间段，并指定时区、开始日期和结束日期。如果不想设置结束日期，请勾选无结束日期复选框。
- 通过API创建或更新物品时，在
periods对象中包含以下参数：periods[0].date_from— 显示时间段的开始日期和时间（格式：YYYY-MM-DDThh:mm:ss±hh:mm）。periods[0].date_until— 显示时间段的结束日期和时间。若要省略结束日期，传入null。
您可以传入包含开始和结束日期的对象数组，通过API定义多个显示时间段。
时间段数组示例：
- json
1"periods": [
2 {
3 "date_from": "2022-06-10T14:00:00+03:00",
4 "date_until": "2022-06-30T14:00:00+03:00"
5 },
6 {
7 "date_from": "2022-07-10T14:00:00+03:00",
8 "date_until": "2022-07-30T14:00:00+03:00"
9 },
10 {
11 "date_from": "2022-08-10T14:00:00+03:00",
12 "date_until": "2022-08-30T14:00:00+03:00"
13 }
14]
设置区域限制
您可以配置虚拟物品在哪些区域可以购买。这样您就能控制物品的可见范围，例如：对特定国家/地区的用户隐藏物品，或者仅在特定区域作为促销活动的一部分提供。
要为虚拟物品设置区域限制，在调用创建虚拟物品或更新虚拟物品API方法时，在请求正文中包含带有相应区域ID的
regions数组示例：
- json
1"regions": [{
2 “id”: 123
3 }, {
4 “id”: 456
5 }
6]
设置区域定价
您可以根据不同国家/地区的经济情况配置区域定价，调整虚拟物品的价格。这有助于让不同购买力的用户都能买得起，从而提高转化率和总体销售额。
您可以通过以下方式设置区域定价：
- 在发布商帐户中（手动配置）：创建或编辑物品时，前往价格设置部分，将真实货币定价开关设为开，然后单击设置价格。您可以手动输入价格，也可以根据货币和税率自动计算。
- 在发布商帐户通过CSV文件导入：在CSV文件中，您可以为特定区域添加多行物品价格。有关文件结构和示例的详细信息，请参阅本地价格说明。
- csv
1SKU,Currency,Amount,Country,IsDefault,Platform
2game-key-1,EUR,9.09,,1,steam
3game-key-1,EUR,9.2,DE,0,steam
4game-key-1,EUR,8.09,IT,0,steam
5game-key-1,USD,10.1,US,0,steam
6game-key-1,MYR,47,MY,0,steam
7game-key-2,EUR,2.09,,1,steam
8game-key-2,EUR,2.2,DE,0,steam
9game-key-2,EUR,1.79,IT,0,steam
10game-key-2,USD,2.3,US,0,steam
11game-key-2,MYR,24,MY,0,steam
- json
1"prices": [
2 {
3 "amount": 100,
4 "currency": "USD",
5 "is_enabled": true,
6 "is_default": true
7 },
8 {
9 "amount": 200,
10 "currency": "CZK",
11 "country_iso": "CZ",
12 "is_enabled": false,
13 "is_default": false
14 }
15 ]
有用链接
上次更新时间: 2025年7月18日发现了错别字或其他内容错误？ 请选择文本，然后按Ctrl+Enter。
