Create New AccountLog In

Installation Guide

This guide provides instructions for installing the OnsideKit framework into your iOS project.

Prerequisites

  • Xcode 14 or later

  • iOS 16.0 or later as your project's deployment target

You can integrate OnsideKit using Swift Package Manager, CocoaPods, or by manually adding the framework.

1. Framework Installation 📋

Swift Package Manager

Swift Package Manager (SPM) 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.

  1. Click the + button to add a new package.

  2. In the search bar at the top right, paste the SDK's repository URL:

    https://github.com/onside-io/OnsideKit-iOS

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

  4. Click Add Package.

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

    sudo gem install cocoapods

  2. If you don't have a Podfile in your project's root directory, create one by running:

    pod init

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

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

  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.

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 three main steps:

  1. Allow your app to query for the Onside app's URL scheme

  2. Declaring a unique URL scheme for your app

  3. Informing OnsideKit SDK about this scheme

  4. Forwarding incoming URLs to the SDK for processing

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

Step 3: 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 the Onside

// AppDelegate.swift

import UIKit
import OnsideKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // 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 4: 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.

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

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

PreviousWelcomeNextCustomizing SDK Behavior

Last updated

Was this helpful?