游戏 API 工作流

游戏 API 工作流

游戏 API 使开发者能够将其游戏与 Amazon GameOn 竞赛集成。本页面介绍您应考虑添加到您的游戏中的典型工作流。

先决条件

要注册玩家并进行身份验证,您需要游戏 API 密钥。您可以在管理控制台的游戏设置面板中找到游戏 API 密钥。它在面板中名为“Public API Key”(公有 API 密钥)。请参见下图:

我们建议每个玩家都有自己的客户端密钥。因此,要对玩家进行身份验证,您必须具有三个 .pem 格式的密钥文件:

  • 客户端公有密钥
  • 客户端私有密钥
  • 游戏公有密钥

您可以在管理控制台的 Game Settings (游戏设置) 选项卡中找到游戏公有密钥的值 (参见上图)。您必须生成客户端公有和私有密钥。有关生成这些密钥的信息,请参阅下面的注释。

注册玩家

当您注册新玩家时,系统会将玩家 (及其设备) 添加到 GameOn,进行密钥交换,并返回加密的玩家令牌。

目的

当您注册游戏时,系统会向该游戏分配一个密钥对。但是,我们建议每个玩家都有自己的客户端密钥对,以最大程度地降低玩家可以解密属于另一个玩家的敏感信息的风险。

密钥交换的目的是将客户端公有密钥提供给 GameOn 系统,该系统在未来的响应中使用此密钥来加密敏感信息。

请求

Register Player (注册玩家) 请求启动密钥交换。游戏应用根据游戏公有密钥加密客户端公有密钥并使用请求正文中生成的已加密客户端公有密钥 (encryptedPayload 字段)。

响应

成功的响应消息包含已加密的玩家令牌。玩家令牌是根据您在请求中提供的客户端公有密钥进行加密的。您需要使用客户端私有密钥解密此令牌,然后使用游戏公有密钥重新加密此令牌。存储此令牌以长期使用。您将在玩家所有以后的身份验证调用中发送它。

生成玩家密钥

公有游戏密钥由 GameOn 系统以 base64 编码 DER 格式提供。这又称为 PEM 格式,但没有标头。您可以在密钥周围添加标头/脚注来创建 PEM 格式密钥:

-----BEGIN PUBLIC KEY-----
[KEY TEXT]
-----END PUBLIC KEY-----

许多 openssl 实现将用于密钥生成的“公用指数”设置为 e=3,这是可行的。但是,指数为 65537 被认为更好,因为它在实现中稍微快一点 (请参阅 https://en.wikipedia.org/wiki/Coppersmith%27s_attack)。

使用“PKCS1_v1_5”填充格式来设置公有游戏密钥的格式。如下所述,openSSL 建议对新应用程序使用 OAEP (其他库将它作为默认值),因此应告知开发者。GameOn 系统需要的负载是 base64 编码的 DER 格式的公有密钥,而不只是直接的 DER 二进制格式 (也等效于没有标头的 PEM 格式的密钥)。已加密输出针对 REST 调用再次以 base64 进行编码。

有关使用 Java、C# 和 PHP 的示例代码,请参阅 GameOn 代码示例

流程图

序列图

玩家启动游戏

当玩家启动游戏应用时,游戏将执行以下操作:

  1. 对玩家进行身份验证
  2. 获取竞赛的列表

对玩家进行身份验证

在发送游戏 API 请求之前,应用将调用 Authenticate Player (对玩家进行身份验证) 来创建新的玩家会话。

身份验证请求正文包含 API 在 Register Player (注册玩家) 响应中返回的已加密玩家令牌,然后您可以按照上述说明对其重新加密。

示例请求

POST /players/register
Content-Type: application/json
x-Api-Key: d2d0b961-a5ce-45c7-9dbe-a63061ee229c

示例请求正文

{
  "advertisingId" : "54d8fd8d-e349-49d8-902c-0558365ac22b",
  "encryptedPayload" : "<encrpyted player token>",
  "playerName" : "hunkdory",
  "devicePushNotificationToken" : "392340e57e4a7c646326b1cf96931d97f22ab163f23b3d3605fc5698d3788xx9",
  "deviceOSType" : "iOS",
  "appBuildType" : "development"
}

deviceOSType 是必需的。仅当 deviceOSType 为 iOS 时,appBuildType 才是必需的。

身份验证请求的响应中包括会话 API 密钥和会话 Id,应用必须在每个后续 API 请求中包括它们。

示例响应

{
  "sessionApiKey" : "9a8f707f-a09e-4710-8cf2-7cb5a7b0de57",
  "sessionExpirationDate": 1607760000000,
  "sessionId" : "034721fb-f384-4cb1-a46d-d96cea8198b6"
}

获取竞赛的列表

游戏应用调用 GET Tournaments (获取竞赛),API 将用竞赛列表进行响应。
此请求包括四个可选查询参数,以控制 API 返回的竞赛。游戏应用可以使用查询参数来按竞赛状态 (已上线或即将推出)、按时间段以及按玩家属性筛选“Get Tournament”(获取竞赛) 请求。此外,您还可以设置可包含在响应中的竞赛的最大数量。

成功的响应包含一个竞赛列表。

UI 控件

游戏提供了一个 UI 控件来提供供玩家浏览竞赛的选项。

游戏 API 中的对战和玩家限制

许多相互关联的参数决定竞赛中的玩家、对战和玩家的最大尝试次数。请注意以下定义:

matchesMax:每个竞赛的最大对战数。每个对战复制其父竞赛的开始日期、结束日期和要授予的奖品。具有 10 个对战的竞赛还具有 10 个排行榜、10 个一等奖获得者等。对于每个竞赛单个对战的最简单方案,设置 matchesMax = 1。范围:1 - 10,000。

matchesPerPlayer:单个玩家能够加入竞赛中的多个对战 (对于提供了多个对战的竞赛)。范围:1 - 10,000 或 matchesMax (取较小值)。

playerAttemptsPerMatch:玩家在对战中可以尝试玩的最大次数,通常也是玩家在该对战中可以提交分数的次数。范围:1 - 1,000,000,000

playersPerMatch:对战及其排行榜中的最大玩家数。最大限制:1,000,000,000

玩家选择竞赛

玩家选择浏览竞赛。

UI 控件

游戏需要提供一个用于查看所显示的任何竞赛的详细信息的选项。

如果玩家选择查看竞赛的详细信息,则游戏应用将使用所选竞赛的竞赛 ID 调用 GET Tournament Details (获取竞赛详细信息)。(可选) 您可以指定此玩家的玩家属性。如果玩家没有资格参加竞赛,则 API 会返回 HTTP 200,但“canEnter”字段设置为 false。

游戏应用显示竞赛详细信息。请参阅以下示例:

{
  "canEnter": true,
  "dateEnd" : 1506322800000,
  "dateStart" : 1505335200000,
  "description" : "这无关于雇佣最强的军队或者赢得 PvP 战斗,而是战胜所有困难。",
  "hasAccessKey": false,
  "imageUrl" : "https://s3.amazonaws.com/tournament-prizes/Prize-Item-1.png",
  "matchesPerPlayer" : 100,
  "playerAttemptsPerMatch" : 3,
  "playersPerMatch" : 1000,
  "prizeBundles" : [ {
    "description" : "这个宝箱里面的宝物比银色宝箱里面的更好!",
    "imageUrl" : "https://images-na.ssl-images-amazon.com/images/I/51J6cQ63OJL._AC_US218_.png",
    "prizeIds" : [ "1a3ea1ef-0e8f-4cfc-91fc-bd3fd70a6ab2", "979e4402-bd33-45ef-add9-2b8fb812d912" ],
    "rankFrom" : 1,
    "rankTo" : 3,
    "title" : "金色奖励宝箱"
  } ],
  "title" : "大人物",
  "scoreType" : "Individual",
  "subtitle" : "海盗的战利品",
  "tournamentId" : "00230795-b4bd-40ef-b181-720ee0ec3d80",
  "winType" : "highest"
}

“GET Tournament Details”(获取竞赛详细信息) 响应中包含一系列奖品包。游戏应用可以调用 Get Prize Details (获取奖品详细信息) (对于每个 prizeId) 来向玩家显示他们可以赢得的奖品。

玩家参加竞赛

UI 控件

游戏应用为玩家提供了一个用于参加竞赛的选项。

如果玩家选择参加竞赛,则游戏应用将调用 Enter Tournament (参加竞赛)。系统将在竞赛中搜索开放的对战并在响应中返回对战 ID。

如果竞赛具有特定要求 (或访问密钥),则游戏应用应在请求正文中填充玩家属性字段,以便接受玩家参加竞赛。下面显示了一个示例请求正文:

{
    "playerAttributes" : {
        "status" : "vip",
        "skill" : 1,
        "isActive" : true,
        "gpsCoordinates" : "{\"latitude\": 33.652275, \"longitude\": -117.750495}"
    },
    "accessKey" : "ADEF"
}

玩家启动对战尝试

UI 控件

游戏应用为玩家提供了一个用于启动对战的选项。

当玩家在竞赛中启动对战时,游戏应用将使用“Enter Tournament”(参加竞赛) 响应中的对战 ID 来调用 Enter Match (参加对战)

响应消息正文包含剩余的尝试次数。在每次尝试对战后,此数字会递减。

玩家完成每次尝试

在玩家完成每次尝试后,游戏将显示玩家的分数。游戏应用将调用 Submit Score (提交分数) 来记录分数。

游戏应用还可以调用 Get Match Details (获取对战详细信息) 来获取有关玩家在竞赛中的进度的信息,如玩家的最后一次分数和高分以及剩余尝试次数。

玩家查看排行榜

UI 控件

游戏应用为玩家提供了一个用于查看排行榜的选项。

在竞赛过程中,玩家可以选择查看排行榜。游戏应用使用玩家的对战 ID 调用获取排行榜,并且响应将包含玩家在排行榜中的位置以及优胜玩家。可以在查询中配置获胜玩家的数量。

玩家退出竞赛

UI 控件

游戏应用为玩家提供了一个用于查看对战结果的选项。

当竞赛结束并且已有最终结果时,系统会发送通知。玩家可以选择查看通知,看看他们是否赢得了奖品。

游戏应用发送获取对战详情请求和获取排行榜请求。根据响应中的信息,游戏应用可以显示排行榜、竞赛细节和玩家可以领取的奖品 (如果有)。

玩家领取奖品

UI 控件

游戏应用为玩家提供了一个用于领取奖品的选项。

玩家选择一个、一些或所有可用奖品。游戏应用调用领取奖品,后者返回已领取奖品的列表,以及无法标记为已领取的奖品 ID 列表。