Platform integration
The Platform is the user-facing entry point. It displays quest chains, keeps progress visible, initiates account linking, and reports events that happen inside the Platform.
Responsibilities
| Responsibility | Description |
|---|---|
| User identity | Keep a stable platform_user_id and register or synchronize the user with Onward. |
| Chain display | Fetch active quest chains and render tasks, progress, and rewards. |
| Platform events | Report actions that occur inside the Platform. |
| Account linking | Redirect the user to the authorization URL for advertiser-side tasks. |
| Reward UX | Let eligible users claim rewards and show the resulting state. |
Typical flow
The diagram shows a Signed Token Callback integration. For an OAuth 2.0 Advertiser, the Platform steps are unchanged: Onward returns the correct Advertiser URL and completes the configured OAuth exchange after the redirect.
Reading active chains
Call GET /v1/quest-chains/active/{platformUserId} from the Platform backend. The response distinguishes an unknown user from a known user with no active chains:
user.exists: falsemeans Onward does not know the requested Platform user.user.exists: truewith an emptyquest_chainsarray means the user currently has no active chain.
Tasks are returned in sequence_number order. For step-by-step chains, a locked task is not yet reachable and is an API presentation state rather than a database status.
When a task requires an advertiser account, continue with the Account linking guide.
Channel headers
Onward reports where users come from — web, iOS or Android — and where they start quest chains. Because the Platform backend calls Onward server-to-server, Onward cannot see the end user's device itself, so the Platform states the channel explicitly.
On every GET /v1/quest-chains/active/{platformUserId} call made on behalf of a user, send:
| Header | Required | Value |
|---|---|---|
X-Onward-Channel | Yes | web, ios or android: the frontend showing the quest chains. |
X-Onward-User-Agent | No | The end user's own User-Agent, forwarded verbatim. |
Code
Send the channel itself rather than relying on the User-Agent alone: a quest chain screen embedded in a mobile app's WebView has nearly the same User-Agent as the mobile website.
- A missing, empty or unrecognized
X-Onward-Channelis recorded asunknownand logged on the Onward side. The request is never rejected because of these headers. - Calls the Platform makes on its own — cache warm-up, prefetching, server-side rendering — are not user visits. Send
X-Onward-Channel: backgroundon them so they are not counted. - Later actions of the user —
POST /v1/account/start-connect,POST /v1/rewards/claim,POST /v1/chains/rewards/claimand the Advertiser's account connection — are attributed to the channel of the user's last quest chain request. On these calls the headers are optional: send them to attribute an action precisely when the same user may have the website and the app open at once.
Direct advertiser linking
When the Platform and Advertiser are the same party — or the Platform controls the Advertiser backend — account linking can be completed in a single register call without a redirect flow.
Supply advertiser_user_id in the request body alongside the advertiser API key headers:
Code
Onward atomically registers the user (or finds an existing one) and links the advertiser account. Segmentation and reconciliation run as a best-effort background step after the commit: if segmentation times out, the response is still successful and the job is retried via the outbox. The response is identical to a standard register call.
Requirements:
- Both
advertiser_user_idand the advertiser key headers must be provided together — one without the other returns a 400 error. - The advertiser API key must have the
can_users_connect_accountpermission. - This endpoint must be called server-to-server only. Never expose advertiser credentials to client-side code.
Note: direct linking emits a link_account event after segmentation and chain join complete. If a pending linking task is visible to the user, it will be closed automatically — but may take a few seconds after the register call returns.
User experience
- Refresh progress after sending an event or returning from an account connection.
- Preserve task order and honor
allow_any_orderfrom the chain. - Use names and descriptions directly in the UI, but provide graceful fallbacks for nullable images and descriptions.
- Treat an empty chain list as a normal state.