트러블 슈팅 - 코도바-아이오닉 SDK (Deprecated)

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

알립니다이 문서는 기존 AppDelegate 기반 앱을 UIScene(SceneDelegate)로 전환해야 하는 고객을 위한 트러블슈팅 가이드입니다.

문제 현상

Xcode 27에서 빌드한 앱을 실행하면 화면이 흰 화면으로 표시되거나, 앱이 정상적으로 그려지지 않습니다.
스킴 딥링크(Scheme Deeplink) 또는 유니버설 링크(Universal Links)로 앱에 진입해도 Airbridge 딥링크 이벤트가 수집되지 않습니다.
setDeeplinkListener 콜백이 호출되지 않습니다.
개발자 가이드의 SDK 설치와 딥링크 설정 예제대로 AppDelegate에 코드를 작성했는데도 동작하지 않습니다.

발생 원인

Apple은 앱 생명주기를 UIApplicationDelegate(AppDelegate) 단독 방식에서 UIScene 기반(SceneDelegate) 방식으로 전환하고 있으며, 최신 Xcode/iOS에서는 Scene 생명주기 채택이 사실상 필수가 되었습니다.앱이 UIApplicationSceneManifest를 통해 Scene 생명주기를 채택하면, 다음 AppDelegate 콜백은 더 이상 호출되지 않습니다.

기존 `AppDelegate` 콜백	Scene 생명주기에서의 대체 콜백 (`SceneDelegate`)
`application:didFinishLaunchingWithOptions:`에서의 `window` 생성	`scene:willConnectToSession:options:`
앱 콜드 스타트 시점의 딥링크	`scene:willConnectToSession:options:`의 `connectionOptions`
`application:openURL:options:`	`scene:openURLContexts:`
`application:continueUserActivity:restorationHandler:`	`scene:continueUserActivity:`

cordova-ios 7.x 이하에서는 CDVAppDelegate가 application:didFinishLaunchingWithOptions:에서 window와 MainViewController를 생성합니다.Scene 생명주기에서는 window를 SceneDelegate가 소유하므로 이 window가 화면에 표시되지 않아 흰 화면이 발생합니다.

해결 방법

작업 내용은 cordova-ios 플랫폼 버전에 따라 다릅니다.cordova platform ls로 버전을 확인한 뒤, 아래 각 단계에서 해당하는 탭을 선택해 주세요.

알립니다cordova-ios 8.0.0 / 8.0.1의 CDVSceneDelegate에는 scene:continueUserActivity: 구현이 없어, 아래 코드를 적용하면 유니버설 링크로 앱에 진입할 때 앱이 종료됩니다.cordova-ios 8.1.0 이상으로 업데이트한 뒤 적용해 주세요.

	cordova-ios 8.1.0 이상	cordova-ios 7.x 이하
앱이 꺼진 상태에서 딥링크	스킴 딥링크는 `CDVSceneDelegate`가 `scene:openURLContexts:`로 전달하므로 별도 처리 불필요 유니버설 링크만 `scene:willConnectToSession:options:`의 `userActivities`에서 `NSUserActivity`를 꺼내 `handleUserActivity:` 호출	`scene:willConnectToSession:options:`에서 `connectionOptions` - `URLContexts`에서 `URL`을 꺼내 `handleURLSchemeDeeplink:` 호출 - `userActivities`에서 `NSUserActivity`를 꺼내 `handleUserActivity:` 호출
스킴 딥링크(백그라운드)	`scene:openURLContexts:`에서 `URLContexts`의 `URL`을 꺼내 `handleURLSchemeDeeplink:` 호출	동일
유니버설 링크(백그라운드)	`scene:continueUserActivity:`에서 `NSUserActivity`를 `handleUserActivity:` 호출	동일

알립니다platforms/ios 하위 파일은 cordova platform rm/add 시 초기화됩니다.config.xml의 <config-file>·<source-file>이나 훅(hook)으로 관리하거나, platforms 디렉터리를 형상 관리에 포함해 주세요.

1. Info.plist에 Scene Manifest 추가

알립니다UISceneDelegateClassName 값은 SceneDelegate를 구현한 언어에 맞춰야 합니다.**Swift는 $(PRODUCT_MODULE_NAME).SceneDelegate, Objective-C는 SceneDelegate**입니다.Swift 클래스는 Objective-C 런타임에 <모듈>.SceneDelegate로 등록되기 때문이며, 값이 맞지 않으면 scene 연결에 실패해 흰 화면이 발생합니다.

cordova-ios 8.1.0 이상
cordova-ios 7.x 이하

platforms/ios/App/App-Info.plist에 기본 포함되어 있습니다.값이 누락되지 않았는지만 확인해 주세요.UISceneStoryboardFile에 Main이 반드시 지정되어 있어야 하며, 이 값이 없으면 흰 화면이 발생합니다.

<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>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
                <key>UISceneStoryboardFile</key>
                <string>Main</string>
            </dict>
        </array>
    </dict>
</dict>

platforms/ios/YOUR_PROJECT_NAME/YOUR_PROJECT_NAME-Info.plist에 아래 UIApplicationSceneManifest를 추가합니다.cordova-ios 7.x 이하에는 Main.storyboard가 없으므로 UISceneStoryboardFile은 지정하지 않습니다.

<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. SceneDelegate 생성 및 딥링크 수집 코드를 SceneDelegate로 이전

아래 코드는 각 cordova-ios 버전의 기본 템플릿 언어(8.1.0 이상은 Swift, 7.x 이하는 Objective-C)를 기준으로 합니다.다른 언어로 구현하는 경우 아래를 함께 적용해 주세요.

cordova-ios 8.1.0 이상을 Objective-C로 구현하는 경우: 기본 제공되는 App/SceneDelegate.swift를 삭제하고, App-Info.plist의 UISceneDelegateClassName을 SceneDelegate로 변경합니다. AirbridgeCO 호출을 위해 #import "AirbridgeCO.h"를 추가해 주세요.
cordova-ios 7.x 이하를 Swift로 구현하는 경우: UISceneDelegateClassName을 $(PRODUCT_MODULE_NAME).SceneDelegate로 변경하고, 플랫폼이 기본 제공하는 platforms/ios/YOUR_PROJECT_NAME/Bridging-Header.h에 #import "AppDelegate.h", #import "MainViewController.h", #import <Cordova/CDVPlugin.h>, #import "AirbridgeCO.h"를 추가합니다.

cordova-ios 8.1.0 이상
cordova-ios 7.x 이하

platforms/ios/App/SceneDelegate.swift를 아래와 같이 수정합니다.

import Cordova

class SceneDelegate: CDVSceneDelegate {
    override func scene(
        _ scene: UIScene,
        willConnectTo session: UISceneSession,
        options connectionOptions: UIScene.ConnectionOptions
    ) {
        // CDVSceneDelegate forwards URL contexts to scene(_:openURLContexts:).
        super.scene(scene, willConnectTo: session, options: connectionOptions)

        // CDVSceneDelegate does not forward user activities.
        if let userActivity = connectionOptions.userActivities.first {
            self.scene(scene, continue: userActivity)
        }
    }

    override func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        // Required to notify other Cordova plugins of the URL.
        super.scene(scene, openURLContexts: URLContexts)

        if let context = URLContexts.first {
            AirbridgeCO.deeplink().handleURLSchemeDeeplink(context.url)
        }
    }

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

platforms/ios/YOUR_PROJECT_NAME/Classes 하위에 아래 두 파일을 추가하고, Xcode에서 앱 타겟에 포함시킵니다.

// SceneDelegate.h
#import <UIKit/UIKit.h>

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

@property (strong, nonatomic) UIWindow *window;

@end

// SceneDelegate.m
#import "SceneDelegate.h"
#import "AppDelegate.h"
#import "MainViewController.h"
#import <Cordova/CDVPlugin.h>
#import "AirbridgeCO.h"

@implementation SceneDelegate

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

    // SceneDelegate owns the window in the Scene lifecycle.
    MainViewController *viewController = [[MainViewController alloc] init];
    self.window = [[UIWindow alloc] initWithWindowScene:windowScene];
    self.window.autoresizesSubviews = YES;
    self.window.rootViewController = viewController;
    [self.window makeKeyAndVisible];

    // Preserve properties read by existing code.
    AppDelegate *appDelegate = (AppDelegate *)UIApplication.sharedApplication.delegate;
    appDelegate.window = self.window;
    appDelegate.viewController = viewController;

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

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
{
    UIOpenURLContext *context = URLContexts.allObjects.firstObject;
    if (context == nil) {
        return;
    }

    [self postCordovaOpenURLNotificationWithContext:context];
    [AirbridgeCO.deeplink handleURLSchemeDeeplink:context.URL];
}

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

// Replaces CDVAppDelegate's URL notification dispatch for other Cordova plugins.
- (void)postCordovaOpenURLNotificationWithContext:(UIOpenURLContext *)context API_AVAILABLE(ios(13.0))
{
    if (context.URL == nil) {
        return;
    }

    [[NSNotificationCenter defaultCenter] postNotificationName:CDVPluginHandleOpenURLNotification
                                                          object:context.URL];

    NSMutableDictionary *openURLData = [[NSMutableDictionary alloc] init];
    [openURLData setValue:context.URL forKey:@"url"];
    [openURLData setValue:context.options.sourceApplication forKey:@"sourceApplication"];
    [openURLData setValue:context.options.annotation forKey:@"annotation"];
    [[NSNotificationCenter defaultCenter]
        postNotificationName:CDVPluginHandleOpenURLWithAppSourceAndAnnotationNotification
                      object:openURLData];
}

@end

알립니다cordova-ios 8.1.0 이상에서 scene(_:willConnectTo:options:)에 connectionOptions.urlContexts로 handleURLSchemeDeeplink(_:)을 추가로 호출하면 안 됩니다.CDVSceneDelegate가 scene(_:openURLContexts:)로 다시 전달하므로 콜드 스타트 시 딥링크가 두 번 수집됩니다.

3. AppDelegate 정리

SDK 초기화 코드(getInstance:appName:withLaunchOptions:)는 application:didFinishLaunchingWithOptions:에 그대로 둡니다.
딥링크 수집을 위해 작성했던 application:openURL:options:와 application:continueUserActivity:restorationHandler:는 Scene 생명주기에서 호출되지 않으므로, SceneDelegate로 이전한 뒤 AppDelegate에서는 삭제합니다.
cordova-ios 7.x 이하에서는 self.viewController = [[MainViewController alloc] init];와 return [super application:application didFinishLaunchingWithOptions:launchOptions];를 삭제하고 return YES;로 변경합니다. CDVAppDelegate의 기본 구현이 window와 CDVViewController를 새로 생성하므로, 그대로 두면 화면에 표시되지 않는 두 번째 Cordova 웹뷰가 생성됩니다.

Update 1.X.X → 2.X.X

기존에 있던 event 전송 API 가 삭제 되고 아래의 API 로 대체 되었습니다.

/**
 * Send event to server.
 * @param {string} category event name
 * @param {EventOption} [option={}] event options
 */
trackEvent(category: string, option?: EventOption): void;

Cordova 2.X.X migration guide 에서 자세한 내용을 확인하세요.

Bitcode 컴파일 에러

Cordova Ionic PhoneGap SDK 2.0.1 이상의 버전으로 iOS 빌드 시 Bitcode 를 지원하지 않아서 아래와 같이 에러가 발생 할 수 있습니다.

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)

Cordova Ionic PhoneGap SDK 2.0.1 버전 부터 Airbridge iOS SDK 1.28.0 버전 으로 업데이트 되었습니다. Airbridge iOS SDK 는 1.28.0 버전 부터 Bitcode 를 지원하지 않습니다.해당 에러 발생 시 아래 가이드를 참고 바랍니다.

Bitcode 컴파일 에러 가이드

Update 1.1.X → 1.2.X

구버전 SDK 를 uninstall 해주세요.

Cordova
Ionic
PhoneGap

cordova plugin remove airbridge-cordova-sdk

ionic cordova plugin remove airbridge-cordova-sdk

phonegap plugin remove airbridge-cordova-sdk

신버전 SDK 를 install 해주세요.

Cordova
Ionic
PhoneGap

cordova plugin add airbridge-cordova-sdk

ionic cordova plugin add airbridge-cordova-sdk

phonegap plugin add airbridge-cordova-sdk

Android

android/app/src/main/java/.../MainActivity파일에 다음 코드를 수정해주세요.

-     AirbridgeCO.getDeeplink().fetch(getIntent())
+     AirbridgeCO.processDeeplinkData(getIntent())

iOS

ios/[프로젝트 이름]/AppDelegate파일의 다음 코드를 수정해주세요.

-     AirbridgeCO.deeplink()?.handleURLSchemeDeeplink(url, withSourceBundle: sourceApplication)
+     AirbridgeCO.deeplink()?.handleURLSchemeDeeplink(url)

설정

프로젝트 폴더에 airbridge.json 파일을 생성해주세요.
JSON 형식으로 설정값을 넣어주세요.

Exmaple

{
    "sessionTimeoutSeconds": 300,
    "autoStartTrackingEnabled": true,
    "userInfoHashEnabled": true,
    "trackAirbridgeLinkOnly": false,
    "facebookDeferredAppLinkEnabled": false,
    "locationCollectionEnabled": false
    "trackingAuthorizeTimeoutSeconds": 0
}

설명

이름	타입	기본값	설명
sessionTimeoutSeconds	number	300	설정한 세션기간 내에 유저가 앱을 재실행하는 경우에는, 같은 세션으로 판단하여 앱 실행 이벤트를 전송하지 않습니다.
autoStartTrackingEnabled	boolean	true	false 로 설정하면, Airbridge.state.startTracking() 을 호출하기 전까지 이벤트를 전송하지 않습니다.
userInfoHashEnabled	boolean	true	false 로 설정하면, User Email 및 User Phone 정보를 Hash 하지않고 이벤트를 전송합니다.
trackAirbridgeLinkOnly	boolean	false	true 로 설정하면, Airbridge 딥링크로 앱이 열린 경우에만 딥링크 이벤트를 전송합니다.
facebookDeferredAppLinkEnabled	boolean	false	true 로 설정하고 Facebook SDK 가 설치되어 있으면, Facebook Deferred AppLink 를 수집합니다.
locationCollectionEnabled	boolean	false	true 로 설정하면, 해당 기기의 위치 정보를 수집합니다. (Android 전용) 사용하기 위해서는 AndroidManifest.xml 에 아래 2개 권한이 필요합니다. android.permission.ACCESS_FINE_LOCATION android.permission.ACCESS_COARSE_LOCATION

Update 1.0.X → 1.1.X

Install

구버전 SDK 를 uninstall 해주세요.

Cordova
Ionic
PhoneGap

cordova plugin remove airbridge-cordova-sdk

ionic cordova plugin remove airbridge-cordova-sdk

phonegap plugin remove airbridge-cordova-sdk

신버전 SDK 를 install 해주세요.

Cordova
Ionic
PhoneGap

cordova plugin add airbridge-cordova-sdk

ionic cordova plugin add airbridge-cordova-sdk

phonegap plugin add airbridge-cordova-sdk

Javascript

DeeplinkListener

getInitialDeeplink 함수를 제거하고 setDeeplinkListener 함수만 사용해주세요.

- Airbridge.deeplink.getInitialDeeplink().then((deeplink) => {
-
- });
.
. Airbridge.deeplink.setDeeplinkListner((deeplink) => {
.
. });

Android

AndroidManifest.xml

android/app/src/main/AndroidManifest.xml 파일의 MainActivity 영역에 아래와 같은 intent-filter 문장을 삽입해주세요.

+ <intent-filter android:autoVerify="true">
+     <action android:name="android.intent.action.VIEW" />
+
+     <category android:name="android.intent.category.DEFAULT" />
+     <category android:name="android.intent.category.BROWSABLE" />
+
+     <data android:scheme="http" android:host="YOUR_APP_NAME.deeplink.page" />
+     <data android:scheme="https" android:host="YOUR_APP_NAME.deeplink.page" />
+ </intent-filter>
. <intent-filter android:autoVerify="true">
.     <action android:name="android.intent.action.VIEW" />
.
.     <category android:name="android.intent.category.DEFAULT" />
.     <category android:name="android.intent.category.BROWSABLE" />
.
.     <data android:scheme="http" android:host="YOUR_APP_NAME.airbridge.io" />
.     <data android:scheme="https" android:host="YOUR_APP_NAME.airbridge.io" />
. </intent-filter>
. <intent-filter>
.     <action android:name="android.intent.action.VIEW" />
.
.     <category android:name="android.intent.category.DEFAULT" />
.     <category android:name="android.intent.category.BROWSABLE" />
.
.     <data android:scheme="EXAMPLE_SCHEME" />
. </intent-filter>

MainActivity.java

android/app/src/main/java/.../MainActivity.java 을 수정해주세요.

. import co.ab180.airbridge.cordova.AirbridgeCO;
.
. public class MainActivity extends ReactActivity {
+     @Override
+     protected void onResume() {
+         super.onResume();
+
+         AirbridgeCO.getDeeplink().fetch(getIntent());
+     }
+
.     @Override
.     public void onNewIntent(Intent intent) {
.         super.onNewIntent(intent);
.         setIntent(intent);
.     }
. }

iOS

Xcode

Universal Link

Xcode > Project 파일 > Signing & Capabilities > Associated Domains 로 이동해주세요.
+버튼을 눌러 applinks:YOUR_APP_NAME.deeplink.page를 추가해주세요.

YOUR_APP_NAME 은 대시보드의 ‘App Setting > 앱 기본정보’ 에서 확인할 수 있습니다.

AppDelegate.m

ios/.../AppDelegate.m 을 수정해주세요.

. - (BOOL)application:(UIApplication *)application
.             openURL:(NSURL *)url
.             options:(NSDictionary<UIApplicationOpenURLOptionsKey, id>*)options
. {
-     [AirbridgeCO.instance handleURLSchemeDeeplink:url
-                                withSourceBundle:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
+     [AirbridgeCO.deeplink handleURLSchemeDeeplink:url
+                                withSourceBundle:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
.
.     return YES;
. }
.
. - (BOOL)application:(UIApplication*)application
.             openURL:(NSURL*)url
.   sourceApplication:(NSString*)sourceApplication
.          annotation:(id)annotation
. {
-     [AirbridgeCO.instance handleURLSchemeDeeplink:url
-                                withSourceBundle:sourceApplication];
+     [AirbridgeCO.deeplink handleURLSchemeDeeplink:url
+                                withSourceBundle:sourceApplication];
.
.     return YES;
. }

iOS 8.x 또는 그 이전 버전을 target 한다면 아래와 같은 코드를 추가로 수정해주세요.

. -  (BOOL)application:(UIApplication*)application
. continueUserActivity:(NSUserActivity*)userActivity
.   restorationHandler:(void (^)(NSArray* _Nullable))restorationHandler
. {
-     [AirbridgeCO.instance handleUniversalDeeplink:userActivity.webpageURL];
+     [AirbridgeCO.deeplink handleUniversalLink:userActivity.webpageURL];
.
.     return YES;
. }

​문제 현상

​발생 원인

​해결 방법

​1. Info.plist에 Scene Manifest 추가

​2. SceneDelegate 생성 및 딥링크 수집 코드를 SceneDelegate로 이전

​3. AppDelegate 정리

Android

iOS

설정

Exmaple

설명

Install

Javascript

DeeplinkListener

Android

AndroidManifest.xml

MainActivity.java

iOS

Xcode

AppDelegate.m

문제 현상

발생 원인

해결 방법

1. Info.plist에 Scene Manifest 추가

2. SceneDelegate 생성 및 딥링크 수집 코드를 SceneDelegate로 이전

3. AppDelegate 정리