Troubleshooting - Flutter SDK (Deprecated)

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

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

Problem

An app built with Xcode 27 (iOS 27 SDK) fails to launch and terminates immediately with the runtime issue UIScene life cycle is required for apps built with this SDK.
After the Scene lifecycle is adopted, an EXC_BAD_ACCESS (code=1, address=0x0) crash occurs near GeneratedPluginRegistrant.register(with:) and the app terminates immediately.
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 iOS setup and iOS deep link setup 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:`
`application:openURL:options:`	`scene:openURLContexts:`
`application:continueUserActivity:restorationHandler:`	`scene:continueUserActivity:`
Deep link at app cold start	`connectionOptions` of `scene:willConnectToSession:options:`

Solution

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)	Extract `NSUserActivity` from `userActivities` and call `handleUserActivity:`

1. Add Scene Manifest to Info.plist

Add the following UIApplicationSceneManifest to Info.plist.Set UISceneDelegateClassName to match the language/module you use, and be sure to set UISceneStoryboardFile to Main.(Without this value, FlutterViewController is not created as the scene’s rootViewController, so plugin registration fails.)

UISceneDelegateClassName
- 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>
                <key>UISceneStoryboardFile</key>
                <string>Main</string>
            </dict>
        </array>
    </dict>
</dict>

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

Swift
Objective-C

import UIKit
import Flutter
import airbridge_flutter_sdk

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

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

        if let controller = window?.rootViewController as? FlutterViewController {
            GeneratedPluginRegistrant.register(with: controller)
        }

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

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        if let context = URLContexts.first {
            AirbridgeFlutter.deeplink.handleURLSchemeDeeplink(context.url)
        }
    }

    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        AirbridgeFlutter.deeplink.handle(userActivity)
    }
}

Add SceneDelegate.h / SceneDelegate.m

#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 <Flutter/Flutter.h>
#import "GeneratedPluginRegistrant.h"
#import <airbridge_flutter_sdk/AirbridgeFlutter.h>

@implementation SceneDelegate

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

    if ([self.window.rootViewController isKindOfClass:[FlutterViewController class]]) {
        FlutterViewController *controller = (FlutterViewController *)self.window.rootViewController;
        [GeneratedPluginRegistrant registerWithRegistry:controller];
    }

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

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
{
    UIOpenURLContext *context = URLContexts.allObjects.firstObject;
    if (context != nil) {
        [AirbridgeFlutter.deeplink handleURLSchemeDeeplink:context.URL];
    }
}

- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity
{
    [AirbridgeFlutter.deeplink handleUserActivity:userActivity];
}

@end

3. Clean up AppDelegate

Leave the SDK initialization code (Swift: AirbridgeFlutter.initSDK(appName:appToken:withLaunchOptions:), Objective-C: [AirbridgeFlutter initSDKWithAppName:appToken: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.
GeneratedPluginRegistrant.register(with: self) relies on FlutterAppDelegate building the plugin registrar through self.window.rootViewController (FlutterViewController). In the Scene lifecycle the window is owned by the SceneDelegate, so AppDelegate’s self.window becomes nil. As a result the registrar is returned as nil, and a plugin that dereferences this nil triggers an EXC_BAD_ACCESS (address=0x0) crash. Therefore plugin registration (GeneratedPluginRegistrant.register) must be moved to the SceneDelegate, where FlutterViewController exists.

import UIKit
import Flutter
import airbridge_flutter_sdk

@main
@objc class AppDelegate: FlutterAppDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        AirbridgeFlutter.initSDK(appName: "YOUR_APP_NAME", appToken: "YOUR_APP_TOKEN", withLaunchOptions: launchOptions)

        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

Bitcode Compile Error

An error like the one below may occur when creating iOS builds with Flutter SDK v3.0.1 or later as the Bitcod is not supported.

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)

Flutter SDK v3.0.1+ is updated to Airbridge iOS SDK v1.28.0+, and Bitcode is no longer supported. Refer to the Bitcode compile error guide for more details.

settings.gradle (Android only)

If you encounter the error message “Plugin project ... not found. Please update settings.gradle,” edit the android/settings.gradle file as shown below.

include ':app'

def flutterProjectRoot = rootProject.projectDir.parentFile.toPath()

def plugins = new Properties()
def pluginsFile = new File(flutterProjectRoot.toFile(), '.flutter-plugins')
if (pluginsFile.exists()) {
    pluginsFile.withReader('UTF-8') { reader -> plugins.load(reader) }
}

plugins.each { name, path ->
    def pluginDirectory = flutterProjectRoot.resolve(path).resolve('android').toFile()
    include ":$name"
    project(":$name").projectDir = pluginDirectory
}

Could not find or use auto-linked library...

Flutter issue: https://github.com/flutter/flutter/issues/16049Airbridge Flutter SDK is a Swift plugin, and an error occurs when the Swift Plugin is used in a 100% Objective C project uses the Swift Plugin.To solve this issue, click File > New > File... > Swift File to create an empty Swift file and a bridge header.This issue does not occur when using Objective C & Swift Project and 100% Swift Project.

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