# Webshop 目录架构参考

> 查找可用于控制商品在 Webshop 中的显示方式的目录字段。

网上商店会在项目的 [IAP](/iap.md) 目录中渲染商品。每个商品都是标准的 IAP 目录商品，您可以使用特定于网上商店的字段（类别、高分辨率图像、推荐处理、展示顺序和每个商品标示）进行扩展，从而控制商品在商店中的显示方式。

此参考列出了网上商店为每个商品读取的字段：每个 IAP 商品的基本目录字段以及网上商店扩展字段。Webshop 扩展字段仅适用于包含在 Webshop 目录中的商品。有关目录的来源和商品展示方式的信息，请参阅[目录和网上商店](./catalog-and-payments.md)付款；要创作商品，请参阅[在 Editor 中创建目录](/iap/create-catalog-in-editor.md)。

## 商品字段##product-fields

这些是每个目录商品的基字段。

| 字段                 | Type（类型） | 必需 | 描述                                                             |
| ------------------ | -------- | -- | -------------------------------------------------------------- |
| `uSKU`             | 字符串      | 是  | 商品的唯一标识符 (SKU)。                                                |
| `type`             | 字符串      | 是  | 商品类型：`Consumable`、`NonConsumable` 或 `Subscription`。            |
| `imageUrl`         | 字符串      | 否  | 商品卡上显示的商品图像的 URL。                                              |
| `productDetails`   | 数组       | 是  | 本地化显示详细信息，每种语言一个条目。请参阅本[地化产品详细信息](#localized-product-details)。 |
| `pricing`          | 数组       | 是  | 每种货币的价格。请参阅[定价](#pricing)。                                     |
| `storeIdOverrides` | 数组       | 否  | 替换特定于商店的商品 ID。每个条目都有一个`store`（`apple`或`google`）和一个`value`。     |

## 本地化产品详细信息##localized-product-details

`productDetails` 中的每个条目都以一种语言描述商品。

| 字段            | Type（类型） | 必需 | 描述                                                                            |
| ------------- | -------- | -- | ----------------------------------------------------------------------------- |
| `language`    | 字符串      | 是  | 此条目适用的语言。                                                                     |
| `title`       | 字符串      | 是  | 商品的显示名称。                                                                      |
| `description` | 字符串      | 是  | 面向玩家的商品描述。                                                                    |
| `subtitle`    | 字符串      | 否  | 随标题一起显示的可选辅助行。                                                                |
| `badge`       | 对象       | 否  | 产品卡上显示的芯片。包含`text`（必填，最多 32 个字符）和文本旁边显示的图标的可选`imageUrl`。任何商品都可以带有标示，无论是否在销售中。 |

## 定价##pricing

`pricing` 中的每个条目都以一种货币设置价格。数组必须在 `USD` 中至少包含一个条目。

| 字段             | Type（类型） | 必需 | 描述                                 |
| -------------- | -------- | -- | ---------------------------------- |
| `currencyCode` | 字符串      | 是  | ISO 4217 货币代码，例如 `USD` 或 `GBP`。    |
| `amount`       | 整数       | 是  | 为商品收取的金额。                          |
| `webshopPrice` | 整数       | 否  | 网上商店上显示的价格。设置此选项可为商品提供特定于 Web 的价格。 |

数量是整数（以微为单位），其中 1,000,000 是货币的一个单位。例如，`9990000` 为 9.99。通过目录工具而不是手动设置价格 — 请参阅[在 Editor 中创建目录](/iap/create-catalog-in-editor.md)。

## Webshop 扩展字段##webshop-extension-fields

这些字段使用特定于 Webshop 的显示选项扩展基础目录商品。它们仅对您的网上商店目录中的商品生效。

| 字段           | Type（类型） | 必需 | 描述                                                                                                        |
| ------------ | -------- | -- | --------------------------------------------------------------------------------------------------------- |
| `categories` | 字符串数组    | 否  | 商品所属的类别 ID（最多 16 个，唯一）。每个类别都必须与您为网上商店定义的类别相匹配。                                                            |
| `hdImages`   | 数组       | 否  | 商品详细信息对话框的高分辨率图像（最多 8 张）。每个条目都有一个`url`（必填）和一个可选`altText`。                                                 |
| `promotion`  | 对象       | 否  | 卡的推荐处理。`type` 为 `Sale`、`Bonus` 或 `Limited`。可选的 `startsAt` 和 `endsAt` 字段 (RFC 3339 date-times) 可调度显示治疗的时间。 |
| `sortIndex`  | 整数       | 否  | 商品在商店中的展示顺序。较低的值首先出现。                                                                                     |

## 示例##example

以下商品同时包含基础目录字段和网上商店扩展字段：

```json
{
  "uSKU": "com.example.gems.medium",
  "type": “消耗品”，
  "imageUrl": "https://cdn.example.com/gems-medium.png",
  "productDetails": [
    {
      "language": "en",
      "title":“Medium Gem Pack”，
      "description": "在游戏中可以方便的存放宝石。",
      "subtitle":"500 gems",
      "badge": { "text":"Best value", "imageUrl": "https://cdn.example.com/gem-icon.png" }
    }
  ],
  "pricing": [
    { "currencyCode":"USD", "amount":9990000, "webshopPrice":7990000 }
  ],
  "categories": ["gems"],
  "hdImages": [
    { "url": "https://cdn.example.com/gems-medium-hd.png", "altText":"一堆宝石" }
  ],
  "promotion": { "type":"Sale", "endsAt":"2026-07-01T00:00:00Z" },
  "sortIndex":10
}
```