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.
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.