Unity SDK · Live Events

Fetch scheduled events with rewards, banner art and per-player claim state. The server enforces single-claim across devices, so your client code never has to track who claimed what.

Overview

KalmForge.LiveEvents is a thin async wrapper around two endpoints. Each Event arrives with the player's claimed flag pre-resolved and copy translated to the requested language.

Note

Live Events is a Studio tier capability. The SDK early-outs to an empty list when the player's plan does not include it.

Fetching active events

exampleC#

1var events = await LiveEvents.GetActiveAsync(
2    lang:     Localization.CurrentLanguage,
3    country:  "US",
4    platform: "ios"
5);
6foreach (var e in events) {
7    Debug.Log($"{e.resolved.name}  ends {e.ends_at}  claimed={e.claimed}");
8}

Claiming a reward

exampleC#

1var result = await LiveEvents.ClaimAsync(events[0].id);
2if (result.ok) {
3    GrantRewards(result.rewards_json);          // your parser, raw JSON
4} else if (result.already_claimed) {
5    Debug.Log("Already claimed on another device");
6}

Reading rewards

rewards_json is delivered as a raw JSON string because rewards are arbitrary shape. Parse with the JSON library of your choice:

exampleC#

1[System.Serializable]
2class Rewards { public int coins; public string item_id; public int qty; }
3
4var r = JsonUtility.FromJson<Rewards>(events[0].rewards_json);

API reference

LiveEvents - static API

Name	Type	Description
GetActiveAsync(lang?, country?, platform?)	Task<List<Event>>	Active events for the current player with translated copy and per-player claim state.
ClaimAsync(eventId)	Task<ClaimResult>	Claim once. Server is idempotent across devices.

Event - fields

Name	Type	Description
id / key	string	Stable identifiers.
banner_url	string	Optional banner image URL.
starts_at / ends_at	string	ISO 8601 UTC timestamps.
rewards_json	string	Raw JSON string of the rewards object.
claimed	bool	True if this player already claimed.
resolved	Resolved	lang / name / description in the requested language.

ClaimResult - fields

Name	Type	Description
ok	bool	Successful first-time claim.
already_claimed	bool	Server says this player has already claimed.
rewards_json	string	Raw JSON of the granted rewards (echoes the event).
error	string	One of "disabled" \| "network" \| "parse" \| server-supplied error.

REST endpoint

examplebash

1GET /api/public/sdk/live-events
2  ?player_id=...&install_id=...&lang=en&country=US&platform=ios
3Headers: X-API-Key: kf_xxx_yyy
4
5POST /api/public/sdk/live-events
6{ "event_id": "...", "player_id": "...", "install_id": "..." }