跳至主要内容

无密码授权

本指南说明如何通过您的游戏应用实现玩家授权，让玩家无需手动输入玩家 ID 即可无缝访问游戏枢纽。

Webhook general flow image
Webhook general flow image

流程的两种发起方式

同一个 用户授权 端点支持两种方式，选择哪一种决定了是否需要 nonce：

  • 由枢纽发起（二维码 / 登录按钮）。 玩家位于游戏枢纽中；游戏枢纽显示二维码或登录按钮，生成一个 nonce，并通过以该 nonce 为键的 WebSocket 等待登录。下文逐步介绍的就是这一流程。
  • 由游戏发起（"前往枢纽"按钮）。 玩家从您的游戏应用开始，您将其以已授权状态送入枢纽。使用同一个 S2S 调用，但省略 nonce，并由您自己打开返回的 authorization_url。请参阅 由游戏发起的登录。

前提条件

  • 用于请求身份验证的活跃服务器到服务器 (S2S) API Key。
  • 在阿哈利姆控制台的 Customization → Login 中配置的 Deep Link URL（见下文）。仅由枢纽发起的流程需要。

Deep Link URL 是玩家点击登录按钮时游戏枢纽打开的地址。请在阿哈利姆控制台的 Customization → Login → Deep Link URL 中进行设置。

这与 游戏 → 枢纽深层链接 方向相反：在那里，您的游戏打开一个进入枢纽的链接（/go/login?player_id=…）；而在这里，枢纽打开一个进入您游戏的链接来授权玩家。

游戏枢纽会自动在此 URL 后附加 after_auth 和 nonce 查询参数，您无需自行添加占位符。例如，配置的值 https://your-game-server.com/authorize-player 在枢纽打开时会变为 https://your-game-server.com/authorize-player?after_auth=open_authorization_url&nonce=<value>。您在配置的 URL 中包含的任何固定查询参数都会保留。

优先使用 https App Link / Universal Link，而不是自定义 scheme

请使用由您自己的域名处理的 https:// Android App Link / iOS Universal Link（例如 https://your-game-server.com/authorize-player），而不是 mygame://authorize-player 这样的自定义 scheme。

当游戏应用未安装时，这一选择就很重要，例如玩家在移动浏览器中打开枢纽：

  • 自定义 scheme（mygame://…）没有操作系统层面的回退。如果设备上没有任何应用处理该 scheme，浏览器什么也不做，玩家会一直停留在加载动画上。您的 apple-app-site-association 和 assetlinks.json 文件不适用于自定义 scheme。
  • https App Link / Universal Link 会自动回退：已安装应用时由操作系统打开应用，否则浏览器会正常加载该 https URL。将该 URL 指向您服务器上的一个端点，在应用缺失时把玩家重定向到您希望的位置（例如网页商店），这样玩家就不会卡住。

要启用 App Links / Universal Links，请在 Deep Link URL 所用的域名上托管 assetlinks.json（Android）和 apple-app-site-association（iOS），并让您的应用声明对应的路径。

当玩家点击登录按钮时，游戏枢纽会打开附加了 after_auth 和 nonce 的 Deep Link URL。URL 将采用以下格式：

https://your-game-server.com/authorize-player?after_auth=open_authorization_url&nonce=<value>

这里，<value> 是游戏枢纽为每个授权请求生成的唯一字符串，after_auth 告诉游戏客户端在 第 4 步 中该做什么。

游戏客户端（或在应用未安装、无法处理 https App Link 时由您的服务器）必须拦截深层链接，并按名称而不是按位置从 URL 中读取 nonce 和 after_auth。此 nonce 将用于向游戏后端的授权请求。

第 2 步：将授权请求转发到游戏后端

玩家启动授权会话后，游戏客户端应向游戏后端发送授权请求。

第 3 步：向阿哈利姆发送授权请求

收到游戏客户端的请求后，游戏后端必须使用 用户授权 端点向阿哈利姆 API 发送 POST 请求。在请求中包含以下参数：

参数描述是否必需
player_id要授权的玩家唯一标识符。是
nonce游戏枢纽提供的唯一字符串。由枢纽发起的流程中必需；由游戏发起的登录 中请省略。视情况
redirect_path要将玩家重定向到的游戏枢纽页面。否
player_info首次授权时写入的可选玩家资料。可包含 name、avatar_url、attributes 和 custom_attributes。否

nonce 将授权与正在等待的枢纽会话关联起来，正是它让显示二维码 / 登录按钮的枢纽能够通过 WebSocket 完成登录。当您的游戏自己打开 authorization_url 时请省略它（请参阅 由游戏发起的登录）。

请求示例

curl --request POST \
  --url https://api.aghanim.com/s2s/v1/users/authorize \
  --header 'Authorization: Bearer YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "player_id": "2D2R-OP3C",
    "nonce": "N2Q3Y2MGI6bQ",
    "player_info": {
      "name": "Han Solo",
      "avatar_url": "https://example.com/han.png",
      "attributes": { "hard_currency_amount": 500 },
      "custom_attributes": { "faction": "rebel" }
    }
  }'

响应示例

{
  "authorization_url": "https://your-game-hub/go/login?token=dXNyX...FTV0xqTWg&nonce=N2Q3Y2MGI6bQ"
}

第 4 步：将玩家重定向到授权 URL

游戏后端收到来自阿哈利姆的 authorization_url 后，应将该 URL 传回游戏客户端。游戏客户端应启动默认浏览器并打开授权 URL。此操作完成玩家在游戏枢纽上的授权。

只有当登录是从添加到 iOS 主屏幕的游戏枢纽发起时，游戏枢纽才会发送 after_auth=prompt_open_pwa；其他所有登录都会收到 open_authorization_url。对于 prompt_open_pwa，请不要打开授权 URL，而是显示一条消息，请玩家返回游戏枢纽应用：应用会自行完成登录。

由游戏发起的登录

当玩家从您的游戏应用开始，而您希望将其以已登录状态直接送入枢纽（例如"前往枢纽"按钮），而不是由枢纽打开您的应用时，请使用此方式。它使用同一个 用户授权 端点，与上述流程有两点不同：跳过深层链接拦截（第 1–2 步），并省略 nonce。

  1. 玩家点击游戏内的按钮。
  2. 您的游戏后端仅使用 player_id（以及可选的 redirect_path）调用 POST /s2s/v1/users/authorize，不带 nonce。
  3. 阿哈利姆返回形如 https://your-game-hub/go/login?token=… 的 authorization_url。
  4. 将该 URL 传回游戏客户端，并在设备的默认浏览器中打开。URL 中的 token 会让玩家登录枢纽。

注意：

  • 这一方向不需要配置 Deep Link URL，并且无论启用了哪些网页登录方式都能正常工作，您无需在枢纽上启用 "Login with Player Id" 方式。这样可以把枢纽自身的登录界面限制为单一方式（例如二维码），同时仍能直接从游戏中让玩家登录。
  • 由于没有枢纽会话在 WebSocket 上等待，也就没有需要用 nonce 关联的对象，以 nonce 为键的 拒绝授权 调用也不适用。如果您的游戏判定某个玩家不能登录，只需不打开 authorization_url 即可。

处理授权失败

游戏并不总能授权玩家。例如，玩家尚未达到访问游戏枢纽所需的等级，或账号受到限制。在这些情况下，请告知阿哈利姆登录无法继续，以免玩家一直停留在加载动画上等待。

拒绝授权请求

当游戏后端判定登录无法继续时，使用 拒绝授权 端点向阿哈利姆 API 发送 POST 请求。请包含您在授权深层链接中收到的同一个 nonce：

参数描述是否必需
nonce游戏枢纽提供的唯一字符串，取自授权深层链接。是
reason授权无法继续的原因。取值为 not_eligible（玩家不满足访问枢纽的条件）、banned 或 rejected（通用拒绝）之一。是

请求示例

curl --request POST \
  --url https://api.aghanim.com/s2s/v1/users/authorize/reject \
  --header 'Authorization: Bearer YOUR_S2S_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "nonce": "N2Q3Y2MGI6bQ",
    "reason": "not_eligible"
  }'

响应示例

{
  "error_url": "https://your-game-hub/error?message_code=auth_via_game.not_eligible"
}

向玩家显示错误

如何呈现失败由游戏决定：

  • 在游戏客户端中。 如果您在游戏自身的界面中显示错误，则无需进一步操作，可以忽略 error_url。
  • 在游戏枢纽上。 如果您希望在浏览器中显示错误，请像成功时处理 authorization_url 一样，将 error_url 传回游戏客户端并在默认浏览器中打开。游戏枢纽随后会向玩家显示相应的错误消息。

需要技术支持？
联系我们的集成技术团队： integration@aghanim.com

On this page