트러블 슈팅 - 플러터 SDK (Deprecated)

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

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

문제 현상

Xcode 27(iOS 27 SDK)로 빌드한 앱이 실행되지 않고 UIScene life cycle is required for apps built with this SDK 런타임 이슈와 함께 즉시 종료됩니다.
Scene 생명주기를 채택한 뒤에는 GeneratedPluginRegistrant.register(with:) 부근에서 EXC_BAD_ACCESS (code=1, address=0x0) 크래시가 발생하며 앱이 즉시 종료됩니다.
스킴 딥링크(Scheme Deeplink) 또는 유니버설 링크(Universal Links)로 앱에 진입해도 Airbridge 딥링크 이벤트가 수집되지 않습니다.
개발자 가이드의 프로젝트 설정 > iOS 설정과 딥링크 설정 > iOS 딥링크 설정 예제대로 AppDelegate에 코드를 작성했는데도 동작하지 않습니다.

발생 원인

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

기존 `AppDelegate` 콜백	Scene 생명주기에서의 대체 콜백 (`SceneDelegate`)
`application:didFinishLaunchingWithOptions:`에서의 `window` 생성	`scene:willConnectToSession:options:`
`application:openURL:options:`	`scene:openURLContexts:`
`application:continueUserActivity:restorationHandler:`	`scene:continueUserActivity:`
앱이 꺼진 상태에서 딥링크	`scene:willConnectToSession:options:`의 `connectionOptions`

해결 방법

앱이 꺼진 상태에서 딥링크	`scene:willConnectToSession:options:`에서 `connectionOptions` • `URLContexts`에서 `URL`을 꺼내 `handleURLSchemeDeeplink:` 호출 • `userActivities`에서 `NSUserActivity`를 꺼내 `handleUserActivity:` 호출
스킴 딥링크(백그라운드)	`URLContexts`에서 `URL`을 꺼내 `handleURLSchemeDeeplink:` 호출
유니버설 링크(백그라운드)	`userActivities`에서 `NSUserActivity`를 꺼내 `handleUserActivity:` 호출

1. Info.plist에 Scene Manifest 추가

Info.plist에 아래 UIApplicationSceneManifest를 추가합니다.UISceneDelegateClassName은 사용하는 모듈에 맞게 지정하고, UISceneStoryboardFile에 Main을 반드시 지정합니다.(이 값이 없으면 FlutterViewController가 scene의 rootViewController로 생성되지 않아 플러그인 등록이 실패합니다.)

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>
                <key>UISceneStoryboardFile</key>
                <string>Main</string>
            </dict>
        </array>
    </dict>
</dict>

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

Swift
Objective-C

import UIKit
import Flutter
import airbridge_flutter_sdk

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(_ scene: UIScene,
        willConnectTo session: UISceneSession,
        options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = scene as? UIWindowScene else { return }

        if let controller = window?.rootViewController as? FlutterViewController {
            GeneratedPluginRegistrant.register(with: controller)
        }

        if let context = connectionOptions.urlContexts.first {
            AirbridgeFlutter.deeplink.handleURLSchemeDeeplink(context.url)
        }
        if let userActivity = connectionOptions.userActivities.first {
            AirbridgeFlutter.deeplink.handle(userActivity)
        }
    }

    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        if let context = URLContexts.first {
            AirbridgeFlutter.deeplink.handleURLSchemeDeeplink(context.url)
        }
    }

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

SceneDelegate.h와 SceneDelegate.m을 추가합니다.

#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 <Flutter/Flutter.h>
#import "GeneratedPluginRegistrant.h"
#import <airbridge_flutter_sdk/AirbridgeFlutter.h>

@implementation SceneDelegate

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

    if ([self.window.rootViewController isKindOfClass:[FlutterViewController class]]) {
        FlutterViewController *controller = (FlutterViewController *)self.window.rootViewController;
        [GeneratedPluginRegistrant registerWithRegistry:controller];
    }

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

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts
{
    UIOpenURLContext *context = URLContexts.allObjects.firstObject;
    if (context != nil) {
        [AirbridgeFlutter.deeplink handleURLSchemeDeeplink:context.URL];
    }
}

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

@end

3. AppDelegate 정리

SDK 초기화 코드(Swift: AirbridgeFlutter.initSDK(appName:appToken:withLaunchOptions:), Objective-C: [AirbridgeFlutter initSDKWithAppName:appToken:withLaunchOptions:])는 application:didFinishLaunchingWithOptions:에 그대로 둡니다.
딥링크 수집을 위해 작성했던 application:openURL:options:와 application:continueUserActivity:restorationHandler:는 Scene 생명주기에서 호출되지 않으므로, SceneDelegate로 이전한 뒤 AppDelegate에서는 삭제합니다.
GeneratedPluginRegistrant.register(with: self)는 FlutterAppDelegate가 self.window.rootViewController(FlutterViewController)를 통해 플러그인 레지스트라를 만듭니다. Scene 생명주기에서는 window가 SceneDelegate 소유라 AppDelegate의 self.window가 nil이 됩니다. 그 결과 레지스트라가 nil로 반환되고, 이를 받은 플러그인이 nil을 역참조하면서 EXC_BAD_ACCESS (address=0x0) 크래시가 발생합니다. 따라서 플러그인 등록(GeneratedPluginRegistrant.register)을 반드시 FlutterViewController가 존재하는 SceneDelegate로 이전해야 합니다.

import UIKit
import Flutter
import airbridge_flutter_sdk

@main
@objc class AppDelegate: FlutterAppDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        AirbridgeFlutter.initSDK(appName: "YOUR_APP_NAME", appToken: "YOUR_APP_TOKEN", withLaunchOptions: launchOptions)

        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

Bitcode 컴파일 에러

Flutter SDK 3.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)

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

Bitcode 컴파일 에러 가이드

settings.gradle

Android build 시에 Plugin project ... not found. Please update settings.gradle 에러가 발생하면 android/settings.gradle 파일을 아래와 같이 수정해서 문제를 해결 할 수 있습니다.

include ':app'

def flutterProjectRoot = rootProject.projectDir.parentFile.toPath()

def plugins = new Properties()
def pluginsFile = new File(flutterProjectRoot.toFile(), '.flutter-plugins')
if (pluginsFile.exists()) {
    pluginsFile.withReader('UTF-8') { reader -> plugins.load(reader) }
}

plugins.each { name, path ->
    def pluginDirectory = flutterProjectRoot.resolve(path).resolve('android').toFile()
    include ":$name"
    project(":$name").projectDir = pluginDirectory
}

Could not find or use auto-linked library...

Flutter issue: https://github.com/flutter/flutter/issues/16049Airbridge Flutter SDK 는 swift plugin 이고, Flutter 에는 100% Objective C Project 에서 Swift Plugin 을 사용하면 해당 오류가 발생하는 문제가 있습니다.File > New > File... > Swift File 을 선택해서 File.swift 파일을 생성하고, Bridge Header 를 생성하는 것으로 문제를 해결할 수 있습니다.Objective C & Swift Project 및 100% Swift Project 에서는 발생하지 않는 문제입니다.

에어브릿지 SDK 백업 규칙 병합 충돌 문제

참조 : Android SDK Auto Backup

에어브릿지 SDK 백업 규칙과 서드파티 SDK 백업 규칙 중복 적용으로 인해 빌드 에러가 발생하는 경우 해결 방법은 아래를 참고해주세요.예) 에어브릿지 SDK 백업 규칙과 Appsflyer SDK 백업 규칙이 중복 적용되는 경우 아래와 같은 빌드 에러가 표시됩니다.

Attribute application@fullBackupContent value=(@xml/appsflyer_backup_rules) from [com.appsflyer:af-android-sdk:6.6.1] AndroidManifest.xml:14:18-73
is also present at [io.airbridge:sdk-android:2.14.0] AndroidManifest.xml:27:18-78 value=(@xml/airbridge_auto_backup_rules).
Suggestion: add 'tools:replace="android:fullBackupContent"' to <application> element at AndroidManifest.xml:7:5-13:19 to override.

이 문제를 해결하기 위해서는 아래와 같이 설정해주세요.

backup_rules.xml 설정

android/app/src/main/res/xml 폴더를 생성해주세요.
생성된 xml 폴더 내부에 (e.g. custom_backup_rules.xml) 파일을 생성해주세요.
에어브릿지 SDK에서 정의하는 데이터 백업 규칙을 다음과 같이 추가해 주세요.

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <!-- Airbridge Backup Rules -->
    <exclude domain="sharedpref" path="airbridge-internal" />
    <exclude domain="sharedpref" path="airbridge-install" />
    <exclude domain="sharedpref" path="airbridge-user-info" />
    <exclude domain="sharedpref" path="airbridge-user-alias" />
    <exclude domain="sharedpref" path="airbridge-user-attributes" />
    <exclude domain="sharedpref" path="airbridge-device-alias" />
    <exclude domain="database" path="airbridge.db" />

    <!-- Appsflyer Backup Rules -->
    <exclude domain="sharedpref" path="appsflyer-data"/>

    <!-- Your Custom Backup Rules -->
</full-backup-content>

AndroidManifest.xml 설정

<manifest
    ...
    xmlns:tools="http://schemas.android.com/tools">

    <application
        ...
        android:allowBackup="true"
        android:fullBackupContent="@xml/custom_backup_rules"
        tools:replace="android:fullBackupContent">

​문제 현상

​발생 원인

​해결 방법

​1. Info.plist에 Scene Manifest 추가

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

​3. AppDelegate 정리

문제 현상

발생 원인

해결 방법

1. Info.plist에 Scene Manifest 추가

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

3. AppDelegate 정리