电子商务快速入门

简单介绍电子商务系统功能、核心术语以及电子商务API的常见用例。

阅读时间10分钟

电子商务概览

Epic Games商城提供了一系列的电子商务功能，可以让你管理与你的游戏相关的可购买或可兑换的物品，比如可下载内容（DLC）或者虚拟货币。该系统设有层级结构，所以你可以优化产品售卖时的各个包体。一下信息将会介绍该系统，罗列核心术语并提供常见的用例来解释如何使用电子商务API来支持游戏内和后端的功能。

请参阅API参考以获取关于电子商务API的更多信息。

电子商务配置示例和术语

为了展示Epic Games商城的电子商务功能，请查看以下的配置示例：

图1. 产品电子商务配置示例

在这个示例中，产品（My Game）配有三个 沙盒：Dev、Stage以及Live。这些沙盒各自都有自己的电子商务配置，由以下一个或多个组成：

  • 目录商品（Catalog offers）: 一个目录商品 (也称为商品（Offer）) 由一个目录物品和一个相关联的价格（价格可以为0）配对而成。用户可以在Epic Games商城中购买商品。用户购买商品时，后端服务会根据商品中包含的每个物品来向用户颁发 entitlement 。

    • 注意： 权利（entitlement）可以是用户在Epic Games商城基础结构内所拥有的任何物品。一个权利可以允许用户访问一个或者多个目录物品。

  • 目录物品（Catalog items）: 一个目录物品（也称为 audience）可以表示一个完整的游戏、游戏内货币或者武器皮肤一类的虚拟物品，也可以是任何类型的课下载内容。服务会根据目录物品来定义如何给用户授权。一个权利直接对应一个目录物品，从而对应额外目录物品的所有权。

    • 提示： 目录物品可以通过Epic Games商城的动态打包功能来进行配置，从而可以权利其它目录物品。通过这个功能，你可以持续地更新关联的商品，比如可以让拥有季票的用户在新DLC发布时轻易获得所有权。

  • 库物品（Library items）: 一个库物品（也称为游戏物品（game item））是一种目录物品。Epic Games商城的基础结构用它来配置该目录物品的额外属性，比如 artifact ID或者云存档配置。库物品永远都链接到目录物品。

    • 注意： 构件（Artifacts）代表你的游戏的可下载或者可游玩内容，比如游戏客户端和DLC。构件与库物品链接。你可以配置指定哪个二进制文件与构件链接，从而决定Epic Games启动器所下载和安装的内容。二进制文件通过BuildPatch Tool BuildPatch Tool来上传。

目录商品和目录物品通过Epic在线服务SDK的Ecom接口（或Web API） 来公开，可以用于检索你的产品中的全部目录商品和物品、显示目录商品的游戏内检查流程，以及针对目录物品和权利来检索所有权信息。

在示例配置中，我们在产品的Live沙盒中有四个商品：

  • 基础游戏商品（Base game offer）：游戏基础版本的目录商品。基础游戏商品是一个持续的购买，意味着玩家在购买后会永久拥有该游戏。该商品包含一个目录物品，目录物品又包含以下子级库物品：

    • 基础游戏物品（Base game item）：游戏基础版本的目录物品。该目录物品用于验证基础游戏的所有权，如 下文 中的用例所示。
    • 基础游戏库物品（Base game library item）: 用于配置基础游戏构件、云存档游戏配置，或者其它游戏属性的目录物品。

  • 豪华游戏商品（豪华版游戏 offer）: 游戏豪华版本的目录商品。该商品是一个持续的购买，并且包含以下目录内容：

    • 豪华游戏物品（豪华版游戏 item）: 游戏豪华版本的目录物品，可以用于验证该版本的所有权。豪华版游戏物品没有链接到其自己的库物品，而是链接到了基础游戏物品（如上所述）和DLC物品（如下所述）。

  • DLC商品（DLC offer）: 游戏DLC的目录商品；该商品是一个持续的购买。

    • DLC物品（DLC item）: 游戏DLC的目录物品。该目录物品用于验证DLC的所有权。
    • DLC库物品（DLC library item）: 用于配置DLC构件或者其它属性的目录物品。

  • 100游戏币 商品: 100个游戏币的目录商品。该购买是可消耗的，意味着玩家可以多次购买该商品，玩家可以使用它填充游戏内的消耗品。

    • 100游戏币物品: 100游戏币的目录物品。该目录物品用于接收商品的额外信息。然而，它不用于验证所有权，因为对应的商品是一个可消耗的购买。

注意： 消耗品不能通过购买另一个商品来获取。也就是说，如果你想要让豪华版游戏附加赠送玩家100游戏币，你需要使用游戏内的逻辑来将游戏币提供给玩家，100游戏币商品将不会显示在豪华版游戏的 "包含商品（Included offers）" 部分。

电子商务API用例

以下小节提供常见用例来介绍电子商务API如何用于支持游戏内或后端的功能。

在游戏内显示目录商品用于购买

要在游戏内显示目录商品供用户购买，需要结合Epic在线服务SDK来执行以下流程。

  1. 如 身份验证接口文档中所指示的使用 EOS_Auth_Login 来验证用户身份。通常情况下这是通过Epic Games启动器提供的ExchangeCode完成的，如这里所示。
  2. 根据 Ecom Interface 文档，使用 EOS_Ecom_QueryOffers API来读取可用的目录商品列表。根据描述的样式来确定商品数量并从SDK缓存中将商品复制到你自己的集合中。
    • 在上面的示例配置中，我们会读取以下商品列表：
      • 基础游戏商品
      • 豪华版游戏商品
      • DLC商品
      • 100游戏币商品
  3. 使用 EOS_Ecom_CatalogOffer 集合来读取商品细节，比如本地化的标题和描述、价格，以及促销信息。商品信息还会说明商品是否可供购买，以及当前用户是否已经购买。

现在你可以使用已有的信息来在游戏内展示商品，并且显示一个按钮，让用户购买可用商品（由 EOS_Ecom_CatalogOffer 的 bIsAvailableForPurchases 属性决定）。要使用这个流程，你的游戏必须要配置好使用Epic在线服务社交覆层。

  1. 按照电子商务接口文档中所描述的，使用EOS_Ecom_Checkout API，并且根据用户想要购买的商品输入每个目录商品的ID。
  2. 按照电子商务接口文档中所描述的，使用 EOS_Ecom_CheckoutCallbackInfo 中返回的 TransactionId 来判断交易是否成功。

使用 EOS_Ecom_Checkout API 进行的交易可以是持续性的，也可以是可消耗的。要了解更多，请参考以下情景来按需验证购买。

使用你自己的后端服务来安全地验证购买

推荐的验证购买方式是通过你自己的后端服务，这样便不会受到用户的恶意行为影响。如果你没有定制的后端服务来应用这个验证，请参考用例验证购买的持续内容 和 验证并补充可消耗购买来了解客户端侧的验证方法。

要通过你自己的后端服务进行验证，请使用以下利用电子商务Web API的方法之一：

直接验证

直接验证（Direct Verification）指的是直接使用访问令牌从你的后端服务对电子Web API进行调用。

  1. 按照身份验证Web API文档中的指示来请求一个访问令牌，用于电子商务Web API。
  2. 要验证持续性的购买，使用电子商务Web API API。要验证并获取可消耗的购买，使用权利枚举和 兑换API。

基于令牌的验证

基于令牌的验证（Token-based verification）指的是验证由游戏客户端生成的JSON Web令牌 (JWT) 的真实性，该令牌会输送到你的后端服务。通过这种方式，你的后端服务仅需要读取公用密钥一次（或者直到该密钥失效）便可以验证由游戏客户端生成的多个令牌。

  • 对于持续性的内容（比如DLC）：根据电子商务接口文档中的指示，使用EOS_Ecom_QueryOwnershipTokenAPI来在游戏客户端代码中生成一个JWT。该JWT可以包含多个目录物品的所有权信息。
  • 对于可消耗的内容（比如游戏内货币）: 根据Ecom Interface文档中的指示，在代码中使用EOS_Ecom_QueryEntitlementTokenAPI来在游戏客户端代码中生成一个JWT。该JWT可以包含多个权利的权利信息。

如上所述生成JWT之后，将JWT输送到你的后端服务。然后，将令牌解码并且按照电子商务Web API文档中的指示验证令牌是否有效。

验证购买的持续内容（比如DLC）

推荐你使用自己的后端服务来验证玩家购买，因为这样不易受到用户恶意行为的影响。请参阅通过自己的后端服务验证购买，了解详情。

要验证游戏客户端中的持续内容，使用EOS_Ecom_QueryOwnershipAPI。该API通过输入一组目录物品ID来验证所有权。该所有权验证会自动识别目录物品之间的关系。

在示例配置中，用户可以购买豪华版游戏商品或者基础游戏商品，两者都能够通过基础游戏物品验证，因为这两个商品都和基础游戏物品相关联。类似地，购买了豪华版游戏商品之后便能够通过DLC物品验证，因为该目录商品也与豪华版游戏商品相关联。

以下流程用于通过EOS_Ecom_QueryOwnershipAPI验证持续性内容：

  1. 如 身份验证接口文档中所指示的使用 EOS_Auth_Login 来验证用户身份。通常情况下这是通过Epic Games启动器提供的ExchangeCode完成的，如这里所示。

  2. 根据Ecom Interface文档，使用EOS_Ecom_QueryOffersAPI来读取可用的目录商品列表。根据描述的样式来确定商品数量并从SDK缓存中将商品复制到你自己的集合中。

  3. 按照电子商务接口文档中的指示，遍历商品集合来找到它们关联的目录物品（EOS_Ecom_CatalogItem）。

    • 在我们的示例配置中，我们会获取每个目录商品中包含的目录物品：
      • 基础游戏商品 → 基础游戏物品
      • 豪华版游戏商品 → 豪华版游戏物品
      • DLC商品 → DLC物品
      • 100游戏币商品 → 100游戏币物品

    目前有两种方法可以验证这些物品的所有权：直接使用SDK，或者生成一个JSON Web令牌 (JWT)。在电子商务接口文档中，这二者被称为 "直接" 和 "基于令牌的" 方法。以下是 "直接" 方法所需的步骤，但是你可以在该指南的 使用你自己的后端服务来安全地验证购买小节来找到更多关于 "基于令牌的" 方法的信息。

  4. 使用EOS_Ecom_QueryOwnershipAPI，通过目录物品ID来检索用户的所有权信息。 对于每个输入的目录物品ID，回调会包含一个数组的EOS_Ecom_ItemOwnership成员，带有对应的EOS_Ecom_Owned或者EOS_Ecom_NotOwned数值。

  5. 在上面的示例配置中，如果一个用户购买了豪华版游戏商品，那么基础游戏物品、豪华版游戏物品，以及DLC物品都会被标记为 EOS_Ecom_Owned。

验证并补充可消耗购买（比如游戏内货币）

可消耗购买可以通过EOS_Ecom_QueryEntitlements和EOS_Ecom_RedeemEntitlements API分别进行验证和使用。这些API可以验证用户是否购买（一次或者多次购买）了物品，并且可以追踪是否已经获取游戏中对应的消耗品。EOS_Ecom_QueryEntitlements API接收 EntitlementNames，等用于 CatalogItem ID。

在示例配置中，一个用户可以购买100游戏币商品一次或者多次，可以兑换权限来获取硬币商品并添加到玩家的账号中。

EOS_Ecom_QueryEntitlements API 不 应该用于验证已购买的持续性内容，因为它不会考虑关联的目录物品间的关系。在我们的示例配置中，用户可以购买豪华版游戏商品，其中包含基础游戏物品以及DLC物品。在这种情况下， EOS_Ecom_QueryEntitlements API只会返回豪华版游戏物品的权利，而忽略与基础游戏物品和DLC物品的关联。

  1. 如 身份验证接口文档中所指示的使用EOS_Auth_Login来验证用户身份。通常情况下这是通过Epic Games启动器提供的 ExchangeCode 完成的，如这里所示。
  2. 如果你知道要检索的权利名称，请执行步骤3。否则请按照上文的验证购买的持续内容 （比如DLC）用例小节中介绍的步骤1和2来为每个适用的目录物品读取ID。读取目录物品ID便相当于该流程所需要的权利名称。
  3. 按照电子商务接口 文档中的指示来调用EOS_Ecom_QueryEntitlements，这样会将用户权利填充入SDK缓存。然后，将权利从缓存中复制进你自己的集合。
    • 注意： 默认情况下，EOS_Ecom_QueryEntitlements API会移除已经兑换过的权利。
  4. 从缓存复制的每一个EOS_Ecom_Entitlement都代表用户进行过的一次购买，并且包含一个独有的 EntitlementId。这些ID可以用于在游戏代码中兑换购买。
    • 在示例配置中，如果用户购买了100游戏币商品两次，那么该用户会拥有两个单独的 EOS_Ecom_Entitlement ，每个都有各自的 EntitlementId。
  5. 在游戏中兑换权利后（比如玩家账号中加入了游戏币），请按照电子商务接口文档中的指示使用EOS_Ecom_RedeemEntitlements，从而在电子商务后端服务中将权利标记为已兑换。