Skip to main content

Daily Rewards

Daily reward programs bring players back to the game hub. A program is a cycle of reward days: the player claims each day's reward on the hub, and Aghanim delivers the items to your game with the item.add webhook.

You manage programs in your Aghanim account or with the Create Daily Reward and Update Daily Reward API methods.

Program types

There are four program types: basic, schedule, seasonal, and custom.

In basic, schedule, and seasonal programs, Aghanim runs the cycle and decides when each reward opens. The rewards come from the program settings, or from the daily_reward.get webhook when you select one for the program.

In custom programs, your game server runs the cycle. See Custom programs.

If several programs are active at the same time, the hub shows one of them, picked by type in this order: seasonal, custom, schedule, basic.

Placeholder for closed slots

Every program type has a hidden_image_url setting: the image the hub shows on reward slots that are still closed. Set it in the program settings or pass rewards.hidden_image_url to the API. Without it, the hub uses its default placeholder.

Custom programs

In a custom program, your game server controls the whole cycle through the daily_reward.get webhook: the items of each day, the moment the next reward opens, and the start of a new cycle. Aghanim stores the player's claims, delivers the items, and renders the program on the hub. Use it when the reward timing depends on your game logic rather than on the calendar.

Players see only the current reward and the final one. The other slots stay closed until the player gets to them.

Setting up a custom program

  1. Implement the daily_reward.get webhook with the custom response and register it in your Aghanim account with the daily_reward.get event type.
  2. Create a daily reward program of the custom type and select the webhook. The webhook is required. With the API, pass type: "custom" and the webhook_id.
  3. Place the daily reward widget on your game hub page.

A game can have one custom program. Static rewards and mode aren't used by custom programs: the rewards always come from your server.

What players see on the hub

  • Claimed days show the items the player received.
  • The current day's items appear only once the day opens.
  • The final reward is always visible.
  • The current day and the final day show a countdown while they're closed, if your server sent their opening time.
  • All other days stay closed and show the hidden_image_url placeholder.
  • When the whole cycle is claimed, the player sees that every reward is collected, with a countdown to the new cycle.

Anonymous players can't claim rewards. They see the final reward, a countdown on the current day if it hasn't opened yet, and every other slot closed.

How the cycle works

Each time a player opens the widget or claims a reward, Aghanim calls your webhook with the player's progress in the current cycle: the cycle number and the days claimed so far. Your server responds with the current state, which is the cycle number plus the current and final days with their opening times. Aghanim builds the hub view from this response and checks every claim against a fresh one. Aghanim stores the claims, so your server can derive the state from the progress it receives.

When the player claims the final day, respond with the next cycle number and its day 1 straight away. The new cycle starts once that day 1 opens. The webhook reference has the exact rules.

Example: a 7-day cycle

This walkthrough follows one player through a 7-day cycle. The game uses a simple rule: each reward opens 24 hours after the previous claim, and a new cycle opens 24 hours after the final claim. Your rule can be anything, as long as the response describes it through available_at. All times are in UTC.

1. First visit

October 1, 10:00. The player opens the widget for the first time, so the request has no claims:

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

Your server opens day 1 right away. For the final day, it sends the earliest moment day 7 can open if the player claims every day:

{
  "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" }] }
  ]
}

The player sees day 1 open with 100 coins, days 2–6 closed, and the day 7 reward with a countdown.

2. Claiming day 1

October 1, 10:01. The player claims day 1. Aghanim first calls the webhook with the hub.daily_reward_claim trigger and the same progress. Your server returns the same response as in step 1 and doesn't record anything. Day 1 is the current day and it's open, so Aghanim records the claim and sends item.add with context.daily_reward.day_number set to 1.

When the hub refreshes the program, the request includes the claim:

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

Day 2 opens 24 hours after the claim:

{
  "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" }] }
  ]
}

The player sees 100 coins on day 1 and a 24-hour countdown on day 2. The day 2 items stay hidden until it opens.

3. Day 2 opens

October 2, 18:30. The player comes back. Your server returns the same response as in step 2, but its available_at is now in the past, so day 2 is open. The player sees 200 coins and claims them.

4. The final day

The player claims days 3 to 6, the last one on October 6 at 09:00. Day 7 opens 24 hours later. The current day is now the final one, so days has a single element:

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

5. Cycle complete

October 7, 20:00. The player claims day 7, and the next request lists all seven claims. Your server responds with the next cycle right away:

{
  "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" }] }
  ]
}

Day 1 of cycle 2 opens only in 24 hours, so Aghanim keeps cycle 1 on the hub. The player sees all seven rewards collected and a countdown to the new cycle.

6. A new cycle

October 8, 21:00. The request still carries cycle 1 with seven claims, and your server returns the same response as in step 5. This time day 1 is already open, so Aghanim starts cycle 2. The player sees day 1 open with 100 coins, days 2–6 closed, and the final reward. Until the first claim in the new cycle, requests carry { "cycle_number": 2, "claims": [] }.

To reset a cycle midway, for example when the player misses a day, respond the same way: cycle_number + 1 and its day 1. To refuse a claim at any step, return an available_at in the future. See Claims in custom programs.

Need help?
Contact our integration team at [email protected]

On this page