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

<AccordionGroup>
  <Accordion title="빌드하면 Dependencies coroutines 오류가 발생합니다">
    ## 문제 현상

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

    ```html Text lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    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 라이브러리 버전이 일정 레벨 이상](https://github.com/Kotlin/kotlinx.coroutines/issues/1879)이어야 합니다.

    ## 해결 방법

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

  <Accordion title="브레이즈 SDK를 사용한 푸시 알림으로 발생한 딥링크 이벤트가 수집되지 않습니다">
    ## 문제 현상

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

    ## 발생 원인

    에어브릿지 안드로이드 SDK는 activity의 action에 있는 dataString과 intent의 dataString으로 딥링크 실행 이벤트와 실행 이벤트를 판별합니다.

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

    ## 해결 방법

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

    <CodeGroup>
      ```kotlin Kotlin lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
      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)
      ```

      ```java Java lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
      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);
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="빌드하면 Manifest merger failed 오류가 발생합니다">
    ## 문제 현상

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

    ## 발생 원인

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

    에어브릿지 SDK 백업 규칙과 앱 백업 규칙의 병합 과정에서 충돌이 발생할 수 있습니다.

    ## 해결 방법

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

    <CodeGroup>
      ```xml Backup on Android 12 or later lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
      <?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 Backup on Android 11 and earlier lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
      <?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>
      ```
    </CodeGroup>

    ##### fullBackupContent="string"과의 충돌 방지

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

    ```html Build Output lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    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`에 추가하면 다음과 같은 오류가 발생할 수 있습니다.

    ```html Build Output lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    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`에 추가하면 다음과 같은 오류가 발생할 수 있습니다.

    ```html Build Output lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    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 미만일 경우, 다음과 같은 오류가 발생할 수 있습니다.

    ```html Build Output lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    AndroidManifest.xml: AAPT: error: attribute android:dataExtractionRules not found.
    ```

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

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

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

    * [안드로이드 가이드](https://developer.android.com/guide/topics/data/autobackup)
    * [에어브릿지 가이드](https://airbridge.readme.io/page/auto-backup-%EC%A4%91%EB%B3%B5-%EB%AC%B8%EC%A0%9C-%ED%95%B4%EA%B2%B0-%EA%B0%80%EC%9D%B4%EB%93%9C)
  </Accordion>

  <Accordion title="에어브릿지 SDK 백업 규칙 설정 (SDK 4.9.0 미만)">
    <Info>
      **알립니다**

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

    ## **설정이 필요한 이유**

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

    ## 설정방법

    **android:allowBackup="..." 포함 시**

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

    **android:dataExtractionRules="..." 포함 시**

    1. `AndroidManifest.xml` 에서 `<application>` 태그의 `tools:replace` 속성에 `android:dataExtractionRules`를 추가하세요. 다른 값이 있다면 쉼표(`,`)로 구분할 수 있습니다. 다른 값이 없다면 쉼표는 사용하지 않습니다.
       ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
       <application
           android:dataExtractionRules="..."
           tools:replace="...,android:dataExtractionRules"
           ...>
       ```
    2. `android:dataExtractionRules="...”` 에 백업 규칙 파일을 지정하세요. 백업 규칙 파일(예: `res/xml/data_extraction_rules.xml`)에 에어브릿지 제외 규칙을 추가하세요.
       ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
       <?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="..." 포함 시**

    1. `AndroidManifest.xml` 에서 `<application>` 태그의 `tools:replace` 속성에 `android:fullBackupContent`를 추가하세요. 다른 값이 있다면 쉼표(`,`)로 구분할 수 있습니다. 다른 값이 없다면 쉼표는 사용하지 않습니다.
       ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
       <application
           android:fullBackupContent="..."
           tools:replace="...,android:fullBackupContent"
           ...>
       ```
    2. `android:fullBackupContent="...”` 에 백업 규칙 파일을 지정하세요. 백업 규칙 파일(예: `res/xml/backup_rules.xml`)에 에어브릿지 제외 규칙을 추가하세요. `android:fullBackupContent="false"` 는 백업 규칙 파일이 없다는 뜻으로 아래 규칙을 추가하지 않아도 됩니다.
       ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
       <?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) 버전에서 빌드 오류가 발생할 수 있습니다. 참고하세요.
  </Accordion>

  <Accordion title="에어브릿지 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.
    ```

    ## 발생 원인

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

    ## 해결 방법

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

    1. `res/xml` 폴더 아래 아래에 백업 규칙 파일을 생성합니다. 만약 기존 파일이 있다면 에어브릿지 내용만 추가 합니다.
       1. Android 11 이하: `backup_rules.xml`
          ```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>
          ```
       2. Android 12 이상: `data_extraction_rules.xml`
          ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
          <?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>
          ```
    2. `AndroidManifest.xml` 에서 `application` 태그에 `tools:replace`를 포함한 아래 내용을 추가합니다. 다른 값이 있다면 쉼표(`,`)로 구분할 수 있습니다. 다른 값이 없다면 쉼표는 사용하지 않습니다.
       ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
       <application
           android:fullBackupContent="@xml/custom_backup_rules"
           android:dataExtractionRules="@xml/custom_data_extraction_rules"
           tools:replace="android:fullBackupContent,android:dataExtractionRules">
       ```

    ## 주의사항

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

  <Accordion title="GAID가 00000000-0000-0000-0000-000000000000으로 수집됩니다">
    ## 발생 현상

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

    ## 발생 원인

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

    ## **해결 방법**

    AD\_ID 권한을 추가합니다.

    ```xml lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    <manifest ...>
      ...
      <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
      ...
    </manifest>
    ```
  </Accordion>

  <Accordion title="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 버전 유지 + 설정 추가
      ```groovy lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
      android {
          ...
          packagingOptions {
              jniLibs {
                  useLegacyPackaging true
              }
          }
      }
      ```

    **Step 3: 앱 다시 빌드 및 확인**

    설정을 변경한 후 앱을 클린 빌드하세요.

    **Step 4: 16KB zipalign 적용 확인**

    빌드된 APK/AAB가 올바르게 16KB zipalign되었는지 확인하세요.
  </Accordion>

  <Accordion title="android:allowBackup=&#x22;false&#x22; 설정 시 오류가 발생합니다.">
    ## 문제 현상

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

    ```html lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    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)를 수행하시기 바랍니다.
  </Accordion>
</AccordionGroup>

<link rel="alternate" hrefLang="en" href="https://help.airbridge.io/en/developers/troubleshooting-android-sdk-v4" />

<link rel="alternate" hrefLang="ko" href="https://help.airbridge.io/ko/developers/troubleshooting-android-sdk-v4" />