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

2. Declare your app's URL scheme

3. Initialize the SDK

4. Provide your callback scheme to OnsideKit

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):

<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.

<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.

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

initialize is idempotent — a second call is a no-op. It also accepts two optional parameters:

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

• storeKitConfigurationName enables an offline testing mode backed by a .storekit file — see Local Testing.

• disableSSLPinning is a debugging aid only — see Debugging & installationId.

For a normal integration, call Onside.initialize() with no arguments.

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.

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.

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.

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

Implement the forwarding for your app's lifecycle:

UIKit (AppDelegate)

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

UIKit (SceneDelegate)

SwiftUI

You're set up

OnsideKit is now initialized and ready. Next:

• Quick Start — a minimal end-to-end purchase flow

• Authentication & User Account — how login works and how to read session state

• The Onside Delegate — route SDK screens to a window scene and customize behavior