Troubleshooting - React Native SDK (Deprecated)

[Xcode 27] Mandatory SceneDelegate Migration and Additional Airbridge Deep Link Settings

NoticeThis document is a troubleshooting guide for customers who need to migrate an existing AppDelegate-based app to UIScene (SceneDelegate).

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 to AppDelegate as shown in the Project Setup (iOS) and Deep Link Setup > Project Setup (iOS) 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 deep link 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:openURL:options:`	`scene:openURLContexts:`
`application:continueUserActivity:restorationHandler:`	`scene:continueUserActivity:`

Solution

State	Handling method
Deep link when the app is terminated	In `scene:willConnectToSession:options:`, from `connectionOptions` - Extract `URL` from `URLContexts` and call `handleURLSchemeDeeplink:` - Extract `NSUserActivity` from `userActivities` and call `handleUserActivity:`
Scheme deep link (background)	Extract `URL` from `URLContexts` and call `handleURLSchemeDeeplink:`
Universal Link (background)	Pass the `NSUserActivity` received by `scene:continueUserActivity:` to `handleUserActivity:`

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 React
import AirbridgeRN

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

    // when terminated app is opened with scheme deeplink or universal links
    func scene(_ scene: UIScene,
               willConnectTo session: UISceneSession,
               options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = scene as? UIWindowScene else { return }

        // Move the root view controller created by RCTAppDelegate in
        // didFinishLaunching to the Scene-owned window and display it.
        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()

        // track deeplink
        if let context = connectionOptions.urlContexts.first {
            AirbridgeRN.deeplink().handleURLSchemeDeeplink(context.url)
        }
        if let userActivity = connectionOptions.userActivities.first {
            AirbridgeRN.deeplink().handle(userActivity)
        }
    }

    // when backgrounded app is opened with scheme deeplink
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        // track deeplink
        if let context = URLContexts.first {
            AirbridgeRN.deeplink().handleURLSchemeDeeplink(context.url)
        }
    }

    // when backgrounded app is opened with universal links
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        // track deeplink
        AirbridgeRN.deeplink().handle(userActivity)
    }
}

Add SceneDelegate.h / SceneDelegate.m.

// SceneDelegate.h
#import <UIKit/UIKit.h>

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

@property (strong, nonatomic) UIWindow *window;

@end

// SceneDelegate.m
#import "SceneDelegate.h"
#import "AppDelegate.h"
#import <AirbridgeRN/AirbridgeRN.h>

@implementation SceneDelegate

// when terminated app is opened with scheme deeplink or universal links
- (void)scene:(UIScene *)scene
        willConnectToSession:(UISceneSession *)session
                     options:(UISceneConnectionOptions *)connectionOptions
{
    if (![scene isKindOfClass:[UIWindowScene class]]) {
        return;
    }
    UIWindowScene *windowScene = (UIWindowScene *)scene;

    // Move the root view controller created by RCTAppDelegate in
    // didFinishLaunching to the Scene-owned window and display it.
    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];

    // track deeplink
    UIOpenURLContext *context = connectionOptions.URLContexts.allObjects.firstObject;
    if (context != nil) {
        [AirbridgeRN.deeplink handleURLSchemeDeeplink:context.URL];
    }
    NSUserActivity *userActivity = connectionOptions.userActivities.allObjects.firstObject;
    if (userActivity != nil) {
        [AirbridgeRN.deeplink handleUserActivity:userActivity];
    }
}

// when backgrounded app is opened with scheme deeplink
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
{
    // track deeplink
    UIOpenURLContext *context = URLContexts.allObjects.firstObject;
    if (context != nil) {
        [AirbridgeRN.deeplink handleURLSchemeDeeplink:context.URL];
    }
}

// when backgrounded app is opened with universal links
- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity
{
    // track deeplink
    [AirbridgeRN.deeplink handleUserActivity:userActivity];
}

@end

3. Clean up AppDelegate

Leave the SDK initialization code (Objective-C: [AirbridgeRN getInstance:appName:withLaunchOptions:], Swift: AirbridgeRN.getInstance(_:appName:withLaunchOptions:)) in application:didFinishLaunchingWithOptions: as is.
The application:openURL:options: and application:continueUserActivity:restorationHandler: methods you wrote to collect deep links are not called in the Scene lifecycle, so after moving them to SceneDelegate, delete them from AppDelegate.

Update 1.X.X → 2.X.X

The event API has been replaced to the below.

/**
 * Send event to server.
 * @param {string} category event name
 * @param {EventOption} [option={}] event options
 */
trackEvent(category: string, option?: EventOption): void;

Refer to the React native 2.X.X migration guide for details.

Bitcode Compile Error

An error like below may occur when creating iOS builds with React Native SDK v1.5.0+.

ld: XCFrameworkIntermediates/AirBridge/AirBridge.framework/AirBridge(AirBridge-arm64-master.o)' does not contain bitcode. You must rebuild it with bitcode enabled (Xcode setting ENABLE_BITCODE)

Since React Native SDK v1.5.0+ uses Airbridge iOS SDK v1.28.0+, Bitcode is no longer supported. Please refer to the Bitcode compile error guide for more details.

Resolve Airbridge SDK backup rules merge conflict issue

Reference : Android SDK Auto Backup

If you are experiencing build errors caused by overlapping of the Airbridge SDK backup rules and third-party SDK backup rules, please refer to the workaround below.e.g) If you have an Airbridge SDK backup rule and an Appsflyer SDK backup rule that overlap, you will see the build error below.

Attribute application@fullBackupContent value=(@xml/appsflyer_backup_rules) from [com.appsflyer:af-android-sdk:6.6.1] AndroidManifest.xml:14:18-73
is also present at [io.airbridge:sdk-android:2.14.0] AndroidManifest.xml:27:18-78 value=(@xml/airbridge_auto_backup_rules).
Suggestion: add 'tools:replace="android:fullBackupContent"' to <application> element at AndroidManifest.xml:7:5-13:19 to override.

To resolve this issue, please set up as follows.

backup_rules.xml setup

Create a android/app/src/main/res/xml folder.
Within the created xml folder, create a file (e.g. custom_backup_rules.xml).
Add the data backup rules defined in the Airbridge SDK as follows.

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <!-- Airbridge Backup Rules -->
    <exclude domain="sharedpref" path="airbridge-internal" />
    <exclude domain="sharedpref" path="airbridge-install" />
    <exclude domain="sharedpref" path="airbridge-user-info" />
    <exclude domain="sharedpref" path="airbridge-user-alias" />
    <exclude domain="sharedpref" path="airbridge-user-attributes" />
    <exclude domain="sharedpref" path="airbridge-device-alias" />
    <exclude domain="database" path="airbridge.db" />

    <!-- Appsflyer Backup Rules -->
    <exclude domain="sharedpref" path="appsflyer-data"/>

    <!-- Your Custom Backup Rules -->
</full-backup-content>

AndroidManifest.xml setup

<manifest
    ...
    xmlns:tools="http://schemas.android.com/tools">

    <application
        ...
        android:allowBackup="true"
        android:fullBackupContent="@xml/custom_backup_rules"
        tools:replace="android:fullBackupContent">

​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

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