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

<Mermaid
  chart={`sequenceDiagram
    participant User
    participant Platform
    participant Onward as Onward API
    participant Advertiser

    User->>Platform: Opens the Quest Chains experience
    Platform->>Onward: Register or synchronize platform user
    Platform->>Onward: GET /v1/quest-chains/active/{platformUserId}
    Onward-->>Platform: Quest chains, tasks, and progress
    Platform-->>User: Render active chains

    User->>Platform: Starts an advertiser task
    Platform->>Onward: Start account connection
    Onward-->>Platform: Authorization redirect URL
    Platform-->>User: Redirect to Advertiser
    User->>Advertiser: Sign up or sign in
    Advertiser->>Onward: POST /v1/users/connect-account
    Onward-->>Advertiser: Connection confirmed
    Advertiser-->>User: Redirect back to Platform

    User->>Platform: Performs a platform-side action
    Platform->>Onward: Report event
    Onward-->>Platform: Event accepted
    Platform-->>User: Refresh progress`}
  caption="Platform journey using Signed Token Callback account linking and subsequent progress updates."
/>

## Reading active chains

Call [`GET /v1/quest-chains/active/{platformUserId}`](/docs/api-reference/quest-chain-api#get-active-quest-chains-for-the-user) from the Platform backend. The response distinguishes an unknown user from a known user with no active chains:

- `user.exists: false` means Onward does not know the requested Platform user.
- `user.exists: true` with an empty `quest_chains` array 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](/docs/account-linking).

## User experience

- Refresh progress after sending an event or returning from an account connection.
- Preserve task order and honor `allow_any_order` from 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.