> ## 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 - Expo SDK
This document explains the issue caused by the mandatory adoption of `SceneDelegate` (the UIScene life cycle) in Xcode 27, and how to resolve it. The Airbridge Expo SDK works under the Scene life cycle **from Expo SDK 58 without any additional code**.
### Symptoms
* An app built with Xcode 27 fails to launch and quits immediately.
* After adding `UIApplicationSceneManifest` to adopt the Scene life cycle, the app shows a blank screen and fails to render.
* Airbridge deep link events are not collected when the app is opened through a scheme deep link or a universal link.
* The Airbridge config plugin is set in `app.json` as described in the developer guide, but it does not work.
### Cause
This is not caused by the Airbridge SDK configuration. It happens because **the Expo SDK version in use does not support the UIScene life cycle**.
Apple is moving the app life cycle from `UIApplicationDelegate` (AppDelegate) to the `UIScene`-based (SceneDelegate) model, and **an app built with the iOS 27 SDK (Xcode 27) fails to launch and quits immediately unless it adopts the UIScene life cycle**.
However, the prebuild template of Expo SDK 57 and earlier does not generate a `SceneDelegate` and does not add `UIApplicationSceneManifest` to `Info.plist`. Instead, the `AppDelegate` (`ExpoAppDelegate`) creates the `window` and starts React Native in `application:didFinishLaunchingWithOptions:`, and receives deep links through `application:openURL:` and `application:continueUserActivity:`.
If you adopt the Scene life cycle by adding only `UIApplicationSceneManifest` in that state, those AppDelegate callbacks are no longer called under the Scene life cycle. The `window` is not displayed, which leaves a blank screen, and deep links are not delivered to the app either. The Airbridge Expo SDK collects deep links in `AirbridgeAppDelegate` (`ExpoAppDelegateSubscriber`), which is invoked through the same AppDelegate callbacks, so Airbridge deep link collection stops as well.
SDK initialization runs in `application:didFinishLaunchingWithOptions:`, which is still called under the Scene life cycle, so it is not affected. Only deep link collection stops working.
### Solution
**Upgrade to Expo SDK 58 or later.** From Expo SDK 58, `expo prebuild` generates `SceneDelegate.swift` and adds `UIApplicationSceneManifest` to `Info.plist`, and Expo forwards scene events back to the AppDelegate. As a result, the deep link collection in `AirbridgeAppDelegate` is called as before, so **you do not need to write a `SceneDelegate` or add Airbridge deep link collection code yourself.**
As of October 2026, Expo SDK 58 is still a **pre-release (beta)** and is published under the npm `next` tag, while the `latest` tag still points to Expo SDK 57. Validate it thoroughly before applying it to production. Once Expo SDK 58 is generally available, install it with `npx expo install expo@latest` instead of the `next` tag. See [npm expo versions](https://www.npmjs.com/package/expo?activeTab=versions) for versions and tags.
#### 1. Upgrade to Expo SDK 58
```shell lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
npx expo install expo@next
npx expo install --fix
```
To pin a specific version, specify it directly, for example `npx expo install expo@58.0.6`.
#### 2. Install the latest Airbridge SDK
```shell lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
npm install --save airbridge-expo-sdk@latest
npm install --save airbridge-react-native-sdk@latest
```
#### 3. Regenerate the native project
```shell lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
npx expo prebuild --clean
```
If you commit and manage the `ios/` directory yourself (bare workflow), `npx expo prebuild --clean` overwrites the changes you applied directly to the native project. In that case, instead of running prebuild, follow the [Expo SDK upgrade guide](https://docs.expo.dev/workflow/upgrading-expo-sdk-walkthrough/) and apply the `SceneDelegate` and `Info.plist` `UIApplicationSceneManifest` changes to your native project yourself.
#### 4. Check the deep link settings
The scheme, `associatedDomains`, and Android `intentFilters` settings remain the same as in the existing developer guide. See [Initialize SDK](/en/developers/expo-sdk-v4#initialize-sdk) and [Set up deep linking](/en/developers/expo-sdk-v4#set-up-deep-linking).
#### 5. Verify the behavior
Open the app through a scheme deep link and a universal link, both when the app is **terminated** and when it is **in the background**, then confirm that the deep link events are collected in the Airbridge dashboard.
A deep link is delivered to **both** the Airbridge `Airbridge.setOnDeeplinkReceived` callback and the React Native `Linking` `url` event. If both places perform navigation, the same link can be handled twice, so handle routing in only one place. To receive an Airbridge tracking link converted back into its original scheme deep link, handle it in `Airbridge.setOnDeeplinkReceived`; `Linking` receives the URL before conversion.
## 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.
## 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
The expo-route deosn't work after installing the SDK for users who have been using it before the SDK installation.
## Cause
When the app is launched via the Airbridge tracking link, Airbridge converts the deep link to a scheme deep link before routing it. However, due to the expo-router, the routing process may be duplicated, or the redirection may be processed incorrectly.
Therefore, the Airbridge Expo SDK has been designed to route the Deeplink.
## Solution
Make sure to be routed within the `Airbridge.setOnDeeplinkReceived` as in the following code.
```dart lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
import { Airbridge } from 'airbridge-react-native-sdk';
import * as Router from 'expo-router';
const router = Router.useRouter();
Airbridge.setOnDeeplinkReceived((result) => {
// route deeplink
router.push(...);
});
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.