> For the complete documentation index, see [llms.txt](https://docs.onside.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onside.io/sdk/getting-started/initialization.md).

# Initializing the SDK

Initialize OnsideKit, register your callback URL scheme, and forward incoming URLs so the app-to-app login flow can complete.

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 %}

## Optional: external accounts

After initialization, native apps can assign `Onside.externalLoginDelegate` to supply their own account identifier. Keep the URL-scheme setup above if you want app-to-app login when external login falls back. See [External Login](/sdk/core-concepts/external-login.md) for setup and purchase restrictions. JavaScript integrations configure external login through the bridge API.

## 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
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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.onside.io/sdk/getting-started/initialization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.