트러블 슈팅 - iOS SDK - Airbridge Help Center

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

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

문제 현상

Xcode 27에서 빌드한 앱을 실행하면 화면이 흰 화면으로 표시되거나, 앱이 정상적으로 그려지지 않습니다.
스킴 딥링크(Scheme Deeplink) 또는 유니버설 링크(Universal Links)로 앱에 진입해도 Airbridge 딥링크 이벤트가 수집되지 않습니다.
개발자 가이드의 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:open:options:`(`application:openURL:options:`)	`scene:openURLContexts:`
`application:continue:restorationHandler:`	`scene:continue:`(`scene:continueUserActivity:`)

해결 방법

Swift
Objective-C

앱이 꺼진 상태에서 딥링크	`scene:willConnectTo:options:`에서 `connectionOptions`로 `Airbridge.trackDeeplink(connectionOptions:)` 호출 후 `Airbridge.handleDeeplink(connectionOptions:)` 호출
스킴 딥링크(백그라운드)	`scene:openURLContexts:`에서 `URLContexts`로 `Airbridge.trackDeeplink(openURLContexts:)` 호출 후 `Airbridge.handleDeeplink(openURLContexts:)` 호출
유니버설 링크(백그라운드)	`scene:continue:`에서 `userActivity`로 `Airbridge.trackDeeplink(userActivity:)` 호출 후 `Airbridge.handleDeeplink(userActivity:)` 호출

앱이 꺼진 상태에서 딥링크	`scene:willConnectToSession:options:`에서 `connectionOptions`로 `[Airbridge trackDeeplinkWithConnectionOptions:]` 호출 후 `[Airbridge handleDeeplinkWithConnectionOptions:onSuccess:]` 호출
스킴 딥링크(백그라운드)	`scene:openURLContexts:`에서 `URLContexts`로 `[Airbridge trackDeeplinkWithOpenURLContexts:]` 호출 후 `[Airbridge handleDeeplinkWithOpenURLContexts:onSuccess:]` 호출
유니버설 링크(백그라운드)	`scene:continueUserActivity:`에서 `userActivity`로 `[Airbridge trackDeeplinkWithUserActivity:]` 호출 후 `[Airbridge handleDeeplinkWithUserActivity:onSuccess:]` 호출

1. Info.plist에 Scene Manifest 추가

Info.plist에 아래 UIApplicationSceneManifest를 추가합니다.UISceneDelegateClassName 값은 사용하는 언어/모듈에 맞게 지정합니다.

Objective-C: SceneDelegate
Swift: $(PRODUCT_MODULE_NAME).SceneDelegate

<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로 이전

Swift
Objective-C

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.
    }
}

#import <UIKit/UIKit.h>

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

@property (strong, nonatomic) UIWindow *window;

@end

#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

3. AppDelegate 정리

SDK 초기화 코드(Airbridge.initializeSDK(option:), Objective-C: [Airbridge initializeSDKWithOption:])는 application:didFinishLaunchingWithOptions:에 그대로 둡니다.
딥링크 수집을 위해 작성했던 application:open:options:(application:openURL:options:)와 application:continue:restorationHandler:의 trackDeeplink/handleDeeplink 호출 코드는 Scene 생명주기에서 호출되지 않으므로, SceneDelegate로 이전한 뒤 AppDelegate에서는 삭제합니다.
application:didFinishLaunchingWithOptions:에서 window를 생성하고 rootViewController를 설정했다면, 해당 코드도 SceneDelegate의 scene:willConnectTo:options:로 이전해야 합니다. Scene 생명주기에서는 window를 SceneDelegate가 소유하므로, AppDelegate에 남겨두면 화면이 표시되지 않습니다.

Swift 6환경에서 handleDeeplink 및 handleDeferredDeeplink 함수등에서 입력한 Closure가 호출되는 시점에 앱이 종료되는 현상

문제 현상

Swift 6환경에서 handleDeeplink 및 handleDeferredDeeplink 함수등에서 입력한 Closure가 호출되는 시점에 앱이 크래시되는 현상영향을 받는 함수

Airbridge.handleDeeplink
Airbridge.handleDeferredDeeplink
Airbridge.createTrackingLink
Airbridge.click
Airbridge.impression
AirbridgeOptionBuilder.setOnAttributionReceived

발생 원인

Swift 5.x 이하에서는 멀티스레드 환경에서 여러 스레드가 동시에 같은 메모리에 접근하는 데이터 레이스 위험이 있어도 컴파일러가 경고만 주었으나 Swift 6 환경에서는 컴파일러 단계에서 다른 스레드(Actor 격리 영역)로 넘어가서 실행될 수 있는 모든 데이터와 클로저는 스레드 간 이동이 안전하다는 것을 반드시 증명해야 하며, 그렇지 않으면 컴파일 에러를 발생시키거나 하위 호환성 빌드 시 런타임 크래시를 유발합니다.

해결 방법

에어브릿지 SDK에서 클로저를 파라미터로 받는 함수를 사용할 때, 클로저 내부 변수 앞에 @Sendable 어노테이션을 명시적으로 추가하여 데이터가 스레드 간에 안전하게 전달됨을 컴파일러에게 알려야 합니다.

Airbridge.handleDeferredDeeplink() { @Sendable url in 
    if let url {
        // Deep link handling logic
    }
}

Deep Link Install(Open)이 발생하지 않고 Organic Install(Open)이 발생합니다.

문제 원인

iOS Lifecycle의 didBecomeActive 이전에 trackDeeplink를 호출해야 Deep link Install 혹은 Deep link Open이 발생합니다. didBecomeActive 이후에 trackDeeplink를 발생했을 경우에 Organic Install 혹은 Open이 발생합니다.

발생 현상

Deeplink Install 혹은 Deeplink Open이 발생하지 않고 Install(Open)이 발생 합니다.

해결 방법

didBecomeActive 이전에 trackDeeplink 를 호출 해 주세요. AirbridgeOptionBuilder에서 setLogLevel 을 Debug로 설정하면 다음과 같은 로그를 순차적으로 확인 할 수 있습니다.

Following app state detected: state=didDeeplink
Following app state detected: state=didBecomeActive

4.9.0 업데이트시에 Airbridge Symbol을 찾을 수 없는 현상

문제 현상

4.x.x에서 4.9.0으로 SDK를 업데이트하여 빌드 했을 때, `Undefined symbol: static Airbridge.Airbridge.~` 오류로 인해서 빌드가 되지 않습니다.

발생 원인

Xcode 빌드 캐시와 업데이트된 바이너리 간의 불일치로 인해 발생하는 링크 오류로 발생됩니다.

해결 방법

Xcode에서 Clean Build Folder 를 실행한 후 재빌드해 주세요.

CocoaPods이 4.7.0 버전을 찾지 못하는 문제

4.7.1배포 도중에 4.7.0이 삭제되는 이슈가 발생하여, 4.7.0에 대한 버전이 CocoaPods에 재배포가 되었습니다.CocoaPods이 버전을 찾지 못하거나, 설치한 Pods에 대해서 Checksum 오류가 표시된다면 다음을 진행 해 주세요.

pod cache clean --all
pod repo remove trunk
pod setup 

pod install --repo-update

저장된 암호의 도메인이 airbridge.io 또는 abr.ge로 보이는 문제

문제 현상

Password AutoFill 기능으로 저장된 암호의 도메인이 airbridge.io 또는 abr.ge로 보이는 현상이 앱을 사용하는 유저에게 발생할 수 있습니다.

발생 원인

에어브릿지 SDK의 딥링크를 설정한 후에 Password AutoFill 기능을 활용하면 도메인이 에어브릿지 딥링크의 앱 링크(applinks) 도메인 airbridge.io 또는 abr.ge로 저장됩니다.

해결 방법

Password AutoFill에 사용하는 webcredentials 도메인을 설정하면 문제를 해결할 수 있습니다.

암호를 저장하는 도메인을 준비해주세요.
아래 JSON을 https://YOUR_DOMAIN/.well-known/apple-app-site-association에 Content-Type: application/json으로 호스팅합니다. 준비한 도메인이 YOUR_DOMAIN입니다.

애플 개발자 대시보드의 [Identifiers]>[YOUR_APP]에서 App ID Prefix, Bundle ID를 확인할 수 있습니다.

{
    "webcredentials": {
        "apps": ["YOUR_APP_ID_PREFIX.YOUR_BUNDLE_ID"]
    }
}

Xcode의 [YOUR_PROJECT]>[Signing & Capabilities]로 이동합니다.
’+ Capability’를 클릭해 Associated Domains를 추가합니다. Associated Domains에 webcredentials:YOUR_DOMAIN을 입력합니다.

Xcode에서 Upload Symbol Failed 경고 메시지가 뜨는 현상

문제 현상

App Store에 앱 업로드 시 Xcode에 Airbridge framework에 dSYM이 포함되어 있지 않다는 경고 메세지가 나타나는 현상

발생 원인

Airbridge iOS SDK에서 dSYM을 지원하고 있지 않습니다.

해결 방법

다음 버전에서 dSYM 지원을 개발 중에 있습니다. 해당 경고는 무시해 주세요.

​문제 현상

​발생 원인

​해결 방법

1. Info.plist에 Scene Manifest 추가

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

3. AppDelegate 정리

​문제 현상

​발생 원인

​해결 방법

문제 원인

발생 현상

해결 방법

​문제 현상

​발생 원인

​해결 방법

​문제 현상

​발생 원인

​해결 방법

​문제 현상

​발생 원인

​해결 방법

문제 현상

발생 원인

해결 방법

문제 현상

발생 원인

해결 방법

문제 현상

발생 원인

해결 방법

문제 현상

발생 원인

해결 방법

문제 현상

발생 원인

해결 방법