# Initializing the SDK

Before you call any OnsideKit API, complete this one-time setup at app launch. It also enables the seamless **app-to-app login** flow, where the user authenticates in the Onside store app and is returned to your app.

The setup has five steps:

1. [Allow your app to detect the Onside app](#id-1-allow-your-app-to-detect-the-onside-app)
2. [Declare your app's URL scheme](#id-2-declare-your-apps-url-scheme)
3. [Initialize the SDK](#id-3-initialize-the-sdk)
4. [Provide your callback scheme to OnsideKit](#id-4-provide-your-callback-scheme-to-onsidekit)
5. [Forward incoming URLs to OnsideKit](#id-5-forward-incoming-urls-to-onsidekit)

## 1. Allow your app to detect the Onside app

To start the app-to-app login, OnsideKit checks whether the Onside store app is installed (via `canOpenURL`). iOS requires you to declare the `onside` scheme you want to query in your `Info.plist`.

Add the `onside` scheme under **Queried URL Schemes** (`LSApplicationQueriesSchemes`):

```xml
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>onside</string>
</array>
```

## 2. Declare your app's URL scheme

Your app needs its own URL scheme so the Onside store app knows where to send the user back. Register a unique scheme under **URL Types** (`CFBundleURLTypes`). Use a reverse-domain style to avoid collisions — for example `com.yourapp.onside`.

```xml
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>com.yourapp.onside</string>
        </array>
    </dict>
</array>
```

You can also set this in Xcode under **Target → Info → URL Types**.

## 3. Initialize the SDK

Call `Onside.initialize()` once at launch, **before any other OnsideKit API**. Calling an OnsideKit API before this logs a warning and leads to undefined behavior.

```swift
// AppDelegate.swift
import UIKit
import OnsideKit

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Onside.initialize()

        // Use the exact same scheme you declared in step 2.
        Onside.callbackScheme = "com.yourapp.onside"

        return true
    }
}
```

{% hint style="info" %}
`initialize` is idempotent — a second call is a no-op. It also accepts two optional parameters:

```swift
Onside.initialize(disableSSLPinning: Bool = false, storeKitConfigurationName: String? = nil)
```

* `storeKitConfigurationName` enables an offline testing mode backed by a `.storekit` file — see [Local Testing](/sdk/advanced-and-tooling/local-testing.md).
* `disableSSLPinning` is a debugging aid only — see [Debugging & installationId](/sdk/advanced-and-tooling/debugging.md).

For a normal integration, call `Onside.initialize()` with no arguments.
{% endhint %}

## 4. Provide your callback scheme to OnsideKit

Set `Onside.callbackScheme` to the **exact** scheme you declared in step 2 (shown in the snippet above). OnsideKit uses it to recognize the redirect coming back from the Onside store app.

{% hint style="warning" %}
If `callbackScheme` is not set, OnsideKit cannot start the app-to-app login and falls back to its own in-SDK login screen. See [Authentication & User Account](/sdk/core-concepts/authentication.md).
{% endhint %}

## 5. Forward incoming URLs to OnsideKit

When the Onside store app redirects back to your app, pass the incoming URL to `Onside.handle(url:)`. It returns `true` when the URL was an Onside callback that it consumed.

```swift
@MainActor static func handle(url: URL) -> Bool
```

Implement the forwarding for your app's lifecycle:

{% tabs %}
{% tab title="UIKit (AppDelegate)" %}

```swift
// AppDelegate.swift
import OnsideKit

extension AppDelegate {
    func application(
        _ app: UIApplication,
        open url: URL,
        options: [UIApplication.OpenURLOptionsKey: Any] = [:]
    ) -> Bool {
        if Onside.handle(url: url) {
            return true
        }
        // Handle your own URLs here…
        return false
    }
}
```

{% endtab %}

{% tab title="UIKit (SceneDelegate)" %}

```swift
// SceneDelegate.swift
import OnsideKit

extension SceneDelegate {
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        guard let url = URLContexts.first?.url else { return }
        if !Onside.handle(url: url) {
            // Handle your own URLs here…
        }
    }
}
```

{% endtab %}

{% tab title="SwiftUI" %}

```swift
// YourApp.swift
import SwiftUI
import OnsideKit

@main
struct YourApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    if !Onside.handle(url: url) {
                        // Handle your own URLs here…
                    }
                }
        }
    }
}
```

{% endtab %}
{% endtabs %}

## You're set up

OnsideKit is now initialized and ready. Next:

* [Quick Start](/sdk/getting-started/quick-start.md) — a minimal end-to-end purchase flow
* [Authentication & User Account](/sdk/core-concepts/authentication.md) — how login works and how to read session state
* [The Onside Delegate](/sdk/customization/delegate.md) — route SDK screens to a window scene and customize behavior


---

# 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/getting-started/initialization.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.