Troubleshooting - iOS SDK - Airbridge Help Center

[Xcode 27] SceneDelegate Migration Required — Additional Setup Needed for Airbridge Deep Links

This troubleshooting guide is for customers who need to migrate an existing AppDelegate-based app to the SceneDelegate (UIScene lifecycle).

Problem

When you run an app built with Xcode 27, the screen appears blank (white) or the app does not render properly.
Airbridge deep link events are not collected even when the app is opened through a scheme deep link or Universal Link.
The app does not work even though the code was added using the AppDelegate approach shown in the Initialize SDK and Set up deep linking developer guide examples.

Cause

Apple is moving the app lifecycle from the UIApplicationDelegate-only AppDelegate model to the UIScene-based SceneDelegate model, and adopting the Scene lifecycle has effectively become required in the latest Xcode and iOS environments.When an app adopts the Scene lifecycle through UIApplicationSceneManifest, the following AppDelegate callbacks are no longer called.

Existing `AppDelegate` callback	Replacement callback in the Scene lifecycle (`SceneDelegate`)
`window` creation in `application:didFinishLaunchingWithOptions:`	`scene:willConnectToSession:options:`
Deep link at app cold start	`connectionOptions` of `scene:willConnectToSession:options:`
`application:open:options:` (`application:openURL:options:`)	`scene:openURLContexts:`
`application:continue:restorationHandler:`	`scene:continue:` (`scene:continueUserActivity:`)

Solution

Swift
Objective-C

Deep link when the app is terminated	In `scene:willConnectTo:options:`, call `Airbridge.trackDeeplink(connectionOptions:)` with `connectionOptions`, and then call `Airbridge.handleDeeplink(connectionOptions:)`
Scheme deep link (background)	In `scene:openURLContexts:`, call `Airbridge.trackDeeplink(openURLContexts:)` with `URLContexts`, and then call `Airbridge.handleDeeplink(openURLContexts:)`
Universal Link (background)	In `scene:continue:`, call `Airbridge.trackDeeplink(userActivity:)` with `userActivity`, and then call `Airbridge.handleDeeplink(userActivity:)`

Deep link when the app is terminated	In `scene:willConnectToSession:options:`, call `[Airbridge trackDeeplinkWithConnectionOptions:]` with `connectionOptions`, and then call `[Airbridge handleDeeplinkWithConnectionOptions:onSuccess:]`
Scheme deep link (background)	In `scene:openURLContexts:`, call `[Airbridge trackDeeplinkWithOpenURLContexts:]` with `URLContexts`, and then call `[Airbridge handleDeeplinkWithOpenURLContexts:onSuccess:]`
Universal Link (background)	In `scene:continueUserActivity:`, call `[Airbridge trackDeeplinkWithUserActivity:]` with `userActivity`, and then call `[Airbridge handleDeeplinkWithUserActivity:onSuccess:]`

1. Add Scene Manifest to Info.plist

Add the following UIApplicationSceneManifest to Info.plist.Set the UISceneDelegateClassName value to match the language/module you use.

Objective-C: SceneDelegate
Swift: $(PRODUCT_MODULE_NAME).SceneDelegate

<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <false/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>UIWindowSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>Default Configuration</string>
                <key>UISceneDelegateClassName</key>
                <string>SceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

2. Create SceneDelegate and move the deep link collection code to SceneDelegate

Swift
Objective-C

import UIKit
import Airbridge

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func handleAirbridgeDeeplink(url: URL) {
        // Display the content for this URL.
    }

    func scene(_ scene: UIScene,
               willConnectTo session: UISceneSession,
               options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = scene as? UIWindowScene else { return }

        let appDelegate = UIApplication.shared.delegate as? AppDelegate
        let window = UIWindow(windowScene: windowScene)
        window.rootViewController = appDelegate?.window?.rootViewController
        self.window = window
        appDelegate?.window = window
        window.makeKeyAndVisible()

        Airbridge.trackDeeplink(connectionOptions: connectionOptions)
        let isAirbridgeDeeplink = Airbridge.handleDeeplink(connectionOptions: connectionOptions) { url in
            self.handleAirbridgeDeeplink(url: url)
        }
        if isAirbridgeDeeplink { return }
        // Handle other deep links with your existing logic.
    }

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        Airbridge.trackDeeplink(openURLContexts: URLContexts)
        let isAirbridgeDeeplink = Airbridge.handleDeeplink(openURLContexts: URLContexts) { url in
            self.handleAirbridgeDeeplink(url: url)
        }
        if isAirbridgeDeeplink { return }
        // Handle other deep links with your existing logic.
    }

    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        Airbridge.trackDeeplink(userActivity: userActivity)
        let isAirbridgeDeeplink = Airbridge.handleDeeplink(userActivity: userActivity) { url in
            self.handleAirbridgeDeeplink(url: url)
        }
        if isAirbridgeDeeplink { return }
        // Handle other deep links with your existing logic.
    }
}

#import <UIKit/UIKit.h>

API_AVAILABLE(ios(13.0))
@interface SceneDelegate : UIResponder <UIWindowSceneDelegate>

@property (strong, nonatomic) UIWindow *window;

@end

#import "SceneDelegate.h"
#import "AppDelegate.h"
#import <Airbridge/Airbridge.h>

@implementation SceneDelegate

- (void)handleAirbridgeDeeplink:(NSURL *)url {
        // Display the content for this URL.
}

- (void)scene:(UIScene *)scene
        willConnectToSession:(UISceneSession *)session
                                  options:(UISceneConnectionOptions *)connectionOptions
{
    if (![scene isKindOfClass:[UIWindowScene class]]) {
        return;
    }
    UIWindowScene *windowScene = (UIWindowScene *)scene;

    AppDelegate *appDelegate = (AppDelegate *)UIApplication.sharedApplication.delegate;
    UIWindow *window = [[UIWindow alloc] initWithWindowScene:windowScene];
    window.rootViewController = appDelegate.window.rootViewController;
    self.window = window;
    appDelegate.window = window;
    [window makeKeyAndVisible];

    [Airbridge trackDeeplinkWithConnectionOptions:connectionOptions];
    BOOL isAirbridgeDeeplink = [Airbridge handleDeeplinkWithConnectionOptions:connectionOptions onSuccess:^(NSURL* url) {
        [self handleAirbridgeDeeplink:url];
    }];
    if (isAirbridgeDeeplink) { return; }
    // Handle other deep links with your existing logic.
}

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
{
    [Airbridge trackDeeplinkWithOpenURLContexts:URLContexts];
    BOOL isAirbridgeDeeplink = [Airbridge handleDeeplinkWithOpenURLContexts:URLContexts onSuccess:^(NSURL* url) {
        [self handleAirbridgeDeeplink:url];
    }];
    if (isAirbridgeDeeplink) { return; }
    // Handle other deep links with your existing logic.
}

- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity
{
    [Airbridge trackDeeplinkWithUserActivity:userActivity];
    BOOL isAirbridgeDeeplink = [Airbridge handleDeeplinkWithUserActivity:userActivity onSuccess:^(NSURL* url) {
        [self handleAirbridgeDeeplink:url];
    }];
    if (isAirbridgeDeeplink) { return; }
    // Handle other deep links with your existing logic.
}

@end

3. Clean up AppDelegate

Keep the SDK initialization code (Airbridge.initializeSDK(option:), Objective-C: [Airbridge initializeSDKWithOption:]) in application:didFinishLaunchingWithOptions: as is.
The trackDeeplink and handleDeeplink calls added to application:open:options: (application:openURL:options:) and application:continue:restorationHandler: for deep link collection are not called in the Scene lifecycle. After moving them to SceneDelegate, remove them from AppDelegate.
If you created the window and set rootViewController in application:didFinishLaunchingWithOptions:, move that code to scene:willConnectTo:options: in SceneDelegate as well. In the Scene lifecycle, SceneDelegate owns the window, so the screen will not appear if the code remains in AppDelegate.

Issue

When running an app built with the Airbridge iOS SDK in a Swift 6 environment, the app crashes when the closures passed to functions such as handleDeeplink and handleDeferredDeeplink are invoked.Affected functions

Airbridge.handleDeeplink
Airbridge.handleDeferredDeeplink
Airbridge.createTrackingLink
Airbridge.click
Airbridge.impression
AirbridgeOptionBuilder.setOnAttributionReceived

Cause

In Swift 5.x and earlier, the compiler only issued warnings even when there was a risk of a data race caused by multiple threads accessing the same memory at the same time. In Swift 6, any data or closure that may move to and run on another thread or actor-isolated context must be proven safe to transfer across threads. Otherwise, the compiler may raise a compile-time error, or a runtime crash may occur when building with backward compatibility.

Solution

When using Airbridge SDK functions that receive closures as parameters, explicitly add the @Sendable annotation before the closure parameter variable to tell the compiler that the data can be safely transferred across threads.

Deep Link Install or Deep Link Open not occurring, resulting in standard Install or Open

Problem

To trigger a Deep Link Install or Deep Link Open, the trackDeeplink method must be called before the didBecomeActive state in the iOS Lifecycle. If trackDeeplink is called after didBecomeActive, it will be recorded as an Organic Install or Open.

Cause

The Deep Link Install or Deep Link Open events are not generated; instead, standard Install or Open events occur.

Solution

Please ensure that trackDeeplink is called before didBecomeActive.By setting the setLogLevel to Debug in the AirbridgeOptionBuilder, you can verify the following logs in sequential order:

Following app state detected: state=didDeeplink
Following app state detected: state=didBecomeActive

CocoaPods cannot find version 4.7.0

During the deployment of version 4.7.1, an issue occurred where version 4.7.0 was accidentally removed. The 4.7.0 version has since been redistributed to CocoaPods.If CocoaPods is unable to find the version, or if you encounter a checksum error with the installed Pods, please follow the steps below.

pod cache clean --all
pod repo remove trunk
pod setup 

pod install --repo-update

The domain of saved passwords appears as airbridge.io or abr.ge

Problem

Users may see the domain of passwords stored with the Password AutoFill feature as airbridge.io or abr.ge.

Cause

After setting up deep links for the Airbridge SDK, if you utilize the Password AutoFill feature, the domain is saved as the applinks domain of the Airbridge deep link, which is airbridge.io or abr.ge.

Solution

The problem can be solved by setting up the webcredentials domain used in the Password AutoFill.

Prepare the domain that will store the password.
Host the JSON below at https://YOUR_DOMAIN/.well-known/apple-app-site-association with Content-Type: application/json. Your prepared domain should be entered instead of YOUR_DOMAIN.

You can find the App ID Prefix and Bundle ID in the [Identifiers]>[YOUR_APP] menu of the Apple Developer Portal.

{
    "webcredentials": {
        "apps": ["YOUR_APP_ID_PREFIX.YOUR_BUNDLE_ID"]
    }
}

Navigate to [YOUR_PROJECT]>[Signing & Capabilities] in Xcode.
Click + Capability to add Associated Domains. Enter webcredentials:YOUR_DOMAIN in Associated Domains.

Upload Symbol Failed on Xcode

Problem

Upon uploading the app to the App Store, Xcode displays a warning message that a dSYM for the Airbridge framework was not included.

Cause

The Airbridge iOS SDK does not support dSYM.

Solution

The dSYM will be supported in the coming update. You may ignore this warning.

​Problem

​Cause

​Solution

1. Add Scene Manifest to Info.plist

2. Create SceneDelegate and move the deep link collection code to SceneDelegate

3. Clean up AppDelegate

​Issue

​Cause

​Solution

Problem

Cause

Solution

​Problem

​Cause

​Solution

​Problem

​Cause

​Solution

Problem

Cause

Solution

Issue

Cause

Solution

Problem

Cause

Solution

Problem

Cause

Solution