> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trueorigin.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Reading the attribution

> Find out in your app which campaign an install came from.

After `configure`, the SDK reports the first open and the attribution arrives a few
seconds later. It is stored, so on every later launch it is available right away.

## Wait for it

<CodeGroup>
  ```swift Swift theme={null}
  let attribution = await TrueOrigin.attribution()
  switch attribution.status {
  case .matched:   showOnboarding(for: attribution.campaign)
  case .ambiguous: break   // not confident enough; never guessed
  case .unmatched: break   // organic or an untracked channel
  case .expired, .failed, .pending: break
  @unknown default: break
  }
  ```

  ```ts React Native theme={null}
  const attribution = await TrueOrigin.attribution()
  switch (attribution.status) {
    case 'matched':     showOnboarding(attribution.campaign); break
    case 'ambiguous':   break // not confident enough; never guessed
    case 'unmatched':   break // organic or an untracked channel
    case 'expired':     break
    case 'failed':      break
    case 'unsupported': break // Android, web
  }
  ```
</CodeGroup>

`attribution()` never throws. Call it wherever you decide what a new user sees first, for
example to open onboarding on the campaign's topic.

## Or get a callback

<CodeGroup>
  ```swift Swift theme={null}
  TrueOrigin.onAttribution { attribution in
      // called once, on the main queue; right away if already final
  }
  ```

  ```ts React Native theme={null}
  const cancel = TrueOrigin.onAttribution((attribution) => {
    // called once; right away if already final
  })
  ```
</CodeGroup>

`TrueOrigin.currentAttribution` (Swift) and `TrueOrigin.currentAttribution()` (React
Native) return the stored state without waiting, or nothing before the first report.

## Status

| Status        | Meaning                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `pending`     | Not decided yet.                                                                                          |
| `matched`     | The install came from one of your tracking links. `campaign` and `payload` say which.                     |
| `ambiguous`   | TrueOrigin could not decide with enough confidence. It never guesses.                                     |
| `unmatched`   | Organic, or a channel without a TrueOrigin link.                                                          |
| `expired`     | The SDK stopped waiting while the result was still pending.                                               |
| `failed`      | The install could not be reported: no network for the whole `reportTimeout`, or the SDK key was rejected. |
| `unsupported` | React Native on Android or web.                                                                           |

New statuses may be added. In Swift, keep an `@unknown default` case.

## What a match carries

| Field          |                                                                                                                |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| `campaign`     | The **Campaign label** you gave the tracking link. The ad's own campaign is in `payload.utm` and `payload.ad`. |
| `slug`         | The link path, `{link name}/{path}`.                                                                           |
| `attributedAt` | When TrueOrigin decided.                                                                                       |
| `payload`      | The click as JSON.                                                                                             |

Useful keys in `payload`:

| Key          |                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clicked_at` | When the link was tapped (ISO 8601).                                                                                                                                                   |
| `ad_network` | `meta`, `tiktok`, `google`, `snap`, … when the tap carried a network click id.                                                                                                         |
| `utm`        | `source`, `medium`, `campaign`, `content`, `term`.                                                                                                                                     |
| `ad`         | `campaign_id`, `adset_id`, `ad_id`, `creative_id`, `placement`, `campaign_name`, `adset_name`, `ad_name`, `site`, as far as the ad's [URL parameters](/tracking-links) filled them in. |
| `query`      | Every parameter of the tapped link, as it came in.                                                                                                                                     |

```swift theme={null}
let adsetId = attribution.payload?["ad"]?["adset_id"]?.stringValue
```

```ts theme={null}
const ad = attribution.payload?.ad as Record<string, string | null> | undefined
const adsetId = ad?.adset_id
```