> ## 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 - iOS SDK

<AccordionGroup>
  <Accordion title="[Xcode 27] SceneDelegate Migration Required — Additional Setup Needed for Airbridge Deep Links">
    <Note>
      This troubleshooting guide is for customers who need to migrate an existing AppDelegate-based app to the `SceneDelegate` (UIScene lifecycle).
    </Note>

    #### 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](/en/developers/ios-sdk-v4#initialize-sdk) and [Set up deep linking](/en/developers/ios-sdk-v4#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

    <Tabs>
      <Tab title="Swift">
        | 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:)` |
      </Tab>

      <Tab title="Objective-C">
        | 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:]` |
      </Tab>
    </Tabs>

    ##### 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`

    ```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>
                </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 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.
            }
        }
        ```
      </Tab>

      <Tab title="Objective-C">
        ```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 <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
        ```
      </Tab>
    </Tabs>

    ##### 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`.
  </Accordion>

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

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

    ```markdown lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    Following app state detected: state=didDeeplink
    Following app state detected: state=didBecomeActive
    ```
  </Accordion>

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

    ```bash lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    pod cache clean --all
    pod repo remove trunk
    pod setup 

    pod install --repo-update
    ```
  </Accordion>

  <Accordion title="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](https://developer.apple.com/documentation/security/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.

    1. Prepare the domain that will store the password.
    2. 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](https://developer.apple.com/account/resources).

    ```json lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    {
        "webcredentials": {
            "apps": ["YOUR_APP_ID_PREFIX.YOUR_BUNDLE_ID"]
        }
    }
    ```

    3. Navigate to **\[YOUR\_PROJECT]>\[Signing & Capabilities]** in Xcode.
    4. Click **+ Capability** to add Associated Domains. Enter `webcredentials:YOUR_DOMAIN` in Associated Domains.
  </Accordion>

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

<link rel="alternate" hrefLang="en" href="https://help.airbridge.io/en/developers/troubleshooting-ios-sdk-v4" />

<link rel="alternate" hrefLang="ko" href="https://help.airbridge.io/ko/developers/troubleshooting-ios-sdk-v4" />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.