# Advertiser integration

Advertisers connect incoming Platform users to advertiser accounts, report actions such as sign-up, KYC, or deposit, and may act as Reward Providers.

## Responsibilities

1. Receive a user through the Onward account-linking flow.
2. Complete sign-up or sign-in on the advertiser site.
3. Complete the configured OAuth 2.0 or Signed Token Callback mechanism.
4. Report subsequent advertiser-side events.
5. If configured as Reward Provider, process signed and idempotent reward webhooks.

## Typical flow

The following diagram shows the Signed Token Callback Flow. With OAuth 2.0, the Advertiser instead issues an
authorization code and Onward completes the token exchange directly with the Advertiser backend.

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

    User->>Platform: Starts an advertiser task
    Platform->>Onward: Request account connection
    Onward-->>Platform: Signed, short-lived authorization URL
    Platform-->>User: Redirect to Advertiser
    User->>Advertiser: Sign up or sign in
    Advertiser->>Onward: POST /v1/users/connect-account
    Onward-->>Advertiser: Link confirmed and redirect URL
    Advertiser-->>User: Redirect back to Platform

    User->>Advertiser: Performs an action
    Advertiser->>Onward: Report advertiser event
    Onward-->>Advertiser: Event accepted
    Note over Onward,Platform: Matching tasks and progress are updated asynchronously`}
  caption="Signed Token Callback account connection and subsequent event reporting."
/>

## Choosing and completing the connection

Advertisers with OAuth infrastructure should implement the
[OAuth 2.0 Authorization Code Flow](/docs/account-linking/oauth-authorization-code). Advertisers without OAuth can use
the [Signed Token Callback Flow](/docs/account-linking/signed-token-callback).

### Signed-token backend confirmation

The Advertiser must call
[`POST /v1/users/connect-account`](/docs/api-reference/account-connection-api#complete-oauth-account-linking) from its
backend. Supply the short-lived token received through the redirect flow and the stable Advertiser-side user identifier.

Optional `retro_events` let the Advertiser report actions that occurred before the connection was finalized. Onward evaluates them immediately after linking the accounts.

See [Account linking](/docs/account-linking) for the mechanism comparison and shared lifecycle.

## Integration checklist

- Obtain Advertiser API credentials with account-connection permission.
- Keep `advertiser_user_id` stable across calls.
- Complete account connection only from trusted backend code.
- Preserve and validate the redirect destination supplied by the flow.
- Make event and reward processing idempotent.