iOS SDK Setup

AppsOnAir-AppLink helps you manage deep links and in-app routing seamlessly in your iOS app. With a simple integration, you can configure, manage, and respond to links from the web dashboard in real time.

BETA

The plugin is fully functional and integrates with our AppLink service, which is currently in public beta. While you can start using it today, please note that there may be minor changes or improvements as we prepare for full production launch.

Basic Requirements

apiKey Setup

• Ensure that your API key is correctly configured. For more information, refer to the Getting Started guide.

Prerequisites

• Before getting started, ensure your AppLink Configuration is set up.

• Minimum supported deployment target is iOS 13.0.

Import the SDK into Your Xcode Project

Using CocoaPods

2.1 Close your Xcode project if it’s open.

2.2 In your project’s root directory, run the following command to install CocoaPods:

Terminal

sudo gem install cocoapods

2.3 Run the following command to initialize CocoaPods:

Terminal

pod init

2.4 Open the generated Podfile in your preferred code editor and add the SDK dependency under your app target:

Podfile

target 'your_project_name' do
  pod 'AppsOnAir-AppLink'
end

2.5 In the terminal, navigate to your project directory and run:

Terminal

pod repo update
pod install

Configure Entitlements and URL Schemes

Universal Links (Associated Domains)

Note

• Configuring associated domains is optional.

• In Xcode, Under TARGETS, select your app target (usually the one named after your app).
• At the top, select the Signing & Capabilities tab.
• Click the + Capability button in the top-left corner of that section.
• In the list of capabilities, scroll or search to select Associated Domains.
• This will automatically create a file named YOUR_PROJECT.entitlements.

Create or update the YOUR_PROJECT.entitlements file and add the following:

YOUR_PROJECT.entitlements

<!-- If Using Universal Links -->
<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:YOUR_DOMAIN</string> <!-- Replace with your actual domain -->
</array>

Add/Update Associated Domain

Note

After configuring the Associated Domain for Universal Links, it may take up to 24 hours for the changes to be reflected and become active. The Associated Domain setup and verification process is managed by Apple.

Custom URL Scheme

If you're using a Custom URL scheme, update your app’s Info.plist file with the following:

Info.plist

<!-- If Using Custom Url Schema -->
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>YOUR_URL_NAME</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>YOUR_CUSTOM_URL_SCHEME</string> <!-- Replace with your custom URL scheme -->
        </array>
    </dict>
</array>

Initialize the AppLink Service

Import the SDK at the top of your AppDelegate file or relevant Swift/SwiftUI/Objective-C file:

Swift

AppDelegate.swift

import AppsOnAir_AppLink

SwiftUI

ContentView.swift

import AppsOnAir_AppLink

Objective-C

AppDelegate.m

#import "AppsOnAir_AppLink-Swift.h"

Implementation

Swift

AppDelegate.swift

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?
    let appOnAirLinkService = AppLinkService.shared

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialize the link service
        appOnAirLinkService.initialize { url,linkInfo in
           // Handle the link and its associated data here
        }
        return true
    }

}

SwiftUI

ContentView.swift

import SwiftUI
import AppsOnAir_AppLink

@main
struct appsonairApp: App {
  
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
      AppLinkService.shared.initialize { incomingURL,linkInfo in
          //write the code for handling flow based o url
      }
      return true
  }
}

Objective-C

AppDelegate.m

#import "AppDelegate.h"
#import "AppsOnAir_AppLink/AppsOnAir_AppLink-Swift.h"

@interface AppDelegate ()
@property (nonatomic, strong) AppLinkService *appLinkServices;
@end

@implementation AppDelegate


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // AppLink Class instance create
    self.appLinkServices = [AppLinkService shared];
    
    // help to initialize link services
    [self.appLinkServices initializeWithCompletion:^(NSURL * url, NSDictionary<NSString *,id> * linkInfo) {
        //write the code for handling flow based on url
    }];
    // Override point for customization after application launch.
    return YES;
}

AppLink Implement Code

Important

When using SwiftUI, it is necessary to add the .onOpenURL modifier in ContentView.swift, directly after any layout container such as VStack, Button, or similar views for handling AppLink.

VStack {
    // Your UI components here
}
.onOpenURL { url in
    AppLinkService.shared.handleAppLink(incomingURL: url)
}

• The initialize() function initializes the common AppLink service and sets up the deep link handler. It processes the incoming link when the app is launched with any URL.

Creating the AppLink

You can also generate a AppLink such as from a button tap within your application’s UI.

Import the SDK

Import the AppsOnAir_AppLink module into your ViewController or relevant Swift/SwiftUI/Objective-C file.

Swift

ViewController.swift

import AppsOnAir_AppLink

SwiftUI

ContentView.swift

import AppsOnAir_AppLink

Objective-C

ViewController.m

#import "AppsOnAir_AppLink/AppsOnAir_AppLink-Swift.h"

Create the AppLink in Code

Swift

ViewController.swift

class ViewController: UIViewController {
    let appOnAirLinkService = AppLinkService.shared
  
    override func viewDidLoad() {
        super.viewDidLoad()
       
        let button = UIButton(type: .system)
                button.setTitle("Button", for: .normal)
                button.backgroundColor = .systemBlue
                button.setTitleColor(.white, for: .normal)
                button.layer.cornerRadius = 10
                
                // Set button frame (size and position)
                button.frame = CGRect(x: 100, y: 200, width: 150, height: 50)
                
                // Add target for onPressed (TouchUpInside)
                button.addTarget(self, action: #selector(buttonPressed), for: .touchUpInside)
                
                // Add the button to the view
                self.view.addSubview(button)
          }
    
          // Define the action when button is pressed
           @objc func buttonPressed() {
               // Help to create the link
               // <urlPrefix> shouldn't contain http or https
               appOnAirLinkService.createAppLink(url: "https://example.com",name: "YOUR_LINK_NAME",urlPrefix: "YOUR_DOMAIN_NAME",shortId: "LINK_ID",socialMeta: [:],isOpenInBrowserApple: false,isOpenInIosApp: true,iOSFallbackUrl: "",isOpenInAndroidApp: true,isOpenInBrowserAndroid: false,androidFallbackUrl: ""
            ) { linkInfo  in
                    //write the code for handling create link
                }
           }

    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Dispose of any resources that can be recreated.
    }
}

SwiftUI

ContentView.swift

struct ContentView: View {
    @State private var showToast = false
    @State private var message = ""

    var body: some View {
        VStack(spacing: 20) {
            Button(action: {
                AppLinkService.shared.createAppLink(
                    url: "https://example.com",
                    name: "YOUR_LINK_NAME",
                    urlPrefix: "YOUR_DOMAIN_NAME",
                    shortId: "LINK_ID",
                    socialMeta: [:],
                    isOpenInBrowserApple: false,
                    isOpenInIosApp: true,
                    iOSFallbackUrl: "",
                    isOpenInAndroidApp: true,
                    isOpenInBrowserAndroid: false,
                    androidFallbackUrl: ""
                ) { linkInfo in
                     //write the code for handling create link
                }
            }) {
                Text("Create Link")
                    .padding()
                    .frame(maxWidth: .infinity)
                    .background(Color.green)
                    .foregroundColor(.white)
                    .cornerRadius(10)
            }
        }
        .padding()
        .toast(isPresented: $showToast, message: message)
        .onOpenURL { url in
            AppLinkService.shared.handleAppLink(incomingURL: url)
        }
    }
}

Objective-C

ViewController.m

@interface ViewController ()
@property (nonatomic, strong) AppLinkService *appLinkService;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.appLinkService = [AppLinkService shared];
    // Create a UIButton programmatically
       UIButton *ctaButton = [UIButton buttonWithType:UIButtonTypeSystem];
       
       // Set button title
       [ctaButton setTitle:@"Create Link" forState:UIControlStateNormal];
       
       // Set button frame (position and size)
       ctaButton.frame = CGRectMake(100, 200, 200, 50);
       
       // Add target-action for button tap
       [ctaButton addTarget:self action:@selector(createLinkTap) forControlEvents:UIControlEventTouchUpInside];
       
       // Add button to the view
       [self.view addSubview:ctaButton];
}
- (void)createLinkTap {
     // Help to create link
     // <urlPrefix> shouldn't contain http or https
    [self.appLinkService createAppLinkWithUrl:@"https://example.com" name:@"YOUR_LINK_NAME" urlPrefix:@"YOUR_DOMAIN_NAME" shortId: @"LINK_ID"socialMeta:@{}isOpenInBrowserApple:true isOpenInIosApp:true iOSFallbackUrl:@"www.google.com" isOpenInAndroidApp:true isOpenInBrowserAndroid:false androidFallbackUrl:@"www.google.com" completion:^(NSDictionary<NSString *,id> * linkInfo) {
        //write the code for handling create link
    }];
}

AppLinkParams Properties

Defines all parameters used to construct a AppLink, including app URL, fallbacks, short ID, and social-meta.

Key	Description
url	The actual deep link URL that the app should open. Example: myapp://product/123
name	The name or label for the link, often used for internal identification.
urlPrefix	The base URL prefix for the link (e.g., https://app.domain.com/). This helps create a complete shareable link.
androidFallbackUrl	A web URL to redirect users to when the app is not installed on Android devices.
iOSFallbackUrl	A web URL to redirect users to when the app is not installed on iOS devices.
shortId	An optional short ID to make the link shorter and easier to share. If provided, the final link becomes urlPrefix/shortId
socialMeta	Meta information used for social sharing previews. refer SocialMeta Properties
isOpenInBrowserApple	Determines whether the link should open in the browser on Apple devices (iOS/macOS).
isOpenInIosApp	Specifies if the link should open in the iOS app even if your app is installed.
isOpenInAndroidApp	Indicates whether to open the link in the Android app even if your app is installed.
isOpenInBrowserAndroid	Determines if the link should open in the browser on Android devices.

socialMeta Properties

Key	Description
title	The title to show in social media link previews.
description	A short description used in social sharing cards (Facebook, Twitter, etc.).
imageUrl	A URL to an image that will appear in the social media preview.

To Retrieving Referral Link

You can also retrieving linkInfo, such as from a button action:

Import the SDK

Import the AppsOnAir_AppLink module into your ViewController.swift or relevant Swift/Objective-C file.

Swift

ViewController.swift

import AppsOnAir_AppLink

SwiftUI

ContentView.swift

import AppsOnAir_AppLink

Objective-C

ViewController.m

#import "AppsOnAir_AppLink/AppsOnAir_AppLink-Swift.h"

Retrieving Referral Link in Code

Swift

ViewController.swift

class ViewController: UIViewController {
    let appOnAirLinkService = AppLinkService.shared
  
    override func viewDidLoad() {
        super.viewDidLoad()
            
        let button = UIButton(type: .system)
                button.setTitle("Button", for: .normal)
                button.backgroundColor = .systemBlue
                button.setTitleColor(.white, for: .normal)
                button.layer.cornerRadius = 10
                
                // Set button frame (size and position)
                button.frame = CGRect(x: 100, y: 200, width: 150, height: 50)
                
                // Add target for onPressed (TouchUpInside)
                button.addTarget(self, action: #selector(buttonPressed), for: .touchUpInside)
                
                // Add the button to the view
                self.view.addSubview(button)
          }
    
          // Define the action when button is pressed
           @objc func buttonPressed() {
               // Help to retrieving referral linkInfo
                appOnAirLinkService.getReferralDetails { linkInfo in
                   //write the code for handling referral linkInfo
                }
           }


    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // Dispose of any resources that can be recreated.
    }

}

SwiftUI

ContentView.swift

struct ContentView: View {

    var body: some View {
        VStack(spacing: 20) {
            Button(action: {
                AppLinkService.shared.getReferralDetails { linkInfo in
                   //write the code for handling referral linkInfo
                }
            }) {
                Text("Fetch Referral Link")
                    .padding()
                    .frame(maxWidth: .infinity)
                    .background(Color.green)
                    .foregroundColor(.white)
                    .cornerRadius(10)
            }
        }
        .padding()
        .onOpenURL { url in
            AppLinkService.shared.handleAppLink(incomingURL: url)
        }
    }
}

Objective-C

ViewController.m

@interface ViewController ()
@property (nonatomic, strong) AppLinkService *appLinkService;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.appLinkService = [AppLinkService shared];
    // Create a UIButton programmatically
       UIButton *ctaButton = [UIButton buttonWithType:UIButtonTypeSystem];
       
       // Set button title
       [ctaButton setTitle:@"Fetch Referral Link" forState:UIControlStateNormal];
       
       // Set button frame (position and size)
       ctaButton.frame = CGRectMake(100, 200, 200, 50);
       
       // Add target-action for button tap
       [ctaButton addTarget:self action:@selector(getReferralLinkTap) forControlEvents:UIControlEventTouchUpInside];
       
       // Add button to the view
       [self.view addSubview:ctaButton];
}
- (void)getReferralLinkTap {
    // Help to retrieving referral linkInfo
    [self.appLinkService getReferralDetailsWithCompletion:^(NSDictionary<NSString *,id> * linkInfo) {
         //write the code for handling referral linkInfo
    }];
}

Response

{
  "message": "Referral link fetched successfully!",
  "status": "SUCCESS",
  "data": {
    "link": "https://your.link",
    "name": "AppLink",
    "referralLink": "https://your.referral.link",
    "shortId": "linkId",
    "socialMetaTags": {
      "description": "Description",
      "imageUrl": "https://example.xom",
      "title": "Meta Title"
    }
  }
}

Troubleshooting

If your app isn’t handling Universal Links or Deep Links as expected, ensure that you’ve correctly implemented the required delegate methods in both AppDelegate and SceneDelegate.

AppDelegate Setup

Swift

AppDelegate.swift

class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?
    let appOnAirLinkService = AppLinkService.shared
  
    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
              let url = userActivity.webpageURL else {
            return false
        }
        appOnAirLinkService.handleAppLink(incomingURL: url)
        return true
    }

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
        appOnAirLinkService.handleAppLink(incomingURL: url)
        return true
    }
}

Objective-C

AppDelegate.m

@interface AppDelegate ()
@property (nonatomic, strong) AppLinkService *appLinkServices;
@end

- (BOOL)application:(UIApplication * )application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    self.appLinkServices = [AppLinkService shared];
    return YES;
}

- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    
    [self.appLinkServices handleAppLinkWithIncomingURL:url];
    return YES;
}

- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {

    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
        NSURL *url = userActivity.webpageURL;
        [self.appLinkServices handleAppLinkWithIncomingURL:url];
    }
    return NO;
}

SceneDelegate Setup

Swift

SceneDelegate.swift

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    let appOnAirLinkService = AppLinkService.shared
    var window: UIWindow?

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        guard let urlContext = URLContexts.first else { return }
        let url = urlContext.url
        appOnAirLinkService.handleAppLink(incomingURL: url)
    }
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
              let incomingURL = userActivity.webpageURL else {
            return
        }
        appOnAirLinkService.handleAppLink(incomingURL: incomingURL)
    }
}

Objective-C

SceneDelegate.m

@interface SceneDelegate ()
@property (nonatomic, strong) AppLinkService *appLinkServices;
@end

@implementation SceneDelegate

- (void)scene:(UIScene *)scene
willConnectToSession:(UISceneSession *)session
     options:(UISceneConnectionOptions *)connectionOptions {
    
    // Handle URLs when app is cold started
    if (connectionOptions.URLContexts.count > 0) {
        UIOpenURLContext *urlContext = connectionOptions.URLContexts.allObjects.firstObject;
        NSURL *url = urlContext.URL;
        if (url) {
            [self.appLinkServices handleAppLinkWithIncomingURL:url];
        }
    }

    // Handle Universal Link via user activity when app is cold started
    if (connectionOptions.userActivities.count > 0) {
        NSUserActivity *userActivity = connectionOptions.userActivities.allObjects.firstObject;
        if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
            NSURL *url = userActivity.webpageURL;
            if (url) {
                [self.appLinkServices handleAppLinkWithIncomingURL:url];
            }
        }
    }
    self.appLinkServices = [AppLinkService shared];
    UIWindowScene *windowScene = (UIWindowScene *)scene;
    self.window = [[UIWindow alloc] initWithWindowScene:windowScene];
    
    // Set root view controller
    self.window.rootViewController = [[ViewController alloc] init];
    [self.window makeKeyAndVisible];
}

- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity {
    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
        NSURL *incomingURL = userActivity.webpageURL;
        if (incomingURL) {
            [self.appLinkServices handleAppLinkWithIncomingURL:incomingURL];
        }
    }
}
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
    UIOpenURLContext *urlContext = [URLContexts anyObject];
    if (urlContext) {
        NSURL *url = urlContext.URL;
        [self.appLinkServices handleAppLinkWithIncomingURL:url];
    }
}
@end

note

For testing purposes:

• Click the referral link, it should redirect you to the App Store.
• To retrieve the latest referral data, you must uninstall the app, then reinstall it, and fetch the referral again.

Run your App and Setup your AppLink services

Run your app by using Xcode on iOS simulators or any physical device to make sure it builds correctly.

For more details explore the example