--- title: ZEPETO.Product slug: world-sdk-guide-ch/zepetoproduct docTags: createdAt: 2026-09-04T06:32:42.200Z --- | 类型 | 说明 | | ------------------------------------------------------------------- | ------------------------------------------------------------------- | | [BaseResponse](./#baseresponse) | 响应类的基类。 | | [BaseRequest](./#baserequest) | 以泛型 `TResponse` 作为响应数据的 `BaseRequest` 类。 | | [ProductListResponse](./#productlistresponse) | `ProductListResponse` 类提供 API 调用结果以及获取到的商品信息列表。 | | [ProductBaseResponse](./#productbaseresponse) | 商品相关响应类的基类。 | | [ProductResponse](./#productresponse) | `ProductResponse` 类提供 API 调用结果以及获取到的商品信息。 | | [PurchaseResponse](./#purchaseresponse) | `ProductResponse` 类提供 API 调用结果以及购买信息。 | | [CurrencyListResponse](./#currencylistresponse) | `CurrencyListResponse` 类提供 API 调用结果以及货币信息列表。 | | [CurrencyResponse](./#currencyresponse) | `CurrencyResponse` 类提供 API 调用结果以及货币信息。 | | [ProductRecord](./#productrecord) | 商品信息。 | | [CurrencyRecord](./#currencyrecord) | 货币信息。 | | [ItemPackageUnitRecord](./#itempackageunitrecord) | 道具礼包中所含各个商品的详细信息。 | | [CurrencyPackageUnitRecord](./#currencypackageunitrecord) | 货币礼包中所含各个货币的详细信息。 | | [ProductType](./#producttype) | 表示商品类型的枚举。 | | [PurchaseType](./#purchasetype) | 表示商品购买类型的枚举。 | | [ProductStatus](./#productstatus) | 表示商品状态的枚举。 | | [CurrencyType](./#currencytype) | 表示货币类型的枚举。 | | [ProductService](./#productservice) | `ProductService` 用于管理与 World 内商品相关的操作。 玩家可通过该服务访问 World 内商品信息并进行购买。 | | [ProductPurchaseButton](./#productpurchasebutton) | 用于管理 World 内商品购买按钮功能的类。 | | [ProductError](./#producterror) | 表示商品相关请求失败原因的错误代码。 | | [OfficialCurrencyBalanceRequest](./#officialcurrencybalancerequest) | 表示用于获取 ZEPETO 官方货币（ZEM）余额的异步请求。 | ## BaseResponse `class` 响应类的基类。 ### 属性 | 名称 | 类型 | 说明 | | --------- | --------- | ------------------------ | | isSuccess | `boolean` | 表示请求的成功状态。成功完成时设置为 true。 | | message | `string` | 描述请求的结果。 | ## BaseRequest `class` · extends `BaseAPIRequest` 以泛型 `TResponse` 作为响应数据的 `BaseRequest` 类。 ### 属性 | 名称 | 类型 | 说明 | | ------------ | ----------- | ----------------------- | | responseData | `TResponse` | 泛型 `TResponse` 类型的响应数据。 | ## ProductListResponse `class` · extends [ProductBaseResponse](./#productbaseresponse) `ProductListResponse` 类提供 API 调用结果以及获取到的商品信息列表。 ### 属性 | 名称 | 类型 | 说明 | | -------- | ------------------------------------- | ------- | | products | [ProductRecord\[\]](./#productrecord) | 商品信息列表。 | ## ProductBaseResponse `class` · extends [BaseResponse](./#baseresponse) 商品相关响应类的基类。 ### 属性 | 名称 | 类型 | 说明 | | --------- | ------------------------------- | --------------- | | ErrorCode | [ProductError](./#producterror) | 获取失败的商品请求的错误代码。 | ## ProductResponse `class` · extends [ProductBaseResponse](./#productbaseresponse) `ProductResponse` 类提供 API 调用结果以及获取到的商品信息。 ### 属性 | 名称 | 类型 | 说明 | | ------- | --------------------------------- | ----- | | product | [ProductRecord](./#productrecord) | 商品信息。 | ## PurchaseResponse `class` · extends [ProductBaseResponse](./#productbaseresponse) `ProductResponse` 类提供 API 调用结果以及购买信息。 ### 属性 | 名称 | 类型 | 说明 | | ----------- | -------- | -------------------- | | userId | `string` | 进行购买的玩家的用户 ID。 | | productId | `string` | 已购买的 World 内商品 ID。 | | price | `number` | 已购买的 World 内商品价格。 | | receiptId | `string` | 该次购买的收据 ID。 | | purchasedAt | `Date` | 购买该 World 内商品的日期和时间。 | ## CurrencyListResponse `class` · extends [ProductBaseResponse](./#productbaseresponse) `CurrencyListResponse` 类提供 API 调用结果以及货币信息列表。 ### 属性 | 名称 | 类型 | 说明 | | ---------- | --------------------------------------- | ------- | | currencies | [CurrencyRecord\[\]](./#currencyrecord) | 货币信息列表。 | ## CurrencyResponse `class` · extends [ProductBaseResponse](./#productbaseresponse) `CurrencyResponse` 类提供 API 调用结果以及货币信息。 ### 属性 | 名称 | 类型 | 说明 | | -------- | ----------------------------------- | ----- | | currency | [CurrencyRecord](./#currencyrecord) | 货币信息。 | ## ProductRecord `class` 商品信息。 ### 属性 | 名称 | 类型 | 说明 | | -------------------- | ------------------------------------------------------------- | ----------------------------------------------- | | productId | `string` | 商品 ID。 | | name | `string` | 商品名称。 | | price | `number` | 商品价格。 | | isPurchased | `boolean` | 表示用户是否已购买该商品，仅适用于非消耗型商品。 | | itemPackageUnits | [ItemPackageUnitRecord\[\]](./#itempackageunitrecord) | 当 `ProductType` 为 `ItemPackage` 时，该商品所含的道具。 | | currencyPackageUnits | [CurrencyPackageUnitRecord\[\]](./#currencypackageunitrecord) | 当 `ProductType` 为 `CurrencyPackage` 时，该商品所含的货币。 | | ProductType | [ProductType](./#producttype) | 返回该商品的 `ProductType`。 | | PurchaseType | [PurchaseType](./#purchasetype) | 返回该商品的 `PurchaseType`。 | | ProductStatus | [ProductStatus](./#productstatus) | 返回该商品的 `ProductStatus`。 | | CurrencyType | [CurrencyType](./#currencytype) | 返回购买该商品所使用的货币类型。 | | currencyId | `string` | 返回购买该商品所使用的货币 ID。 | | currencyName | `string` | 返回购买该商品所使用的货币名称。 | ### 方法 ### GetCurrencySprite `GetCurrencySprite() → Sprite` 返回购买该商品所使用的货币图片。 **返回值：** `Sprite` ## CurrencyRecord `class` 货币信息。 ### 属性 | 名称 | 类型 | 说明 | | ------------------ | --------- | ------------------------------------ | | currencyId | `string` | 货币 ID。 | | name | `string` | 货币名称。 | | isOfficialCurrency | `boolean` | 表示该货币是 ZEPETO 官方货币（ZEM）还是 World 内货币。 | ## ItemPackageUnitRecord `class` 道具礼包中所含各个商品的详细信息。 ### 属性 | 名称 | 类型 | 说明 | | --------- | -------- | ------ | | productId | `string` | 商品 ID。 | | itemName | `string` | 道具名称。 | | quantity | `bigint` | 道具数量。 | ## CurrencyPackageUnitRecord `class` 货币礼包中所含各个货币的详细信息。 ### 属性 | 名称 | 类型 | 说明 | | ------------ | -------- | ------ | | currencyId | `string` | 货币 ID。 | | currencyName | `string` | 货币名称。 | | quantity | `bigint` | 货币数量。 | ## ProductType `enum` 表示商品类型的枚举。 | 名称 | 值 | 说明 | | --------------- | - | -------------- | | Item | 0 | 单个道具的商品。 | | ItemPackage | 1 | 包含多个道具的道具礼包商品。 | | CurrencyPackage | 2 | 包含多种货币的货币礼包商品。 | ## PurchaseType `enum` 表示商品购买类型的枚举。 | 名称 | 值 | 说明 | | ------------- | - | ------- | | Consumable | 0 | 消耗型商品。 | | NonConsumable | 1 | 非消耗型商品。 | ## ProductStatus `enum` 表示商品状态的枚举。 | 名称 | 值 | 说明 | | --------- | - | --------------- | | Active | 0 | 启用状态。 | | InActive | 1 | 停用状态。 | | Forbidden | 2 | 因使用期限到期而被禁用的状态。 | ## CurrencyType `enum` 表示货币类型的枚举。 | 名称 | 值 | 说明 | | ---------------- | - | ---------------- | | OfficialCurrency | 0 | ZEPETO 官方货币（ZEM） | | UserCurrency | 1 | World 内货币。 | ## ProductService `class` `ProductService` 用于管理与 World 内商品相关的操作。 玩家可通过该服务访问 World 内商品信息并进行购买。 ### 事件 | 名称 | 类型 | 说明 | | ---------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | OnPurchaseCompleted (static) | `UnityEvent` | World 内商品购买成功时触发的事件。可添加监听器，监听器会接收 `ProductRecord`（已购买商品的信息）和 `PurchaseResponse`（购买结果信息）实例作为参数。 | | OnPurchaseFailed (static) | `UnityEvent` | World 内商品购买失败时触发的事件。可添加监听器，监听器会接收 `ProductRecord`（尝试购买的商品信息）和 `PurchaseResponse`（失败的购买结果信息）实例作为参数。 | ### 方法 ### GetProductsAsync `static GetProductsAsync(productIds: string[]) → BaseRequest` 该异步方法根据提供的商品 ID 获取 World 内商品列表。 | 参数 | 类型 | 说明 | | ---------- | ---------- | ------------ | | productIds | `string[]` | 要获取的多个商品 ID。 | **返回值：** [BaseRequest\](./#baserequest) — 一个 `BaseRequest` 对象。异步处理完成后，可通过 `responseData` 属性访问 `ProductListResponse` 对象。 ### GetProductAsync `static GetProductAsync(productId: string) → BaseRequest` 该异步方法根据提供的商品 ID 获取 World 内商品信息。 | 参数 | 类型 | 说明 | | --------- | -------- | ---------- | | productId | `string` | 要获取的商品 ID。 | **返回值：** [BaseRequest\](./#baserequest) — 一个 `BaseRequest` 对象。异步处理完成后，可通过 `responseData` 属性访问 `ProductResponse` 对象。 ### PurchaseProductAsync `static PurchaseProductAsync(product: ProductRecord, reason?: string) → BaseRequest` 该异步方法根据提供的商品信息购买 World 内商品。 | 参数 | 类型 | 说明 | | ----------- | --------------------------------- | -------------------------- | | product | [ProductRecord](./#productrecord) | 要购买商品的 `ProductRecord` 实例。 | | reason （可选） | `string` | 对该次购买的说明。 | **返回值：** [BaseRequest\](./#baserequest) — 一个 `BaseRequest` 对象。异步处理完成后，可通过 `responseData` 属性访问 `PurchaseResponse` 对象。 ### PurchaseProductAsync `static PurchaseProductAsync(productId: string, reason?: string) → BaseRequest` 该异步方法根据提供的商品 ID 购买 World 内商品。 | 参数 | 类型 | 说明 | | ----------- | -------- | ---------- | | productId | `string` | 要购买的商品 ID。 | | reason （可选） | `string` | 对该次购买的说明。 | **返回值：** [BaseRequest\](./#baserequest) — 一个 `BaseRequest` 对象。异步处理完成后，可通过 `responseData` 属性访问 `PurchaseResponse` 对象。 ### GetCurrenciesAsync `static GetCurrenciesAsync() → BaseRequest` 用于获取货币列表的异步方法。 处理完成后即可获得货币列表，并可通过 `responseData` 属性访问 `CurrencyListResponse` 对象。 **返回值：** [BaseRequest\](./#baserequest) ### GetCurrencyAsync `static GetCurrencyAsync(currencyId: string) → BaseRequest` 该异步方法根据提供的商品 ID 获取 World 内货币信息。 | 参数 | 类型 | 说明 | | ---------- | -------- | ---------- | | currencyId | `string` | 要获取的货币 ID。 | **返回值：** [BaseRequest\](./#baserequest) — 一个 `BaseRequest` 对象。异步处理完成后，可通过 `responseData` 属性访问 `CurrencyResponse` 对象。 ### OpenPurchaseUI `static OpenPurchaseUI(product: ProductRecord) → void` 该方法用于打开 World 内商品购买 UI。 | 参数 | 类型 | 说明 | | ------- | --------------------------------- | -------------------------- | | product | [ProductRecord](./#productrecord) | 要购买商品的 `ProductRecord` 实例。 | ## ProductPurchaseButton `class` 用于管理 World 内商品购买按钮功能的类。 ### 属性 | 名称 | 类型 | 说明 | | --------- | --------------------------------- | -------------------------------- | | productId | `string` | 获取可供购买的 World 内商品 ID。 | | product | [ProductRecord](./#productrecord) | 获取与 `productId` 关联的 World 内商品信息。 | ### 方法 ### SetProductId `SetProductId(productId: string) → void` 设置可通过该按钮购买的 World 内商品 ID。 | 参数 | 类型 | 说明 | | --------- | -------- | ------ | | productId | `string` | 商品 ID。 | ## ProductError `enum` 表示商品相关请求失败原因的错误代码。 | 名称 | 值 | 说明 | | -------------------------------- | ---- | ------------------------------------------------------------ | | Unknown | -1 | 错误：未知错误。 | | NetworkError | 0 | 错误：与网络问题相关的错误，包括连接中断或连接不稳定。 | | UserCanceled | 1 | 错误：请求已被用户取消。 | | ProductRefreshResponseError | 2 | 错误：请求中的商品元数据无效。 | | ItemPackageProductsResponseError | 3 | 错误：未能获取道具礼包中一个或多个道具的信息。 | | IAPCardError | 4 | 错误：未能获取货币礼包中一个或多个货币的信息。 | | ProductPriceChanged | 4001 | 错误：商品价格不匹配。 | | ProductAlreadyPurchased | 4002 | 错误：该商品已购买。 | | BalanceOfficialCurrencyNotEnough | 4003 | 错误：ZEPETO 官方货币（ZEM）余额不足，无法完成购买。 | | BalanceUserCurrencyNotEnough | 4004 | 错误：World 内货币余额不足，无法完成购买。 | | ProductNotActive | 4005 | 错误：商品未处于启用状态。 | | InvalidCreator | 4006 | 错误：玩家的用户 ID 与 World 创作者的用户 ID 不一致。该错误仅在使用 Unity 编辑器的开发环境中出现。 | ## OfficialCurrencyBalanceRequest `class` · extends [BaseRequest\](./#baserequest) 表示用于获取 ZEPETO 官方货币（ZEM）余额的异步请求。