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

안드로이드

Android 기기에서 올바르게 Airbridge Unity가 초기화 되지 않는 경우

Airbridge Unity Android의 경우 Content Provider를 통하여 자동으로 초기화 됩니다. 올바른 초기화 작업을 위하여 Project > Plugins > Android > AndroidManifest.xml파일에 다음과 같은 Xml Tag가 반드시 올바르게 명시되어야 합니다.

<provider
    android:authorities="${applicationId}.co.ab180.airbridge.unity.AirbridgeContentProvider"
    android:name="co.ab180.airbridge.unity.AirbridgeContentProvider"
    android:exported="false" />

Android 기기에서 사용자가 이미 Custom Activity를 사용하는 경우

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

@Override
protected void onNewIntent(Intent intent) {
  super.onNewIntent(intent);
  setIntent(intent);
}

@Override
protected void onResume() {
  super.onResume();
  AirbridgeUnity.processDeeplinkData(getIntent());
}

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 해야 합니다.

Missing 'package' key attribute on element package at ...

안드로이드 11 버전의 Package Visibility 정책 추가로 해당 버전을 지원하는 모든 어플리케이션에서 다른 어플리케이션과 올바르게 상호작용하기 위해 어떤 패키지와 상호작용이 이루어 지는지에 대해서 manifest의 <queries>를 통해 유저에게 올바르게 고지하여야 합니다.Airbridge에서는 해당 정책을 준수를 위해 안드로이드 SDK 모듈이 해당 변경사항이 포함되어 있으며 <queries> 태그를 지원하기 위해서는 Gradle 최소 5.6.4 버전 이상 그리고 Android Gradle Plugin 최소 3.6.0 버전 이상을 필요로 합니다.유니티 버전에 따라 어떠한 Gradle 버전을 포함하고 있는가에 대해서는 다음 페이지를 통해 확인하실 수 있습니다.만약 사용하는 유니티의 Gradle 버전이 5.6.4 버전 미만 혹은 및 Android Gradle Plugin 버전이 3.6.0 버전 미만인 경우, 다음과 같은 유니티 설정을 통해 버전을 특정하여 사용하실 수 있습니다.

유니티 2020.1 또는 이후 버전

다음 버전들은 Gradle 5.6.4 이후 버전과 Android Gradle Plugin 3.6.0 이후 버전을 이미 포함하고 있기 때문에 추가적인 작업을 필요로 하지 않습니다.

유니티 2019.3 버전 ~ 2019.4 버전

해당 커스텀 옵션은 유니티 2019.3 patch 7 이후의 버전에서만 가능합니다.

Gradle Build Tool 페이지로 이동하여 Gradle5.6.4 이상의 버전을 다운로드해 주세요.
Preferences > External Tools로 이동하여 Gradle Installed with Unity (recommended) 체크를 해제하고 다운로드 받은 Gradle파일의 경로를 다음과 같이 설정해 주세요.

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

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

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

유니티 2019.1 버전 ~ 2019.2 버전

Gradle Build Tool 페이지로 이동하여 Gradle5.6.4 이상의 버전을 다운로드해 주세요.
Preferences > External Tools로 이동하여 Gradle Installed with Unity (recommended)체크를 해제하고 다운로드 받은 Gradle파일의 경로를 다음과 같이 설정해 주세요.

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

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

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

유니티 2018.4 버전

해당 커스텀 옵션은 유니티 2018.4 patch 24 이후의 버전에서만 가능합니다.

Gradle Build Tool 페이지로 이동하여 Gradle5.6.4 이상의 버전을 다운로드해 주세요.
Build Settings > Android로 이동하여 다음 이미지와 같이 Build System에서 Gradle을 선택해 주세요.

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

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

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

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

유니티 2018.3 이하 버전

Gradle 커스터마이즈 옵션은 2018.3 버전 이하의 유니티에서는 지원하지 않습니다.

에어브릿지 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 라이브러리 프로젝트(Assets/Plugins/Android/res.androidlib)를 생성해주세요.
생성된 Android 라이브러리 프로젝트 내부에 AndroidManifest.xml 파일을 다음과 같이 추가해 주세요.

<?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>

생성된 Android 라이브러리 프로젝트 내부에 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 설정

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

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

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

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

iOS

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

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

문제 현상

Xcode 27에서 빌드한 앱을 실행하면 앱이 정상적으로 실행되지 않을 수 있습니다.
스킴 딥링크(Scheme Deeplink) 또는 유니버설 링크(Universal Links)로 앱에 진입해도 Airbridge 딥링크 이벤트가 수집되지 않습니다.
개발자 가이드의 SDK 초기화하기와 앱에서 딥링크 이벤트 수집하기 예제대로 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를 호출합니다.

#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를 호출합니다.

#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

iOS 에서 Custom AppController 를 사용하는 경우

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

- (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 SDKAssets > Plugins > Airbridge > iOS > Delegate > AUAppController.mm파일 제거해 주세요.

iOS 에서 앱 실행 시 바로 종료되는 문제

Text

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버전으로 업데이트 해 주세요.

iOS 에서 호환되는 AirBrdige 버전을 찾지 못하는 문제

Text

[!] CocoaPods could not find compatible versions for pod "AirBridge":
    In Podfile:
        AirBridge (= {MISSING_VERSION})

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

pod repo update
pod install --repo-update

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

​안드로이드

​iOS

문제 현상

발생 원인

해결 방법

UnityScene이 지원되는 버전 목록

UnityScene이 지원되지 않는 버전

UnityScene을 지원하는 버전

안드로이드

iOS