# Attribution

Attribution tells you where a user came from before installing your app. OnsideKit links the install to a prior browser session and returns a `refererUrl` describing the source page.

### Requirements

Call `Onside.initialize()` as early as possible at app launch, before any other OnsideKit API. The earlier you initialize, the sooner the install can be correlated with the originating session. See [Initializing the SDK](/sdk/getting-started/initialization.md#id-3-initialize-the-sdk).

### Getting attribution metadata

```swift
@MainActor static func getAttributionMetadata(
    completion: @escaping @MainActor (Result<OnsideAttributionMetadata, OnsideAttributionMetadataError>) -> Void
)
```

`OnsideAttributionMetadata` contains a single optional field:

```swift
struct OnsideAttributionMetadata {
    var refererUrl: URL?
}
```

* `refererUrl != nil` — the install was attributed to a browser session. The value is the full URL loaded in the user's browser when the install started (typically your landing page), including any ad-network query parameters such as UTM tags and click IDs.
* `refererUrl == nil` — the install was organic, or attribution wasn't possible.

{% hint style="info" %}
The result is fetched once over the network and then cached on device, and concurrent calls are de-duplicated — so you can call `getAttributionMetadata` whenever convenient without extra cost.
{% endhint %}

#### Example

```swift
import UIKit
import OnsideKit

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // Call as early as possible for reliable attribution.
        Onside.initialize()

        Onside.getAttributionMetadata { result in
            switch result {
            case .success(let metadata):
                if let refererUrl = metadata.refererUrl {
                    print("Onside refererUrl: \(refererUrl)")
                    // Send refererUrl to your analytics / backend if needed.
                } else {
                    print("No refererUrl. Organic install or attribution unavailable.")
                }

            case .failure(let error):
                print("Failed to fetch attribution metadata: \(error)")
            }
        }

        return true
    }
}
```

### Errors

`OnsideAttributionMetadataError`:

<table><thead><tr><th width="240">Case</th><th>Cause</th><th>Suggested handling</th></tr></thead><tbody><tr><td><code>.connectionError</code></td><td>Network failure.</td><td>Retry later.</td></tr><tr><td><code>.serviceUnavailable</code></td><td>Server returned 5xx.</td><td>Retry later.</td></tr><tr><td><code>.appNotRegistered</code></td><td>The app/install isn't recognized by Onside (HTTP 404).</td><td>Check your app registration/configuration.</td></tr><tr><td><code>.internalError</code></td><td>Parsing or other unexpected error.</td><td>Report if persistent.</td></tr></tbody></table>

{% hint style="info" %}
Attribution is also available from web content through the [JS ↔ Native Bridge](/sdk/integrations/js-bridge.md) as `getAttributionMetadata()`.
{% endhint %}

### Next

* [Building funnels with event tracking](/sdk/attribution-and-analytics/building-funnels-with-event-tracking.md) — track what users do after they arrive


---

# Agent Instructions: 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://docs.onside.io/sdk/attribution-and-analytics/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.