> For the complete documentation index, see [llms.txt](https://series-1.gitbook.io/rundot-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://series-1.gitbook.io/rundot-docs/v5.21.0/readme/attribution.md).

# Attribution API

Read the web campaign and UTM parameters the player arrived with. Use them to tailor onboarding, credit a referral source, or report acquisition in your own analytics.

{% hint style="warning" %}
All SDK methods can reject; unhandled rejections crash the app. Always wrap SDK calls in `try/catch` or attach a `.catch()` handler. See [Error Handling](/rundot-docs/v5.21.0/readme/error-handling.md) for details.
{% endhint %}

{% hint style="info" %}
Attribution params are a web-only signal. `getAttributionParams()` resolves to `null` on native (iOS/Android), and on web it resolves to `null` when no campaign params were captured at landing. Always handle the `null` case.
{% endhint %}

## Quick Start

```typescript
import RundotGameAPI from '@series-inc/rundot-game-sdk/api'

const params = await RundotGameAPI.attribution.getAttributionParams()

if (params) {
  console.log('Arrived from', params.utm_source, params.utm_campaign)
} else {
  // null on native, or on web when no campaign params were captured
}
```

## `getAttributionParams(): Promise<CampaignParams | null>`

Resolves to the campaign params the player landed with, or `null`.

The host returns `null` immediately on native platforms (iOS/Android). On web it returns the params captured from the landing URL, or `null` when none were present. Within a returned `CampaignParams` object, any individual field is `null` when that parameter was absent from the URL.

| Returns                           | Description                                                                             |
| --------------------------------- | --------------------------------------------------------------------------------------- |
| `Promise<CampaignParams \| null>` | The captured campaign params, or `null` on native and on web when nothing was captured. |

```typescript
import RundotGameAPI from '@series-inc/rundot-game-sdk/api'

async function reportAcquisition() {
  const params = await RundotGameAPI.attribution.getAttributionParams()
  if (!params) return

  myAnalytics.track('acquisition', {
    source: params.utm_source,
    medium: params.utm_medium,
    campaign: params.utm_campaign,
    fbclid: params.fbclid,
    gclid: params.gclid,
  })
}
```

## API Reference

| Method                   | Returns                           | Description                                                                                                 |
| ------------------------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `getAttributionParams()` | `Promise<CampaignParams \| null>` | Read the captured web campaign/UTM params. Resolves to `null` on native and on web when none were captured. |

## Types

### `CampaignParams`

The shape returned by `getAttributionParams()`. Every field is `string | null`; a field is `null` when that parameter was absent from the landing URL.

| Field          | Type             | Description                                            |
| -------------- | ---------------- | ------------------------------------------------------ |
| `utm_source`   | `string \| null` | Identifies the referrer (e.g. `google`, `newsletter`). |
| `utm_medium`   | `string \| null` | Marketing medium (e.g. `cpc`, `email`, `social`).      |
| `utm_campaign` | `string \| null` | Campaign name.                                         |
| `utm_content`  | `string \| null` | Distinguishes creatives or links within a campaign.    |
| `utm_term`     | `string \| null` | Paid-search keyword term.                              |
| `fbclid`       | `string \| null` | Facebook click identifier.                             |
| `gclid`        | `string \| null` | Google click identifier.                               |

```typescript
interface CampaignParams {
  utm_source: string | null
  utm_medium: string | null
  utm_campaign: string | null
  utm_content: string | null
  utm_term: string | null
  fbclid: string | null
  gclid: string | null
}
```

## Best Practices

* Always branch on the `null` result; never assume params exist (they never do on native).
* Treat each field independently; a player can arrive with `utm_source` set but `utm_campaign` `null`.
* Read params once early and cache them; the value does not change during a session.
* Don't rely on attribution params for gameplay gating; they're an acquisition signal, not an authenticated identity.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://series-1.gitbook.io/rundot-docs/v5.21.0/readme/attribution.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.