Quick Start Guide

简单介绍电子商务系统功能、核心术语以及电子商务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 Interface (或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_CatalogOfferbIsAvailableForPurchases 属性决定)。要使用这个流程,你的游戏必须要配置好使用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_QueryOwnershipToken API来在游戏客户端代码中生成一个JWT。该JWT可以包含多个目录物品的所有权信息。
  • 对于可消耗的内容(比如游戏内货币): 根据Ecom Web API文档中的指示,在代码中使用一个自定义HTTP请求来在游戏客户端代码中生成一个JWT。该JWT可以包含多个权利的权利信息。

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

验证购买的持续内容(比如DLC)

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

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

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

以下流程用于通过EOS_Ecom_QueryOwnership API验证持续性内容:

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

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

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

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

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

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

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

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

可消耗购买可以通过EOS_Ecom_QueryEntitlementsEOS_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 API,从而在电子商务后端服务中将权利标记为已兑换。