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

# 트러블 슈팅 - 유니티 SDK (Deprecated)

## 안드로이드

<AccordionGroup>
  <Accordion title="Android 기기에서 올바르게 Airbridge Unity가 초기화 되지 않는 경우">
    Airbridge Unity Android의 경우 [Content Provider](https://developer.android.com/guide/topics/providers/content-provider-basics)를 통하여 자동으로 초기화 됩니다. 올바른 초기화 작업을 위하여 `Project > Plugins > Android > AndroidManifest.xml`파일에 다음과 같은 `Xml Tag`가 반드시 올바르게 명시되어야 합니다.

    ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    <provider
        android:authorities="${applicationId}.co.ab180.airbridge.unity.AirbridgeContentProvider"
        android:name="co.ab180.airbridge.unity.AirbridgeContentProvider"
        android:exported="false" />
    ```
  </Accordion>

  <Accordion title="Android 기기에서 사용자가 이미 Custom Activity를 사용하는 경우">
    Airbridge Unity는 올바른 딥링크의 호출을 위해 Custom Activity를 사용하고 있습니다. 사용자가 이미 Custom Activity를 사용하고 있을 경우, 해당 Custom Activity에 아래와 같은 코드를 추가해 주세요.

    ```java lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    @Override
    protected void onNewIntent(Intent intent) {
      super.onNewIntent(intent);
      setIntent(intent);
    }

    @Override
    protected void onResume() {
      super.onResume();
      AirbridgeUnity.processDeeplinkData(getIntent());
    }
    ```
  </Accordion>

  <Accordion title="Android Manifest 파일이 제대로 Merge 되지 않는 경우">
    Airbridge Unity에서 제공되는 Android Manifest Merger는 이미 존재하는 `Project > Plugins > Android > AndroidManifest.xml`를 읽어들여 Airbridge Unity에서 제공되는 `Project > Plugins > Airbridge > Android> AndroidManifest.xml`를 단순하게 Merge 해주는 컴포넌트로서 모든 사용자의 케이스에 맞춰 원하는 형태로 출력하는데 있어서는 한계가 있습니다. 이와 같은 경우 사용자가 직접 해당 `AndroidManifest.xml`를 Merge 해야 합니다.
  </Accordion>

  <Accordion title="Missing 'package' key attribute on element package at ...">
    안드로이드 11 버전의 [`Package Visibility`](https://developer.android.com/training/package-visibility) 정책 추가로 해당 버전을 지원하는 모든 어플리케이션에서 다른 어플리케이션과 올바르게 상호작용하기 위해 어떤 패키지와 상호작용이 이루어 지는지에 대해서 `manifest`의 `<queries>`를 통해 유저에게 올바르게 고지하여야 합니다.

    Airbridge에서는 해당 정책을 준수를 위해 안드로이드 SDK 모듈이 해당 변경사항이 포함되어 있으며 `<queries>` 태그를 지원하기 위해서는 `Gradle` 최소 `5.6.4` 버전 이상 그리고 `Android Gradle Plugin` 최소 `3.6.0` 버전 이상을 필요로 합니다.

    유니티 버전에 따라 어떠한 `Gradle` 버전을 포함하고 있는가에 대해서는 [다음 페이지](https://docs.unity3d.com/Manual/android-gradle-overview.html)를 통해 확인하실 수 있습니다.

    만약 사용하는 유니티의 `Gradle` 버전이 `5.6.4` 버전 미만 혹은 및 `Android Gradle Plugin` 버전이 `3.6.0` 버전 미만인 경우, 다음과 같은 유니티 설정을 통해 버전을 특정하여 사용하실 수 있습니다.

    <AccordionGroup>
      <Accordion title="유니티 2020.1 또는 이후 버전">
        다음 버전들은 `Gradle` 5.6.4 이후 버전과 `Android Gradle Plugin` 3.6.0 이후 버전을 이미 포함하고 있기 때문에 추가적인 작업을 필요로 하지 않습니다.
      </Accordion>

      <Accordion title="유니티 2019.3 버전 ~ 2019.4 버전">
        <Note>
          해당 커스텀 옵션은 유니티 `2019.3 patch 7` 이후의 버전에서만 가능합니다.
        </Note>

        1. [`Gradle Build Tool`](https://gradle.org/releases/) 페이지로 이동하여 `Gradle`5.6.4 이상의 버전을 다운로드해 주세요.
        2. `Preferences > External Tools`로 이동하여 `Gradle Installed with Unity (recommended)` 체크를 해제하고 다운로드 받은 `Gradle`파일의 경로를 다음과 같이 설정해 주세요.

        <Frame>
          <img src="https://mintcdn.com/airbridge-help-center/C5DxUFZdlJVt7nU9/asset/image/unity-external-gradle-path.png?fit=max&auto=format&n=C5DxUFZdlJVt7nU9&q=85&s=13ed05db9e47ff1fa4e0e2e07c43d823" alt="09-en-dev-unity-sdk" width="1226" height="168" data-path="asset/image/unity-external-gradle-path.png" />
        </Frame>

        3. `Project Settings > Player > Android tab > Publishing Settings > Build`로 이동하여 다음 옵션들을 모두 선택해 주세요.
           1. Custom Main Gradle Template
           2. Custom Launcher Gradle Template

        <Frame>
          <img src="https://mintcdn.com/airbridge-help-center/C5DxUFZdlJVt7nU9/asset/image/unity-custom-gradle-templates.png?fit=max&auto=format&n=C5DxUFZdlJVt7nU9&q=85&s=cd62c3c73328339d2f149594a2f3e826" alt="10-en-dev-unity-sdk" width="654" height="322" data-path="asset/image/unity-custom-gradle-templates.png" />
        </Frame>

        4. 다음 자동 생성된 두가지 파일 모두 다음과 같이 변경해 주세요.
           1. `Assets/Plugins/Android/mainTemplate.gradle`
           2. `Assets/Plugins/Android/launcherTemplate.gradle`

        ```groovy lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        buildscript {
            repositories {
                google()
                jcenter()
            }
            dependencies {
                // Must be Android Gradle Plugin 3.6.0 or later. For a list of
                // compatible Gradle versions refer to:
                // https://developer.android.com/studio/releases/gradle-plugin
                classpath 'com.android.tools.build:gradle:3.6.0'
            }
        }
        allprojects {
           repositories {
              google()
              jcenter()
              flatDir {
                dirs 'libs'
              }
           }
        }
        ```
      </Accordion>

      <Accordion title="유니티 2019.1 버전 ~ 2019.2 버전">
        1. [`Gradle Build Tool`](https://gradle.org/releases/) 페이지로 이동하여 `Gradle`5.6.4 이상의 버전을 다운로드해 주세요.
        2. `Preferences > External Tools`로 이동하여 `Gradle Installed with Unity (recommended)`체크를 해제하고 다운로드 받은 `Gradle`파일의 경로를 다음과 같이 설정해 주세요.

        <Frame>
          <img src="https://mintcdn.com/airbridge-help-center/C5DxUFZdlJVt7nU9/asset/image/unity-external-gradle-path.png?fit=max&auto=format&n=C5DxUFZdlJVt7nU9&q=85&s=13ed05db9e47ff1fa4e0e2e07c43d823" alt="12-kr-dev-unity-sdk" width="1226" height="168" data-path="asset/image/unity-external-gradle-path.png" />
        </Frame>

        3. `Project Settings > Player > Android tab > Publishing Settings > Build`로 이동하여 `Custom Gradle Template`옵션을 다음과 같이 선택해 주세요.

        <Frame>
          <img src="https://mintcdn.com/airbridge-help-center/C5DxUFZdlJVt7nU9/asset/image/unity-main-gradle-template.png?fit=max&auto=format&n=C5DxUFZdlJVt7nU9&q=85&s=d247944aa09b8e82d03dd3f054cc5037" alt="13-kr-dev-unity-sdk" width="582" height="140" data-path="asset/image/unity-main-gradle-template.png" />
        </Frame>

        4. 생성된 `Assets/Plugins/Android/mainTemplate.gradle`파일로 이동하여 다음과 같이 변경해 주세요.

        ```groovy lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        buildscript {
            dependencies {
                // Must be Android Gradle Plugin 3.6.0 or later. For a list of
                // compatible Gradle versions refer to:
                // https://developer.android.com/studio/releases/gradle-plugin
                classpath 'com.android.tools.build:gradle:3.6.0'
            }
        }
        ```
      </Accordion>

      <Accordion title="유니티 2018.4 버전">
        <Note>
          해당 커스텀 옵션은 유니티 `2018.4 patch 24` 이후의 버전에서만 가능합니다.
        </Note>

        1. [`Gradle Build Tool`](https://gradle.org/releases/) 페이지로 이동하여 `Gradle`5.6.4 이상의 버전을 다운로드해 주세요.
        2. `Build Settings > Android`로 이동하여 다음 이미지와 같이 `Build System`에서 `Gradle`을 선택해 주세요.

        <Frame>
          <img src="https://mintcdn.com/airbridge-help-center/C5DxUFZdlJVt7nU9/asset/image/unity-android-gradle-build-system.png?fit=max&auto=format&n=C5DxUFZdlJVt7nU9&q=85&s=8de52b2f5edf7fe92bc28dc767e1b2f1" alt="14-kr-dev-unity-sdk" width="1244" height="324" data-path="asset/image/unity-android-gradle-build-system.png" />
        </Frame>

        3. `Preferences > External Tools`로 이동하여 `Gradle Installed with Unity (recommended)`체크를 해제하고 다운로드 받은 `Gradle`파일의 경로를 다음과 같이 설정해 주세요.

        <Frame>
          <img src="https://mintcdn.com/airbridge-help-center/C5DxUFZdlJVt7nU9/asset/image/unity-external-gradle-path.png?fit=max&auto=format&n=C5DxUFZdlJVt7nU9&q=85&s=13ed05db9e47ff1fa4e0e2e07c43d823" alt="15-kr-dev-unity-sdk" width="1226" height="168" data-path="asset/image/unity-external-gradle-path.png" />
        </Frame>

        4. `Project Settings > Player > Android tab > Publishing Settings > Build`로 이동하여 `Custom Gradle Template`옵션을 다음과 같이 선택해 주세요.

        <Frame>
          <img src="https://mintcdn.com/airbridge-help-center/C5DxUFZdlJVt7nU9/asset/image/unity-main-gradle-template.png?fit=max&auto=format&n=C5DxUFZdlJVt7nU9&q=85&s=d247944aa09b8e82d03dd3f054cc5037" alt="16-kr-dev-unity-sdk" width="582" height="140" data-path="asset/image/unity-main-gradle-template.png" />
        </Frame>

        5. 생성된 `Assets/Plugins/Android/mainTemplate.gradle`파일로 이동하여 다음과 같이 변경해 주세요.

        ```groovy lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        buildscript {
            dependencies {
                // Must be Android Gradle Plugin 3.6.0 or later. For a list of
                // compatible Gradle versions refer to:
                // https://developer.android.com/studio/releases/gradle-plugin
                classpath 'com.android.tools.build:gradle:3.6.0'
            }
        }
        ```
      </Accordion>

      <Accordion title="유니티 2018.3 이하 버전">
        `Gradle` 커스터마이즈 옵션은 `2018.3` 버전 이하의 유니티에서는 지원하지 않습니다.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="에어브릿지 SDK 백업 규칙 병합 충돌 문제">
    * 참조 : [Android SDK Auto Backup](/ko/developers/troubleshooting-deprecated-android-sdk-v2#auto-backup)

    에어브릿지 SDK 백업 규칙과 서드파티 SDK 백업 규칙 중복 적용으로 인해 빌드 에러가 발생하는 경우 해결 방법은 아래를 참고해주세요.

    예) 에어브릿지 SDK 백업 규칙과 Appsflyer SDK 백업 규칙이 중복 적용되는 경우 아래와 같은 빌드 에러가 표시됩니다.

    ```html lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    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.
    ```

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

    <AccordionGroup>
      <Accordion title="backup_rules.xml 설정">
        1. 리소스 파일을 저장할 Android 라이브러리 프로젝트(`Assets/Plugins/Android/res.androidlib`)를 생성해주세요.
        2. 생성된 Android 라이브러리 프로젝트 내부에 `AndroidManifest.xml` 파일을 다음과 같이 추가해 주세요.

        ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        <?xml version="1.0" encoding="utf-8"?>
        <manifest xmlns:android="http://schemas.android.com/apk/res/android"
                  package="custom.android.res"
                  android:versionCode="1"
                  android:versionName="1.0">
        </manifest>
        ```

        3. 생성된 Android 라이브러리 프로젝트 내부에 `res/xml` 폴더를 생성해주세요.
        4. 생성된 xml 폴더 내부에 (e.g. `custom_backup_rules.xml`) 파일을 생성해주세요.
        5. 에어브릿지 SDK에서 정의하는 데이터 백업 규칙을 다음과 같이 추가해 주세요.

        ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        <?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>
        ```
      </Accordion>

      <Accordion title="AndroidManifest.xml 설정">
        안드로이드 앱 매니페스트 파일(`Assets/Plugins/Android/AndroidManifest.xml`)에 데이터 백업 규칙을 다음과 같이 추가해 주세요.

        ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
        <manifest
            ...
            xmlns:tools="http://schemas.android.com/tools">

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

    아래 가이드를 함께 참고해 주세요.

    * [Android 라이브러리 프로젝트 임포트](https://docs.unity3d.com/kr/current/Manual/android-library-project-import.html)
    * [Android 앱 매니페스트 오버라이드](https://docs.unity3d.com/kr/current/Manual/overriding-android-manifest.html)
  </Accordion>
</AccordionGroup>

## iOS

<AccordionGroup>
  <Accordion title="[Xcode 27] SceneDelegate 전환 필수화 및 Airbridge 딥링크 추가 설정 안내">
    <Note>
      **알립니다**

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

    ##### 문제 현상

    * Xcode 27에서 빌드한 앱을 실행하면 앱이 정상적으로 실행되지 않을 수 있습니다.
    * 스킴 딥링크(Scheme Deeplink) 또는 유니버설 링크(Universal Links)로 앱에 진입해도 Airbridge 딥링크 이벤트가 수집되지 않습니다.
    * 개발자 가이드의 [SDK 초기화하기](/ko/developers/react-native-sdk-v4)와 [앱에서 딥링크 이벤트 수집하기](/ko/developers/react-native-sdk-v4) 예제대로 `AppDelegate`에 코드를 작성했는데도 동작하지 않습니다.

    ##### 발생 원인

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

    앱이 `UIApplicationSceneManifest`를 통해 Scene 생명주기를 채택하면, 다음 `AppDelegate` 딥링크 콜백은 **더 이상 호출되지 않습니다.**

    ##### 해결 방법

    Unity Engine과 Airbridge SDK버전에 따라서 해야될 작업은 다음과 같습니다. 하단의 리스트에 참고된 Unity Engine 이상부터는 Unity가 Xcode Proejct를 생성할 때 `UnityScene`을 생성합니다.

    ###### UnityScene이 지원되는 버전 목록

    | **2022.3 LTS** | **`2022.3.72f1`** |
    | - | - |
    | **6000.0.x (LTS)** | **`6000.0.75f1`** |
    | **6000.1.x \~ 6000.3.x** | **미지원** |
    | **6000.4.x** | **`6000.4.0f1`** |
    | **6000.5.x** | **`6000.5.0f1`** |

    작성되어있는 버전 이상이여야 하며, UnityScene이 지원되지 않는 버전의 경우 별도의 UIScene 추가 필요합니다.

    ###### UnityScene이 지원되지 않는 버전

    Unity에서 UIScene을 추가 한 SceneDelegate 파일에서 `AirbridgeUnity.h` 의 public deeplink interface를 호출합니다.

    ```c# lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    #import "AirbridgeUnity.h"

    @implementation MyUnityScene

    - (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
        for (UIOpenURLContext *context in connectionOptions.URLContexts) {
            if (context.URL == nil) {
                continue;
            }

            [AirbridgeUnity.deeplink handleURLSchemeDeeplink:context.URL];
        }
        for (NSUserActivity *userActivity in connectionOptions.userActivities) {
            [AirbridgeUnity.deeplink handleUniversalLink:userActivity.webpageURL];
        }
    }

    - (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
        for (UIOpenURLContext *context in URLContexts) {
            if (context.URL == nil) {
                continue;
            }

            [AirbridgeUnity.deeplink handleURLSchemeDeeplink:context.URL];
        }
    }

    - (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity {
        [AirbridgeUnity.deeplink handleUniversalLink:userActivity.webpageURL];
    }

    @end
    ```

    ###### UnityScene을 지원하는 버전

    Unity에 의해 만들어진 Xcode Project의 UnityScene 파일에서 `AirbridgeUnity.h` 의 public deeplink interface를 호출합니다.

    ```c# lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    #import "UnityScene.h"
    #import "UnityAppController.h"
    #import "AirbridgeUnity.h"

    @implementation UnityScene

    - (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
        for (UIOpenURLContext *context in connectionOptions.URLContexts) {
            if (context.URL == nil) {
                continue;
            }

            [AirbridgeUnity.deeplink handleURLSchemeDeeplink:context.URL];
        }
        for (NSUserActivity *userActivity in connectionOptions.userActivities) {
            [AirbridgeUnity.deeplink handleUniversalLink:userActivity.webpageURL];
        }
    }

    - (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
        for (UIOpenURLContext *context in URLContexts) {
            if (context.URL == nil) {
                continue;
            }

            [AirbridgeUnity.deeplink handleURLSchemeDeeplink:context.URL];
        }
    }

    - (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity {
        [AirbridgeUnity.deeplink handleUniversalLink:userActivity.webpageURL];
    }

    @end
    ```
  </Accordion>

  <Accordion title="iOS 에서 Custom AppController 를 사용하는 경우">
    * Airbridge Unity iOS의 경우 유니티에서 제공하는 `IMPL_APP_CONTROLLER_SUBCLASS`를 이용하여 `Custom AppController`를 생성합니다. 이미 `IMPL_APP_CONTROLLER_SUBCLASS`를 사용하여 `Custom AppController`를 구현한 경우 해당 `Custom AppController`에 아래와 같은 코드를 추가해 주세요.

    ```objective-c lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    - (BOOL) application:(UIApplication*)application
    continueUserActivity:(NSUserActivity*)userActivity
      restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>>* _Nullable))restorationHandler
    {
        [AUAppDelegate.instance application:application
                       continueUserActivity:userActivity
                         restorationHandler:restorationHandler];

        return YES;
    }
    ```

    * 해당 작업 완료 후 기존의 Airbridge Unity SDK`Assets > Plugins > Airbridge > iOS > Delegate > AUAppController.mm`파일 제거해 주세요.
  </Accordion>

  <Accordion title="iOS 에서 앱 실행 시 바로 종료되는 문제">
    ```html Text lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    Error loading /var/containers/Bundle/Application/…/Frameworks/UnityFramework.framework/UnityFramework (…)
    : dlopen(/var/containers/Bundle/Application/…/Frameworks/UnityFramework.framework/UnityFramework, …)
    : Library not loaded: @rpath/AirBridge.framework/AirBridge
    ```

    Airbridge Unity SDK 1.14.1 \~ 1.16.2 이상의 버전을 사용하는 경우, 1.16.3버전으로 업데이트 해 주세요.
  </Accordion>

  <Accordion title="iOS 에서 호환되는 AirBrdige 버전을 찾지 못하는 문제">
    ```html Text lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    [!] CocoaPods could not find compatible versions for pod "AirBridge":
        In Podfile:
            AirBridge (= {MISSING_VERSION})
    ```

    iOS 에서 호환되는 [AirBridge](https://cocoapods.org/pods/AirBridge) 버전을 찾지 못하는 경우, 아래의 명령어를 실행하여 소스 레포지토리 업데이트를 진행해 주세요.

    ```bash lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    pod repo update
    pod install --repo-update
    ```

    소스 레포지토리 업데이트 후, `pod search AirBrdige` 명령어를 실행하여 올바른 AirBridge 버전이 레포지토리 내에 존재하는지 확인한 후, iOS 빌드를 진행해 주세요.
  </Accordion>
</AccordionGroup>