> ## Documentation Index
> Fetch the complete documentation index at: https://help.airbridge.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting - Flutter SDK (Deprecated)

<AccordionGroup>
  <Accordion title="[Xcode 27] SceneDelegate Migration Required — Additional Setup Needed for Airbridge Deep Links">
    <Note>
      **Attention**

      This troubleshooting guide is for customers who need to migrate an existing AppDelegate-based app to `SceneDelegate` and the UIScene lifecycle.
    </Note>

    ### 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](/en/developers/deprecated-flutter-sdk-v3#for-ios) and [iOS deep link setup](/en/developers/deprecated-flutter-sdk-v3#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`<br />  • extract `URL` from `URLContexts` and call `handleURLSchemeDeeplink:`<br />  • 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`

    ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    <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

    <Tabs>
      <Tab title="Swift">
        ```swift lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        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)
            }
        }
        ```
      </Tab>

      <Tab title="Objective-C">
        Add `SceneDelegate.h` / `SceneDelegate.m`

        ```objective-c lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        #import <UIKit/UIKit.h>

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

        @property (strong, nonatomic) UIWindow *window;

        @end
        ```

        ```objective-c lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        #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
        ```
      </Tab>
    </Tabs>

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

    ```swift lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    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)
        }
    }
    ```
  </Accordion>

  <Accordion title="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.

    ```Text theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    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](/en/developers/troubleshooting-deprecated-ios-sdk-v1#bitcode-compile-error) for more details.
  </Accordion>

  <Accordion title="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.

    ```groovy lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    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
    }
    ```
  </Accordion>

  <Accordion title="Could not find or use auto-linked library...">
    Flutter issue: [https://github.com/flutter/flutter/issues/16049](https://github.com/flutter/flutter/issues/16049)

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

  <Accordion title="Resolve Airbridge SDK backup rules merge conflict issue">
    * Reference : [Android SDK Auto Backup](/en/developers/troubleshooting-deprecated-android-sdk-v2#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.

    ```html lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    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.

    <AccordionGroup>
      <Accordion title="backup_rules.xml setup">
        1. Create a `android/app/src/main/res/xml` folder.
        2. Within the created xml folder, create a file (e.g. `custom_backup_rules.xml`).
        3. Add the data backup rules defined in the Airbridge SDK as follows.

        ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        <?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>
        ```
      </Accordion>

      <Accordion title="AndroidManifest.xml setup">
        ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        <manifest
            ...
            xmlns:tools="http://schemas.android.com/tools">

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