트러블 슈팅 - 안드로이드 SDK

빌드하면 Dependencies coroutines 오류가 발생합니다

문제 현상

빌드하면 아래 메시지와 함께 Dependencies coroutines 오류가 발생합니다.

Text

java.lang.NoClassDefFoundError: kotlin/coroutines/AbstractCoroutineContextKey
    at java.base/java.lang.ClassLoader.defineClass1(Native Method)
    at java.base/java.lang.ClassLoader.defineClass(ClassLoader.java:1016)
  ...

발생 원인

kotlinx-coroutines-core 라이브러리 버전이 v1.3.5 이상이면 kotlin-stdlib 라이브러리 버전이 일정 레벨 이상이어야 합니다.

해결 방법

gradlew dependencies 커멘드로 kotlin-stdlib 라이브러리 버전이 v1.3.70 이상인지 확인해 주세요. 해당 버전 미만이라면 업데이트를 진행해야 합니다.

브레이즈 SDK를 사용한 푸시 알림으로 발생한 딥링크 이벤트가 수집되지 않습니다

문제 현상

브레이즈 SDK를 사용한 푸시 알림으로 발생한 딥링크 실행(Deeplink Open) 이벤트가 수집되지 않습니다. 대신 실행(Open) 이벤트가 수집됩니다.

발생 원인

에어브릿지 안드로이드 SDK는 activity의 action에 있는 dataString과 intent의 dataString으로 딥링크 실행 이벤트와 실행 이벤트를 판별합니다.브레이즈 SDK를 사용한 푸시 알림으로 앱을 실행하면 NotificationTrampolineActivity을 사용합니다. 브레이즈 SDK를 사용한 푸시 알림으로 앱을 실행하면 NotificationTrampolineActivity의 activity의 action과 intent로부터 dataString을 확인할 수 없습니다. 이로 인해 딥링크 실행 이벤트와 실행 이벤트를 판별할 수 없습니다.

해결 방법

에어브릿지 안드로이드 SDK v2.21.5 이상에서 아래 코드로 해결할 수 있습니다.

val option = AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
  .setLifecycleIntegration {
    it.takeIf { it.javaClass.name == "com.braze.push.NotificationTrampolineActivity" }
    ?.run { intent?.extras?.getString("uri") }
  }
  .build()
Airbridge.initializeSDK(application, option)

AirbridgeOption option = new AirbridgeOptionBuilder("YOUR_APP_NAME", "YOUR_APP_SDK_TOKEN")
  .setLifecycleIntegration(new AirbridgeLifecycleIntegration() {
      @Nullable
      @Override
      public String getDataString(@NonNull Activity activity) {
          if (activity.getClass().getName().equals("com.braze.push.NotificationTrampolineActivity")
                  && activity.getIntent() != null
                  && activity.getIntent().getExtras() != null) {
              return activity.getIntent().getExtras().getString("uri");
          }
          return null;
      }
    })
  })
  .build();
Airbridge.initializeSDK(application, option);

빌드하면 Manifest merger failed 오류가 발생합니다

문제 현상

빌드하면 Manifest merger failed 오류가 발생합니다.

발생 원인

에어브릿지 SDK의 AndroidManifest.xml에는 공유 환경 설정 데이터 백업을 옵트아웃하는 규칙이 포함되어 있습니다. 이는 재설치 중에 동일한 에어브릿지 설정 값들을 유지하지 않도록 하여 새로운 설치 또는 재설치를 정확하게 감지하도록 하기 위해 수행됩니다.에어브릿지 SDK 백업 규칙과 앱 백업 규칙의 병합 과정에서 충돌이 발생할 수 있습니다.

해결 방법

에어브릿지 SDK에서 정의하는 옵트아웃하는 규칙은 다음과 같습니다.

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        <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" />
    </cloud-backup>
    <device-transfer>
        <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" />
    </device-transfer>
</data-extraction-rules>

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <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" />
</full-backup-content>

fullBackupContent=“string”과의 충돌 방지

android:fullBackupContent="string"를 AndroidManifest.xml에 추가하면 다음과 같은 오류가 발생할 수 있습니다.

Build Output

Manifest merger failed : Attribute application@fullBackupContent value=(string) from AndroidManifest.xml

위 오류를 해결하려면 AndroidManifest.xml 파일의

<manifest> 태그에 xmlns:tools="http://schemas.android.com/tools"를 추가 해주세요.
<application> 태그에 tools:replace="android:fullBackupContent"를 추가 해주세요.

dataExtractionRules=“string resource”과의 충돌 방지

android:dataExtractionRules="string resource"를 AndroidManifest.xml에 추가하면 다음과 같은 오류가 발생할 수 있습니다.

Build Output

Manifest merger failed : Attribute application@dataExtractionRules value=(string resource) from AndroidManifest.xml

위 오류를 해결하려면 AndroidManifest.xml 파일의

<manifest> 태그에 xmlns:tools="http://schemas.android.com/tools"를 추가 해주세요.
<application> 태그에 tools:replace="android:dataExtractionRules"를 추가 해주세요.

allowBackup=“false”과의 충돌 방지

android:allowBackup="false"를 AndroidManifest.xml에 추가하면 다음과 같은 오류가 발생할 수 있습니다.

Build Output

Manifest merger failed : Attribute application@allowBackup value=(false) from AndroidManifest.xml:32:9-36
	is also present at [:airbridge] AndroidManifest.xml:27:9-35 value=(true).
	Suggestion: add 'tools:replace="android:allowBackup"' to <application> element at AndroidManifest.xml:30:5-250:19 to override.

위 오류를 해결하려면 AndroidManifest.xml 파일의

<manifest> 태그에 xmlns:tools="http://schemas.android.com/tools"를 추가 해주세요.
<application> 태그에 tools:replace="android:allowBackup"를 추가 해주세요.

compileSdkVersion이 31 미만일 경우

android:dataExtractionRules 기능이 API Level 31 부터 추가되었기 때문에 compileSdkVersion이 31 미만일 경우, 다음과 같은 오류가 발생할 수 있습니다.

Build Output

AndroidManifest.xml: AAPT: error: attribute android:dataExtractionRules not found.

위 오류를 해결하려면 AndroidManifest.xml 파일의

<manifest> 태그에 xmlns:tools="http://schemas.android.com/tools"를 추가 해주세요.
<application> 태그에 tools:remove="android:dataExtractionRules"를 추가 해주세요.

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

에어브릿지 SDK 백업 규칙 설정 (SDK 4.9.0 미만)

알립니다에어브릿지 안드로이드 SDK 4.9.0 부터는 백업 규칙 설정이 필요하지 않습니다. 4.9.0 미만 버전을 사용 중인 경우에만 이 단계를 진행하세요.

설정이 필요한 이유

에어브릿지 안드로이드 SDK는 재설치 감지의 정확성을 위해 특정 데이터를 백업 대상에서 제외해야 합니다. SDK 4.9.0 미만 버전에서는 이를 수동으로 설정해야 합니다.

설정방법

android:allowBackup=”…” 포함 시

AndroidManifest.xml 에서 <application> 태그의 tools:replace 속성에 android:allowBackup을 추가하세요. 다른 값이 있다면 쉼표(,)로 구분할 수 있습니다. 다른 값이 없다면 쉼표는 사용하지 않습니다.
<application android:allowBackup="..." tools:replace="...,android:allowBackup" ...>

android:dataExtractionRules=”…” 포함 시

AndroidManifest.xml 에서 <application> 태그의 tools:replace 속성에 android:dataExtractionRules를 추가하세요. 다른 값이 있다면 쉼표(,)로 구분할 수 있습니다. 다른 값이 없다면 쉼표는 사용하지 않습니다.
<application android:dataExtractionRules="..." tools:replace="...,android:dataExtractionRules" ...>

android:dataExtractionRules="...” 에 백업 규칙 파일을 지정하세요. 백업 규칙 파일(예: res/xml/data_extraction_rules.xml)에 에어브릿지 제외 규칙을 추가하세요.

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        <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" />
    </cloud-backup>
    <device-transfer>
        <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" />
    </device-transfer>
</data-extraction-rules>

android:fullBackupContent=”…” 포함 시

AndroidManifest.xml 에서 <application> 태그의 tools:replace 속성에 android:fullBackupContent를 추가하세요. 다른 값이 있다면 쉼표(,)로 구분할 수 있습니다. 다른 값이 없다면 쉼표는 사용하지 않습니다.
<application android:fullBackupContent="..." tools:replace="...,android:fullBackupContent" ...>

android:fullBackupContent="...” 에 백업 규칙 파일을 지정하세요. 백업 규칙 파일(예: res/xml/backup_rules.xml)에 에어브릿지 제외 규칙을 추가하세요. android:fullBackupContent="false" 는 백업 규칙 파일이 없다는 뜻으로 아래 규칙을 추가하지 않아도 됩니다.

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <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" />
</full-backup-content>

주의사항

<application> 태그의 tools:replace 속성에 값을 추가 할때, 쉼표(,) 뒤에 공백이 있다면 일부 Android Gradle Plugin(AGP) 버전에서 빌드 오류가 발생할 수 있습니다. 참고하세요.

에어브릿지 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.

발생 원인

에어브릿지 SDK 백업 규칙과 서드파티 SDK 백업 규칙 중복 적용으로 인해 빌드 에러가 발생할 수 있습니다.

해결 방법

다음 단계를 따라 모든 SDK의 백업 규칙을 하나의 파일로 통합하세요.

res/xml 폴더 아래 아래에 백업 규칙 파일을 생성합니다. 만약 기존 파일이 있다면 에어브릿지 내용만 추가 합니다.

Android 11 이하: backup_rules.xml

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

Android 12 이상: data_extraction_rules.xml

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        <!-- 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 -->
    </cloud-backup>
    <device-transfer>
        <!-- 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 -->
    </device-transfer>
</data-extraction-rules>

AndroidManifest.xml 에서 application 태그에 tools:replace를 포함한 아래 내용을 추가합니다. 다른 값이 있다면 쉼표(,)로 구분할 수 있습니다. 다른 값이 없다면 쉼표는 사용하지 않습니다.
<application android:fullBackupContent="@xml/custom_backup_rules" android:dataExtractionRules="@xml/custom_data_extraction_rules" tools:replace="android:fullBackupContent,android:dataExtractionRules">

주의사항

GAID가 00000000-0000-0000-0000-000000000000으로 수집됩니다

발생 현상

LAT(LimitAdTracking)를 비활성화한 상태에서 정상적으로 수집되어야 하는 GAID가 00000000-0000-0000-0000-000000000000으로 수집됩니다.

발생 원인

다른 서드파티 라이브러리 등으로 인해 AD_ID 권한이 제외되었습니다.

해결 방법

AD_ID 권한을 추가합니다.

<manifest ...>
  ...
  <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
  ...
</manifest>

Google Play 업로드 시 16KB 페이지 크기 관련 경고 또는 거부가 발생합니다

문제 현상

Google Play Console에 앱을 업로드할 때 다음과 같은 경고 또는 거부 메시지를 받을 수 있습니다:

“Your app doesn’t support 16 KB page size”
“16 KB page size compatibility required”
앱 업로드가 거부되거나 경고 상태로 표시됩니다

이는 Android 15(API 수준 35) 이상을 타겟팅하는 앱이 16KB 페이지 크기를 지원해야 한다는 Google Play 정책 요구사항 때문입니다.

발생 원인

16KB 페이지 크기 지원을 위해서는 앱 전체(APK/AAB)가 16KB zipalign으로 패키징되어야 Google Play 정책을 통과합니다.APK/AAB가 16KB zipalign으로 빌드되지 않으면:

Google Play Console 업로드 시 경고 또는 거부 메시지를 받습니다
2025년 11월 1일 이후에는 업로드가 완전히 차단됩니다
16KB 페이지 크기 기기에서 향후 정상 작동하지 않을 수 있습니다

Airbridge SDK 알려진 이슈: PT_GNU_RELRO 정렬Airbridge SDK는 v4.6부터 16KB 페이지 크기를 지원하고 있습니다. 다만 SDK 빌드에 NDK r21을 사용한 버전에서는 네이티브 라이브러리(.so)의 LOAD 세그먼트는 16KB 경계로 정렬되지만 PT_GNU_RELRO 세그먼트는 정렬되지 않습니다.

앱 동작에는 영향이 없습니다. 16KB 페이지 크기 기기에서도 정상적으로 동작합니다.
다만 Google Play Console 업로드 시 16KB 페이지 크기 관련 경고 메시지가 표시될 수 있습니다.
Android Studio의 lint, APK Analyzer, check_elf_alignment.sh 등 정렬 검사 도구에서도 경고로 표시될 수 있습니다.

해당 이슈는 SDK 빌드 툴체인을 NDK r27로 업그레이드하여 수정했으며, 수정 이후 16KB 페이지 크기 지원에 이상이 없음을 확인했습니다. 플랫폼별 16KB 페이지 크기 지원 버전과 권장 버전은 아래 표를 참고해 주세요.

Platform	16KB 지원 시작 버전	권장 버전 (PT_GNU_RELRO 이슈 수정)
Android	v4.6	v4.9.4
React Native	v4.6	v4.9.0
Cordova Ionic	v4.4.1	x(지원 예정)
Flutter	v4.6	v4.9.0
Expo	v4.6	v4.9.0
Unity	v4.6	v4.9.2
Unreal	v4.6	v4.9.0

해결 방법

Step 1: Airbridge SDK 버전 확인사용 중인 Airbridge SDK 버전을 위 표와 비교해 확인해 주세요.

16KB 지원 시작 버전보다 낮은 버전을 사용 중인 경우: 16KB 페이지 크기를 지원하지 않습니다. 반드시 업데이트해 주세요.
16KB 지원 시작 버전 이상, 권장 버전 미만을 사용 중인 경우: 위에 안내한 PT_GNU_RELRO 정렬 이슈로 인해 Google Play Console 경고가 계속 표시될 수 있습니다. 앱 동작에는 영향이 없지만, 경고를 해소하려면 권장 버전 이상으로 업데이트해 주세요.

Step 2: Android Gradle Plugin(AGP) 버전 확인 및 설정현재 프로젝트의 AGP 버전을 확인하세요.AGP 8.5.1 이상을 사용하는 경우:

별도의 추가 설정 없이 자동으로 16KB zipalign이 적용됩니다.
Step 3으로 바로 이동하세요.

AGP 8.5.0 이하를 사용하는 경우:

옵션 A: AGP를 8.5.1 이상으로 업그레이드

옵션 B: 현재 AGP 버전 유지 + 설정 추가

android {
    ...
    packagingOptions {
        jniLibs {
            useLegacyPackaging true
        }
    }
}

Step 3: 앱 다시 빌드 및 확인설정을 변경한 후 앱을 클린 빌드하세요.Step 4: 16KB zipalign 적용 확인빌드된 APK/AAB가 올바르게 16KB zipalign되었는지 확인하세요.

android:allowBackup="false" 설정 시 오류가 발생합니다.

문제 현상

android:allowBackup="false" 설정 시 아래와 같은 빌드 에러가 표시됩니다.

Multiple entries with same key: android:allowBackup=REPLACE and android:allowBackup=REPLACE

발생 원인

이 문제는 Android Gradle Plugin(AGP)의 버전에 따른 Manifest Merger의 파싱 동작 방식 차이로 인해 발생할 수 있습니다.일부 AGP 버전에서는 AndroidManifest.xml의 tools:replace="..." 속성을 해석할 때, 쉼표(,) 뒤의 공백(Whitespace)을 자동으로 제거하지 못합니다. 이 경우 공백이 포함된 문자열을 별도의 잘못된 속성 키로 인식하게 되어, 결과적으로 속성 교체 규칙이 적용되지 않거나 중복 선언으로 인한 빌드 오류가 발생할 수 있습니다.

해결 방법

이 문제를 해결하기 위해서는 tools:replace 속성 값 내 모든 공백을 제거한 후 클린 빌드(Clean Build)를 수행하시기 바랍니다.

​문제 현상

​발생 원인

​해결 방법

​문제 현상

​발생 원인

​해결 방법

​문제 현상

​발생 원인

​해결 방법

fullBackupContent=“string”과의 충돌 방지

dataExtractionRules=“string resource”과의 충돌 방지

allowBackup=“false”과의 충돌 방지

compileSdkVersion이 31 미만일 경우

​설정이 필요한 이유

​설정방법

​주의사항

​문제 현상

​발생 원인

​해결 방법

​주의사항

​발생 현상

​발생 원인

​해결 방법

​문제 현상

​발생 원인

​해결 방법

​문제 현상

​발생 원인

​해결 방법

문제 현상

발생 원인

해결 방법

문제 현상

발생 원인

해결 방법

문제 현상

발생 원인

해결 방법

설정이 필요한 이유

설정방법

주의사항

문제 현상

발생 원인

해결 방법

주의사항

발생 현상

발생 원인

해결 방법

문제 현상

발생 원인

해결 방법

문제 현상

발생 원인

해결 방법