# Installation Guide

#### Prerequisites

* Xcode 14 or later
* iOS 16.0 or later as your project's deployment target

You can integrate OnsideKit using [Swift Package Manager](#swift-package-manager), [CocoaPods](#cocoapods), or by [manually](#manual-installation) adding the framework.

***

## 1. Framework Installation 📋

### Swift Package Manager

[Swift Package Manager (SPM)](https://www.swift.org/documentation/package-manager/) is Apple's official dependency manager, integrated directly into Xcode.

**Steps:**

1. In Xcode, open your project and navigate to your project's settings by clicking on the project file in the Project Navigator.
2. Select your project in the **PROJECT** section, then go to the **Package Dependencies** tab.

<div data-full-width="false"><figure><img src="https://3039215126-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Far2Jh3wLmverIdTKRpUi%2Fuploads%2FS9aB3nNKgpPQ8U52zXjJ%2FScreenshot%202025-07-11%20at%2016.53.58.png?alt=media&#x26;token=272f456b-8385-4a3d-b5b9-2cbafc351da2" alt=""><figcaption></figcaption></figure></div>

3. Click the **+** button to add a new package.
4. In the search bar at the top right, paste the SDK's repository URL:

   ```url
   https://github.com/onside-io/OnsideKit-iOS
   ```
5. Xcode will fetch the package. For the **Dependency Rule**, we recommend using **"Up to Next Major Version"** to automatically receive updates and bug fixes without breaking changes.
6. Click **Add Package**.

<figure><img src="https://3039215126-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Far2Jh3wLmverIdTKRpUi%2Fuploads%2Fu1mXUPYXZTGDX06Eo1Iu%2FScreenshot%202025-07-12%20at%2023.32.45.png?alt=media&#x26;token=f3ca8720-6956-499f-a93a-817b75f82a42" alt=""><figcaption></figcaption></figure>

7. Choose the package product to add to your app's target and click **Add Package** again.

The OnsideKit framework will now appear in the Project Navigator and will be automatically linked to your target.

### CocoaPods

[CocoaPods](https://cocoapods.org/) is a popular dependency manager for Swift and Objective-C projects.

**Steps:**

1. If you don't have CocoaPods installed, open Terminal and run the following command:

   ```bash
   sudo gem install cocoapods
   ```
2. If you don't have a Podfile in your project's root directory, create one by running:

   ```bash
   pod init
   ```
3. Open your Podfile with a text editor and add the following line inside your app's target block.

   ```ruby
   # Podfile

   platform :ios, '16.0'
   use_frameworks!

   target 'YourAppName' do
       pod 'OnsideKit', :git => 'https://github.com/onside-io/OnsideKit-iOS.git'
   end
   ```
4. Save the Podfile and run the installation command in your project's root directory:

   ```
   pod install
   ```
5. After the installation is complete open the newly created .xcworkspace file.

You can now import OnsideKit in your source files and start using the SDK.

### Manual Installation

If you prefer not to use a dependency manager, you can install the framework manually.

**Steps:**

1. Download the latest version of OnsideKit.xcframework.zip from our [**Releases page**](https://github.com/onside-io/OnsideKit-iOS/releases).
2. Unzip the downloaded file to get the OnsideKit.xcframework bundle.
3. In Xcode, open your project and select your app's target.
4. Navigate to the **General** tab.
5. Find the **"Frameworks, Libraries, and Embedded Content"** section.
6. Drag and drop the OnsideKit.xcframework file from your Finder into this section.
7. Ensure that **"Embed & Sign"** is selected for the framework. This is crucial as it bundles the framework with your app and signs it.

<figure><img src="https://3039215126-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Far2Jh3wLmverIdTKRpUi%2Fuploads%2FX5MOiRXxsyDSw7v90bim%2FScreenshot%202025-07-11%20at%2017.11.11.png?alt=media&#x26;token=a855c42a-14a6-49bf-b737-b42750848913" alt=""><figcaption></figcaption></figure>

***

## 2. Basic Configuration 🛠️

To enable the seamless, app-to-app authorization flow with the Onside store app, you need to perform a one-time configuration in your project. This allows your application to securely receive authentication data back from the Onside.

The process involves five main steps:

1. [Allow your app to query for the Onside app's URL scheme](#step-1-allow-queries-for-the-onside-app-scheme)
2. [Declaring a unique URL scheme for your app](#step-2-declare-a-custom-url-scheme)
3. [Initialize the SDK](#step-3-initialize-the-sdk)
4. [Informing OnsideKit SDK about this scheme](#step-4-provide-the-callback-scheme-to-the-sdk)
5. [Forwarding incoming URLs to the SDK for processing](#step-5-forward-incoming-urls-to-the-sdk)

#### Step 1: Allow Queries for the Onside App Scheme

For OnsideKit to be able to open the Onside store app, your application needs permission to query for its custom URL scheme. You must add the onside scheme to your app's Info.plist.

1. In Xcode, open your project's Info.plist file.
2. Add a new key by clicking the + button and select **"Queried URL Schemes"** from the list (or type `LSApplicationQueriesSchemes` manually).
3. The type for this key will be an Array.
4. Click the + button on that row to add a new item to the array.
5. Set the value of **Item 0** to `onside`.

This is what it looks like in the Info.plist source code:

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

> **Why is this needed?** This step is required by iOS to allow your app to check if the main Onside store app is installed on the user's device (canOpenURL), which is necessary to initiate the seamless login flow.

#### Step 2: Declare a Custom URL Scheme

Your app needs a unique identifier so the Onside store app knows where to redirect the user back to. This is done by registering a custom URL scheme.

1. In Xcode, select your project file in the Project Navigator.
2. Select your app's target and navigate to the **Info** tab.
3. Expand the **URL Types** section. If it doesn't exist, click the **+** button to add one.
4. In the **URL Schemes** field, enter a unique scheme for your app. We recommend using a reverse-domain style or a unique name related to your app to avoid collisions with other apps.
   * **Example:** com.yourapp.auth or onside-yourapp-login
5.

```
<figure><img src="/files/EUnPPUWO2xav56dhzWul" alt=""><figcaption></figcaption></figure>
```

#### Step 3: Initialize the SDK

Before you call any OnsideKit API, call `Onside.initialize()` once at app launch.

If you skip this, some SDK features (for example user attribution) can behave incorrectly.

The best place to do this is at application launch.

1. Open your AppDelegate.swift file
2. Import the OnsideKit framework
3. In the `application(_:didFinishLaunchingWithOptions:)` method, call `Onside.initialize()`

```swift
// AppDelegate.swift

import UIKit
import OnsideKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

        // Your other app setup code...

        return true
    }
    
    // ... rest of your AppDelegate code

}
```

#### Step 4: Provide the Callback Scheme to the SDK

Once the URL scheme is declared, you must provide the exact same string to OnsideKit. This allows the SDK to correctly handle the callback.

The best place to do this is at application launch.

1. Open your AppDelegate.swift file
2. Import the OnsideKit framework
3. In the `application(_:didFinishLaunchingWithOptions:)` method, set the `callbackScheme` property on `Onside`

```swift
// AppDelegate.swift

import UIKit
import OnsideKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialize the SDK before calling any other OnsideKit APIs
        Onside.initialize()

        // Use the exact same URL Scheme you defined in your Info.plist
        Onside.callbackScheme = "com.yourapp.auth"

        // Your other app setup code...

        return true
    }
    
    // ... rest of your AppDelegate code

}
```

#### Step 5: Forward Incoming URLs to the SDK

When the Onside app redirects back to your application, the system will notify your app via a specific delegate method. You need to implement this method and pass the incoming URL to OnsideKit to complete the authentication process.

The implementation depends on your project's lifecycle (UIKit AppDelegate or SwiftUI App).

**For UIKit AppDelegate Lifecycle**

In your AppDelegate.swift, implement the `application(_:open:options:)` method.

```swift
// AppDelegate.swift

import OnsideKit

class AppDelegate: UIResponder, UIApplicationDelegate {

    // ... your other AppDelegate code
    
    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
        let handledByOnside = Onside.handle(url: url)
        if handledByOnside {
            return true
        } else {
            // Your other url handling code...
        }
    }

}
```

**For SwiftUI App Lifecycle (with SceneDelegate)**

If your project uses a SceneDelegate, you should implement the `scene(_:openURLContexts:)` method instead.

```swift
// SceneDelegate.swift

import OnsideKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    // ... your other SceneDelegate code

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        guard let url = URLContexts.first?.url else {
            return
        }
        
        let handledByOnside = Onside.handle(url: url)
        if !handledByOnside {
            // Your other url handling code...
        }
    }

}
```

## 3. Congratulations! 🎉

You've completed the necessary configuration! You are now ready to start using **OnsideKit** in your application.


---

# 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/installation-guide.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.