트러블 슈팅 - 엑스포 SDK (Deprecated)

[Xcode 27] SceneDelegate 전환 필수화 및 Airbridge 딥링크 추가 설정 안내

이 문서는 Xcode 27에서 SceneDelegate(UIScene 생명주기) 채택이 필수화되면서 발생하는 문제와 해결 방법을 안내합니다. Deprecated Airbridge Expo SDK도 Expo SDK 58에서 추가 코드 작성 없이 딥링크가 수집되지만, 신규 기능과 대응이 제한되므로 최신 Airbridge Expo SDK로의 마이그레이션을 권장합니다.

문제 현상

Xcode 27에서 빌드한 앱이 실행되지 않고 즉시 종료됩니다.
Scene 생명주기를 채택하기 위해 UIApplicationSceneManifest를 추가하면, 이번에는 앱이 흰 화면으로 표시되고 화면이 그려지지 않습니다.
스킴 딥링크(Scheme Deeplink) 또는 유니버설 링크(Universal Links)로 앱에 진입해도 Airbridge 딥링크 이벤트가 수집되지 않습니다.
app.json에 Airbridge config plugin을 설정했는데도 동작하지 않습니다.

발생 원인

이 문제는 Airbridge SDK 설정이 아니라, 사용 중인 Expo SDK 버전이 UIScene 생명주기를 지원하지 않아 발생합니다.Apple은 앱 생명주기를 UIApplicationDelegate(AppDelegate) 단독 방식에서 UIScene 기반(SceneDelegate) 방식으로 전환하고 있으며, iOS 27 SDK(Xcode 27)로 빌드한 앱은 UIScene 생명주기를 채택하지 않으면 실행되지 않고 즉시 종료됩니다.그런데 Expo SDK 57 이하의 prebuild 템플릿은 SceneDelegate를 생성하지 않고, Info.plist에 UIApplicationSceneManifest도 추가하지 않습니다. AppDelegate가 application:didFinishLaunchingWithOptions:에서 window를 만들어 React Native를 시작하고, 딥링크는 application:openURL:·application:continueUserActivity:로 받는 구조입니다.이 상태에서 UIApplicationSceneManifest만 추가해 Scene 생명주기를 채택하면, 위 AppDelegate 콜백은 Scene 생명주기에서 호출되지 않습니다. 그래서 window가 화면에 표시되지 않아 흰 화면이 되고, 딥링크도 앱에 전달되지 않습니다. Deprecated Airbridge Expo SDK는 딥링크를 AirbridgeAppDelegate(ExpoAppDelegateSubscriber)에서 AirbridgeRN.deeplink() API로 수집하며 이 subscriber 역시 같은 AppDelegate 콜백으로 호출되므로, Airbridge 딥링크 수집도 함께 멈춥니다.

SDK 초기화는 application:didFinishLaunchingWithOptions:에서 수행되며, 이 콜백은 Scene 생명주기에서도 호출되므로 영향을 받지 않습니다. 딥링크 수집만 동작하지 않습니다.

해결 방법

Expo SDK 58 이상으로 업그레이드하세요. Expo SDK 58부터는 expo prebuild가 SceneDelegate와 Info.plist의 UIApplicationSceneManifest를 생성하고, Expo가 scene 이벤트를 AppDelegate로 다시 전달합니다. 그 결과 Deprecated SDK를 사용하는 경우에도 SceneDelegate를 직접 작성하거나 딥링크 수집 코드를 추가할 필요가 없습니다.

Expo SDK 58은 2026년 10월 기준 정식 릴리스 전 베타 단계이며 npm next 태그로 배포되고 있습니다. (latest 태그는 Expo SDK 57) 프로덕션에 적용하기 전에 충분히 검증하시기 바랍니다. 정식 릴리스 이후에는 next 태그 대신 npx expo install expo@latest로 설치하세요. 버전과 태그는 npm expo versions에서 확인할 수 있습니다.

1. Expo SDK 58로 업그레이드

npx expo install expo@next
npx expo install --fix

특정 버전으로 고정하려면 npx expo install expo@58.0.6과 같이 버전을 직접 지정합니다.

2. Airbridge SDK 버전 확인

Deprecated SDK를 계속 사용하는 경우 최신 2.x 버전을 사용하세요.

npm install --save airbridge-expo-sdk@sdk-v2
npm install --save airbridge-react-native-sdk@2.10.1

3. 네이티브 프로젝트 재생성

npx expo prebuild --clean

ios/ 디렉터리를 저장소에 커밋해 직접 관리하는 경우(Bare workflow), npx expo prebuild --clean은 네이티브 프로젝트에 직접 적용한 수정사항을 덮어씁니다. 이 경우 prebuild를 실행하는 대신 Expo SDK 업그레이드 가이드를 참고해 SceneDelegate와 Info.plist의 UIApplicationSceneManifest 변경 사항을 네이티브 프로젝트에 직접 반영하세요.

4. 동작 확인

앱이 종료된 상태와 백그라운드 상태 각각에서 스킴 딥링크·유니버설 링크로 진입한 뒤, airbridge.deeplink.setDeeplinkListener() 콜백 수신과 Airbridge 대시보드의 딥링크 이벤트 수집을 확인합니다.

딥링크는 airbridge.deeplink.setDeeplinkListener() 콜백과 React Native Linking의 url 이벤트에 모두 전달됩니다. 두 곳에서 각각 화면 이동을 처리하면 같은 링크가 두 번 처리될 수 있으므로 라우팅은 한 곳에서만 처리하세요.

Deprecated Airbridge Expo SDK는 더 이상 기능이 추가되지 않습니다. iOS·Android 최신 OS 대응과 신규 기능을 사용하려면 최신 Airbridge Expo SDK로 마이그레이션하세요.

expo-route

기존에 expo-route 를 사용중인 경우 SDK 설치 후 expo-route 기능이 동작 하지 않습니다.Airbridge tracking link 를 통해서 app 진입 시 진입한 링크를 airbridge 를 통해서 scheme deeplink 로 변환 처리 후 route 처리가 되어야 합니다. 그러나 expo-router 로 인해 route 처리가 중복, 잘못된 이동 등과 같은 옳지 않은 방향으로 처리 될 수 있습니다.그리하여 Airbridge Expo SDK 에서 Deeplink 를 route 처리되도록 설계 되었습니다.아래 코드와 같이 airbridge.deeplink.setDeeplinkListener 내에서 route 되도록 처리 해주세요.

import * as Router from 'expo-router';

const router = Router.useRouter();

airbridge.deeplink.setDeeplinkListener((_deeplink) => {
  // route deeplink
  router.push(...);
});

Webcredentials

App 에서 Autofill 기능을 사용해 비밀번호를 저장하는 경우 webcredentials:... 설정이 되어 있지 않으면 비밀번호가 applinks:YOUR_APP_NAME.airbridge.io 또는 applinks:YOUR_APP_NAME.abr.ge 의 도메인에 저장됩니다.비밀번호가 저장되는 도메인을 변경하고 싶다면, example.com 을 설정할 도메인 으로 변경해서 아래와 같이 설정해주세요.

https://example.com/.well-known/apple-app-site-association주소에서 아래 내용을 호스팅 합니다.

{
    "webcredentials": {
        "apps": ["TEAM_ID.APP_BUNDLE_ID"]
    }
}

예) 9JA89QQLNQ.com.apple.wwdc

app.json 에 webcredentials:example.com을 추가해주세요.

{
  "expo": {
    "ios": {
      "associatedDomains": [
        "webcredentials:example.com"
      ]
    }
  }
}

​문제 현상

​발생 원인

​해결 방법

​1. Expo SDK 58로 업그레이드

​2. Airbridge SDK 버전 확인

​3. 네이티브 프로젝트 재생성

​4. 동작 확인

문제 현상

발생 원인

해결 방법

1. Expo SDK 58로 업그레이드

2. Airbridge SDK 버전 확인

3. 네이티브 프로젝트 재생성

4. 동작 확인