跳至主要内容

每日奖励

每日奖励方案能吸引玩家回到 Game Hub。一个方案就是由若干奖励日组成的周期：玩家在 Hub 上逐日领取奖励，Aghanim 通过 item.add Webhook 将商品发放到您的游戏中。

您可以在 Aghanim 账户中管理方案，也可以使用 Create Daily Reward 和 Update Daily Reward API 方法。

方案类型

共有四种方案类型：basic、schedule、seasonal 和 custom。

在 basic、schedule 和 seasonal 方案中，由 Aghanim 运行周期并决定每个奖励的开放时间。奖励来自方案设置；如果您为方案选择了 daily_reward.get Webhook，则来自该 Webhook。

在 custom 方案中，由您的游戏服务器运行周期。请参阅自定义方案。

如果同时有多个方案处于启用状态，Hub 只会显示其中一个，并按以下类型顺序选择：seasonal、custom、schedule、basic。

未开放奖励位的占位图

每种方案类型都有 hidden_image_url 设置，即 Hub 在尚未开放的奖励位上显示的图片。您可以在方案设置中配置，或通过 API 传入 rewards.hidden_image_url。未设置时，Hub 使用默认占位图。

自定义方案

在自定义方案中，您的游戏服务器通过 daily_reward.get Webhook 控制整个周期：每天的商品、下一个奖励的开放时间，以及新周期的开始。Aghanim 负责保存玩家的领取记录、发放商品，并在 Hub 上渲染方案。当奖励的发放时间取决于您的游戏逻辑而不是日历时，请使用自定义方案。

玩家只能看到当前奖励和最终奖励。其他奖励位在玩家进行到之前都保持未开放状态。

设置自定义方案

  1. 实现返回自定义响应的 daily_reward.get Webhook，并在您的 Aghanim 账户中以 daily_reward.get 事件类型注册该 Webhook。
  2. 创建自定义类型的每日奖励方案并选择该 Webhook。Webhook 为必选项。使用 API 时，请传入 type: "custom" 和 webhook_id。
  3. 在您的 Game Hub 页面上放置每日奖励组件。

一个游戏只能有一个自定义方案。自定义方案不使用静态奖励和 mode：奖励始终来自您的服务器。

玩家在 Hub 上看到的内容

  • 已领取的奖励日显示玩家获得的商品。
  • 当前奖励日的商品要等该日开放后才会显示。
  • 最终奖励始终可见。
  • 如果您的服务器发送了开放时间，当前奖励日和最终奖励日在未开放期间会显示倒计时。
  • 其他所有奖励日都保持未开放状态，并显示 hidden_image_url 占位图。
  • 整个周期都领取完毕后，玩家会看到所有奖励均已领取，以及距新周期开始的倒计时。

匿名玩家无法领取奖励。他们能看到最终奖励；如果当前奖励日尚未开放，还能看到它的倒计时；其余奖励位均为未开放状态。

周期的运作方式

每当玩家打开组件或领取奖励时，Aghanim 都会调用您的 Webhook，并附带玩家在当前周期中的进度：周期编号和目前已领取的奖励日。您的服务器返回当前状态，即周期编号，以及当前奖励日和最终奖励日及其开放时间。Aghanim 根据该响应构建 Hub 视图，并在每次领取时用一次新的响应进行校验。Aghanim 会保存领取记录，因此您的服务器可以根据收到的进度推算出当前状态。

玩家领取最终奖励日后，请立即返回下一个周期编号及其第 1 天。新周期在该第 1 天开放时开始。具体规则请参阅 Webhook 参考。

示例：7 天周期

本示例跟随一位玩家走完一个 7 天周期。游戏采用一条简单规则：每个奖励在上一次领取 24 小时后开放，新周期在领取最终奖励 24 小时后开放。您可以使用任何规则，只要响应通过 available_at 体现出来即可。所有时间均为 UTC。

1. 首次访问

10月1日 10:00。玩家首次打开组件，因此请求中没有领取记录：

"progress": { "cycle_number": 1, "claims": [] }

您的服务器立即开放第 1 天。对于最终奖励日，服务器发送的是玩家每天都领取时第 7 天最早的开放时间：

{
  "cycle_number": 1,
  "days": [
    { "day_number": 1, "available_at": 1790848800, "items": [{ "sku": "coins", "quantity": 100 }] },
    { "day_number": 7, "available_at": 1791367200, "items": [{ "sku": "coins", "quantity": 5000 }, { "sku": "boost" }] }
  ]
}

玩家看到第 1 天已开放，奖励为 100 金币；第 2–6 天未开放；第 7 天的奖励显示倒计时。

2. 领取第 1 天

10月1日 10:01。玩家领取第 1 天。Aghanim 首先以 hub.daily_reward_claim 触发器和相同的进度调用 Webhook。您的服务器返回与第 1 步相同的响应，不做任何记录。第 1 天是当前奖励日且已开放，因此 Aghanim 记录这次领取，并发送 item.add，其中 context.daily_reward.day_number 为 1。

Hub 刷新方案时，请求中会包含这次领取：

"progress": {
  "cycle_number": 1,
  "claims": [{ "day_number": 1, "claimed_at": 1790848860 }]
}

第 2 天在领取 24 小时后开放：

{
  "cycle_number": 1,
  "days": [
    { "day_number": 2, "available_at": 1790935260, "items": [{ "sku": "coins", "quantity": 200 }] },
    { "day_number": 7, "available_at": 1791367260, "items": [{ "sku": "coins", "quantity": 5000 }, { "sku": "boost" }] }
  ]
}

玩家看到第 1 天领取的 100 金币，以及第 2 天的 24 小时倒计时。第 2 天的商品在开放前保持隐藏。

3. 第 2 天开放

10月2日 18:30。玩家再次访问。您的服务器返回与第 2 步相同的响应，但其中的 available_at 已经是过去的时间，因此第 2 天已开放。玩家看到 200 金币并领取。

4. 最终奖励日

玩家依次领取了第 3 至第 6 天，最后一次是在 10月6日 09:00。第 7 天在 24 小时后开放。此时当前奖励日就是最终奖励日，因此 days 只包含一个元素：

{
  "cycle_number": 1,
  "days": [
    { "day_number": 7, "available_at": 1791363600, "items": [{ "sku": "coins", "quantity": 5000 }, { "sku": "boost" }] }
  ]
}

5. 周期完成

10月7日 20:00。玩家领取第 7 天，下一次请求会列出全部七条领取记录。您的服务器立即返回下一个周期：

{
  "cycle_number": 2,
  "days": [
    { "day_number": 1, "available_at": 1791489600, "items": [{ "sku": "coins", "quantity": 100 }] },
    { "day_number": 7, "available_at": 1792008000, "items": [{ "sku": "coins", "quantity": 5000 }, { "sku": "boost" }] }
  ]
}

周期 2 的第 1 天要在 24 小时后才开放，因此 Aghanim 在 Hub 上继续显示周期 1。玩家看到全部七个奖励均已领取，以及距新周期开始的倒计时。

6. 新周期

10月8日 21:00。请求仍然携带周期 1 和七条领取记录，您的服务器返回与第 5 步相同的响应。这一次第 1 天已经开放，因此 Aghanim 开始周期 2。玩家看到第 1 天已开放，奖励为 100 金币；第 2–6 天未开放；以及最终奖励。在新周期中首次领取之前，请求都携带 { "cycle_number": 2, "claims": [] }。

如需中途重置周期（例如玩家错过了某一天），也以同样的方式响应：返回 cycle_number + 1 及其第 1 天。如需在任一步骤拒绝领取，请返回一个未来的 available_at。请参阅自定义方案中的领取。

需要技术支持？
联系我们的集成技术团队： [email protected]

On this page