跳至主要内容

每日奖励 Webhook

daily_reward.get Webhook 用于确定玩家从每日奖励方案中获得哪些商品。当方案配置为由 Webhook 驱动时，Aghanim 会调用您的服务器，询问每天（以及额外奖励）应发放哪些商品，并根据您的响应实时生成玩家看到的奖励。

该 Webhook 适用于两类方案：

  • 选择了 Webhook 的基础、排期和季节性方案。您的响应决定商品，周期由 Aghanim 运行。
  • 自定义方案。您的响应还决定每个奖励何时开放、新周期何时开始。有关它们在 Game Hub 上的呈现方式，请参阅每日奖励。

此 Webhook 在以下情况下触发：

  • 玩家在 Game Hub 中打开每日奖励组件时。
  • 玩家领取每日奖励时。

如果您的服务器未响应、返回非 2xx 状态、超时或返回无效的响应体，Aghanim 会回退到方案的静态奖励。但为方案选择 Webhook 会清除这些奖励，因此实际上方案不会显示任何奖励，领取也会失败。自定义方案则完全没有静态奖励。请参阅自定义方案中的错误。

要求

如需接入 Aghanim 的 daily_reward.get Webhook，请按照以下要求配置您的 Webhook 服务器：

  • HTTPS 端点，可接收 POST Webhook 请求。
  • 监听由 Aghanim 生成并 签名 的事件。
  • 使用 2xx 状态码响应，并在 JSON 响应体中描述奖励商品。
  • 尽快响应。响应过慢会降低 Hub 的体验，超时则会导致方案没有奖励。

配置步骤

  1. 为 daily_reward.get Webhook 处理开发一个函数。
  2. 部署您的端点使其可访问。
  3. 进入您的 Aghanim 账户后，依次导航至 游戏 → Webhooks → Add webhook，然后选择 daily_reward.get 事件类型来注册您的端点。
  4. 在每日奖励方案设置中选择该 Webhook，方案即通过它获取商品。自定义方案必须设置 Webhook。
  5. 在您的 Game Hub 页面上放置每日奖励组件，以便玩家打开它并触发 Webhook。

或者，您也可以使用 Create Webhook API 方法在 Aghanim 中注册您的端点。

触发器值

值描述
hub.interact当玩家在 Game Hub 中打开每日奖励组件时。
hub.daily_reward_claim当玩家领取每日奖励时，用于确定要发放的商品。对于自定义方案，这是领取前的预检查。请参阅自定义方案中的领取。
test在 Dashboard 中使用 "Send test event" 时。

有关 daily_reward.get 与其他事件类型的关系，请参阅完整的事件与触发器对照表。

Request Schema

下面是一个 daily_reward.get Webhook 请求示例：

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "daily_reward.get",
  "event_data": {
    "player_id": "2D2R-OP3C",
    "id": "dlrwd_eAeXgQGcaie",
    "key": "season-1",
    "is_anonymous": false
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.interact",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

事件 Schema

键名类型描述
event_idstring阿哈利姆生成的唯一事件标识符。
game_idstring您的游戏在阿哈利姆中的唯一标识符。
event_typestring事件的类型， daily_reward.get 在此情境下。
event_timenumberThe time the event was sent, in Unix epoch time. May differ across duplicate deliveries of the same event.
event_dataEventData包含事件特定数据的字段，其中可能包含用于继承对象的各种键值。
idempotency_keystring|null即使出现重试情况，也能确保 Webhook 操作只执行一次。 可以是 null 具体取决于事件类型。
request_idstring|null如果事件是通过 API 请求触发的，此字段将包含对应的请求 ID。
sandboxboolean标识事件是否来自沙盒测试环境的指示器。
triggerstring|null触发该事件发送的触发器。
transaction_idstring阿哈利姆生成的交易标识符。在同一交易过程中触发的多个事件可能共享相同的交易 ID。
contextEventContext|null事件的相关上下文信息。

EventContext Schema

键名类型描述
orderOrderContext|null与事件相关的订单信息（如果适用）。
playerPlayerContext|null（可选）玩家信息。如需启用，请在webhook设置中选择“添加玩家上下文”。

EventData Schema

键名类型描述
player_idstring用于玩家身份验证的唯一 玩家 ID。
idstring由 Aghanim 生成的唯一每日奖励方案 ID。
keystring|null游戏为每日奖励方案定义的键。
is_anonymousboolean指示当前用户是否未通过身份验证（匿名）。
progressDailyRewardProgress玩家在当前周期中的进度。仅针对自定义方案和已通过身份验证的玩家发送。

DailyRewardProgress Schema

键名类型描述
cycle_numbernumber当前周期的编号，由 Aghanim 分配。从 1 开始。
claimsDailyRewardClaim[]玩家在当前周期中已领取的奖励日。在该周期首次领取之前为空。

DailyRewardClaim Schema

键名类型描述
day_numbernumber已领取的奖励日。
claimed_atnumber领取该奖励日的时间，以 Unix 时间戳（秒）表示。

以下是自定义方案的 event_data 示例，其中玩家已领取第三个周期的第 1 天和第 2 天：

{
  "id": "dlrwd_eAeXgQGcaie",
  "key": "daily",
  "player_id": "2D2R-OP3C",
  "is_anonymous": false,
  "progress": {
    "cycle_number": 3,
    "claims": [
      { "day_number": 1, "claimed_at": 1791100000 },
      { "day_number": 2, "claimed_at": 1791200000 }
    ]
  }
}

对于尚未领取任何奖励的玩家，progress 为 { "cycle_number": 1, "claims": [] }。

匿名玩家没有进度：请求携带 is_anonymous: true，且不包含 progress 块。对于自定义方案，请像对待新玩家一样响应：将 cycle_number 设为 1，并返回带有 available_at 的当前奖励日（通常是第 1 天）以及最终奖励日。匿名玩家无法领取奖励。Hub 会向他们显示最终奖励，其他奖励位保持未开放；如果当前奖励日尚未开放，则显示它的倒计时。

Response Schema

返回 200 OK 并附带 JSON 数据。其结构取决于方案类型：

基础、排期和季节性方案的响应

响应会完全替换方案的奖励：请列出周期中的每一天，如有额外奖励也一并列出。例如，如果您为一个 7 天方案返回第 1–3 天，该方案就只有 3 天。如果省略 extra_reward_items，该方案就没有额外奖励。

键名类型描述是否必需
daysDailyRewardDay[]每个奖励日发放的商品。至少包含一天，按升序排列，并从 1 开始连续编号，中间不能有空缺。是
extra_reward_itemsDailyRewardItem[]额外奖励发放的商品。否

如果某一天的所有 SKU 都与您的商品目录不匹配，该天会从方案中移除。如果这类方案收到了带有 cycle_number 的响应（该字段用于自定义方案），Aghanim 会忽略该响应并将本次调用视为失败，因此方案不会显示任何奖励。

DailyRewardDay Schema

键名类型描述是否必需
day_numbernumber商品所属的奖励日（≥ 1）。是
itemsDailyRewardItem[]该天发放的商品（1–10 个）。是

响应示例

{
  "days": [
    {
      "day_number": 1,
      "items": [
        { "sku": "sword-001", "quantity": 1 },
        { "sku": "coins-pack", "quantity": 500 }
      ]
    },
    {
      "day_number": 2,
      "items": [
        { "sku": "shield-001" }
      ]
    }
  ],
  "extra_reward_items": [
    { "sku": "gem-pack", "quantity": 10 }
  ]
}

自定义方案的响应

返回玩家所在周期的当前状态：周期编号、当前奖励日和最终奖励日。Aghanim 通过 cycle_number 识别自定义响应，因此不含该字段的自定义响应无效。

键名类型描述是否必需
cycle_numbernumber返回 progress.cycle_number 以继续当前周期，或返回 progress.cycle_number + 1 以开始新周期。请参阅自定义方案中的周期。是
daysCustomDailyRewardDay[]一个或两个奖励日，按 day_number 升序排列且不得重复：先是当前奖励日，然后是最终奖励日。如果当前奖励日就是最终奖励日，只需发送这一天。是

不允许使用 extra_reward_items：自定义方案没有额外奖励。

CustomDailyRewardDay Schema

键名类型描述是否必需
day_numbernumber奖励在周期中的位置（≥ 1）。它与日历无关：由您的服务器决定每个奖励何时开放。最终奖励日的编号即周期长度，最大为 365 天。是
available_atnumber该天的开放时间，以 Unix 时间戳（秒）表示。过了这个时间点，该天即开放，玩家可以领取。可以是过去的时间。对于最终奖励日，它只用于驱动最终奖励位上的倒计时。当前奖励日必需
itemsDailyRewardItem[]该天发放的商品（1–10 个）。是

违反上述任一规则的响应都无法通过校验，并按错误处理。请参阅自定义方案中的错误。

响应示例

此示例中的请求于 1791300000 到达，此时第 1 天和第 2 天已领取。第 3 天在一小时后开放，最终奖励日第 7 天在其后四天开放。

{
  "cycle_number": 3,
  "days": [
    {
      "day_number": 3,
      "available_at": 1791303600,
      "items": [{ "sku": "coins", "quantity": 500 }]
    },
    {
      "day_number": 7,
      "available_at": 1791649200,
      "items": [
        { "sku": "coins", "quantity": 5000 },
        { "sku": "boost" }
      ]
    }
  ]
}

DailyRewardItem Schema

键名类型描述是否必需
skustring作为奖励发放的商品 SKU。必须与您商品目录中的 SKU 匹配。是
quantitynumber|null商品数量。省略时使用该商品的默认数量。否
metadataobject|null商品的自定义键值对，用于支持您这边的额外逻辑。否
备注

与游戏在 Aghanim 中的商品目录不匹配的 SKU 会被静默忽略。

自定义方案中的周期

自定义方案的每个请求都携带 progress.cycle_number。返回相同的编号即继续当前周期，返回该编号加一即开始新周期。

玩家领取最终奖励日后，请立即返回下一个周期：cycle_number + 1，以及带有 available_at 的第 1 天。在该时间点之前，玩家会看到已完成的周期和倒计时。第 1 天开放后，Aghanim 开始新周期，后续请求会携带新的 cycle_number 和空的 claims。如需中途重置周期，也以同样的方式响应。

只有同时满足以下所有条件时，新周期才会开始：

  • 响应中的 cycle_number 比 progress.cycle_number 大 1。
  • 玩家在当前周期中至少领取过一天。
  • 新周期第 1 天的 available_at 已过。

切换之后，请求会携带新的编号，因此再次返回该编号会继续当前周期。

7 天周期示例结合请求和响应完整演示了一个周期。

自定义方案中的领取

玩家领取某一天的奖励时，Aghanim 会以 hub.daily_reward_claim 触发器调用 Webhook。这是一次预检查：照常返回当前状态，不要在您这边记录这次领取。请求中不会说明玩家领取的是哪一天。

只有根据这次新的响应，该天是当前奖励日且其 available_at 已过，玩家才会获得奖励。随后 Aghanim 记录这次领取，并通过 item.add Webhook 发放商品，其中 context.daily_reward.day_number 为所领取的奖励日。这次领取也会出现在后续请求的 progress.claims 中。

如需拒绝领取，请返回一个未来的 available_at，或返回另一个当前奖励日。

自定义方案中的错误

如果您的服务器返回错误、返回无效的响应体，或未在 10 秒内响应，领取就会失败，玩家什么也得不到。自定义方案不会回退到静态奖励。如果这种情况发生在玩家打开组件时，Hub 将无法显示奖励日。

需要帮助吗？请通过 integration@aghanim.com 联系我们的集成团队。

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

On this page