Deeplinks

The Reward Center SDK is activated by a deep link delivered to the app on launch. The deep link carries the campaign definition (publisher, currency, milestones, rewards). No deep link, no campaign, no UI.

It supports two deep link modes, Inline and Reference and auto-detects the mode using the following rules:

cid : the campaign id. Required in both modes.
payload (inline mode) : the campaign JSON, URL-encoded
config_url (reference mode) : the URL where the campaign JSON is hosted, URL-encoded

Inline Mode

https://link.ciao.games/rc?cid=<CAMPAIGN_ID>&payload=<URL-ENCODED JSON>

The SDK reads the payload parameter, URL-decodes it, and parses it as JSON.

Reference Mode

https://link.ciao.games/rc?cid=<CAMPAIGN_ID>&config_url=<URL-ENCODED URL>

The SDK reads the config_url parameter, downloads the JSON from that URL, and parses it.
If both payload and config_url are present, the SDK uses config_url (reference mode wins).

Data Model

The JSON payload uses short keys to keep URLs compact.

Campaign

Key	Type	Required	Description
id	string	yes	Unique campaign identifier
pn	string	yes	Publisher name (shown in Welcome popup and Milestones Map)
plu	string	yes	Publisher logo URL (PNG/JPG, downloaded and cached)
cn	string	yes	Currency name (e.g. "coins", "gems")
ciu	string	yes	Currency icon URL (PNG/JPG, downloaded and cached)
ex	string	yes	Campaign expiry, ISO 8601 UTC (e.g. "2027-01-01T00:00:00Z")
m	array	yes	Milestones, at least one required

MIlestone

Key	Type	Required	Description
e	string	yes	Event name. Must match the event fired by the game/MMP when this milestone is achieved
r	number	yes	Reward amount in the campaign's currency
d	string	no	Human-readable description shown in the Milestones Map. If omitted, falls back to `"Complete Milestone #N"`

Milestones are identified by their e field. Each milestone must have a unique event name within the campaign.

Example Payload

{
  "id": "cg_promo",
  "pn": "Ciao",
  "plu": "https://ciao.games/logo.png",
  "cn": "coins",
  "ciu": "https://ciao.games/coin.png",
  "ex": "2027-01-01T00:00:00Z",
  "m": [
    { "e": "level_5_completed", "r": 100, "d": "Reach level 5" },
    { "e": "watch_ad", "r": 250, "d": "Watch an ad" },
    { "e": "make_purchase", "r": 500, "d": "Make a purchase" }
  ]
}

As an inline deep link

The JSON is URL-encoded (percent-encoded) and placed in the payload parameter:

https://link.ciao.games/rc?cid=cg_promo&payload=%7B%22id%22%3A%22scg_promo%22%2C%22pn%22%3A%22Ciao%22...

As a reference deep link

The JSON is hosted at a URL, and the URL is placed in config_url:

https://link.ciao.games/rc?cid=cg_promo&config_url=https%3A%2F%2Fciao.games%2Fcg_promo.json

Encoding

All URLs must be percent-encoded (URL-encoded).

payload value must be percent-encoded JSON. Reserved characters like {, ", :, ,, [, ] become %7B, %22, %3A, %2C, %5B, %5D.
config_url value must be percent-encoded. The : and / in the URL become %3A and %2F.

Failing to encode will corrupt the URL when passed through Singular(MMPs), OS deep link handling, or copy-paste flows.

Runtime Behavior

When the SDK receives a deep link via RewardCenter.HandleDeepLink(url):

Validates cid presence. If missing, the URL is ignored (not our deep link).
Detects mode:
1. config_url present → fetches JSON from that URL
2. payload present → decodes JSON from the parameter
Parses JSON into a Campaign object.
Validates: campaign must have an id and at least one milestone.
Compares with the currently active campaign (if any):
1. Same id → ignored (deduplication)
2. Different id or no active campaign → replaces state, downloads publisher logo and currency icon, activates the campaign
Fires OnCampaignActivated once assets are downloaded.

Expiry

The ex field is checked at SDK initialization only. If a campaign is past its expiry when the app launches, it is cleared and the SDK stays dormant until a new deep link arrives.

Expiry is not re-checked during a session. A campaign that expires while the user is playing remains active until the next launch.