---
title: "Dex 보호를 위한 ProGuard 설정"
description: "DoveRunner Dex 보호 사용 시 필요한 Android ProGuard/R8 설정 가이드입니다."
---
> For the complete documentation index, see [llms.txt](/llms.txt).

import { Aside } from '@astrojs/starlight/components';

<Aside type="caution">
이 가이드는 실링 버전 **3.0.0.0 – 3.1.0.0**에 해당합니다. 3.2.0.0 이상에서는 요구사항이 변경될 수 있습니다 (`-keeppackagenames` 불필요 등). 적용 전 사용 중인 실링 버전의 릴리스 노트를 확인하세요.
</Aside>

Dex 보호를 활성화하면 DoveRunner는 APK/AAB 매니페스트에 선언된 패키지를 기준으로 비즈니스 코드를 식별합니다. ProGuard 또는 R8이 해당 클래스를 다른 패키지로 재배치한 경우, DoveRunner가 대상 패키지를 찾지 못해 난독화가 적용되지 않을 수 있습니다.

패키지 구조를 유지하면서 클래스·멤버 이름은 정상적으로 난독화하는 룰 한 줄로 해결할 수 있습니다.

## 필수 룰

`proguard-rules.pro`에 다음을 추가합니다. `com.example`은 실제 앱의 베이스 패키지 이름으로 교체하세요:

```proguard
-keeppackagenames 'com.example.**'
```

이 룰은 패키지 경로를 그대로 보존하면서, 내부 클래스·메서드·필드 이름은 정상적으로 난독화합니다.

| 원본 | 난독화 후 |
| :--- | :-------- |
| `com.example.api.UserService.fetchUser()` | `com.example.api.a.b()` |
| `com.example.model.Profile.userName` | `com.example.model.c.a` |

## 피해야 할 룰

다음 룰들은 패키지 경로 자체를 재배치하거나 평탄화하므로, DoveRunner가 의존하는 패키지 구조를 무너뜨립니다. `-keeppackagenames`와 함께 사용하지 마세요:

```proguard
-repackageclasses 'x'
-flattenpackagehierarchy 'x'
```

<Aside>
이 룰들은 R8에서 기본적으로 적용되지 않으며, `proguard-android-optimize.txt`에도 포함되어 있지 않습니다. 직접 추가하지 않았다면 기본적으로 안전합니다. 다만 외부 라이브러리의 consumer-rules에 포함되어 있을 수 있으니 확인해보는 것을 권장합니다.
</Aside>

## 라이브러리 호환성

`-keeppackagenames`는 패키지 경로만 유지하고, 클래스·멤버 이름은 여전히 난독화됩니다. 일부 라이브러리는 런타임에 리플렉션이나 직렬화를 사용하기 때문에 별도의 ProGuard 룰을 요구할 수 있습니다.

사용 중인 라이브러리에서 ProGuard 룰을 제공하는 경우, 해당 룰을 그대로 적용하면 됩니다. `-keeppackagenames`는 특정 클래스나 멤버에 대한 표준 `-keep` 룰과 충돌하지 않습니다. 단, 위에서 언급한 패키지 재배치 룰(`-repackageclasses`, `-flattenpackagehierarchy`)과는 함께 사용하지 마세요.

## 적용 검증

릴리스 빌드 후 매핑 파일을 열어 패키지 경로가 유지되고 클래스명이 난독화되었는지 확인합니다:

```
app/build/outputs/mapping/release/mapping.txt
```

다음과 같이 출력되어야 합니다:

```
com.example.api.UserService -> com.example.api.a:
    void fetchUser() -> b
com.example.model.Profile -> com.example.model.c:
    java.lang.String userName -> a
```

패키지 경로(`com.example.api`, `com.example.model`)가 그대로 유지되고, 클래스·멤버명이 짧은 기호로 치환되었으면 정상입니다.

<details>
<summary>AGP 버전별 호환성 상세</summary>

`-keeppackagenames`는 AGP 버전에 관계없이 정상 동작합니다. 주요 차이점은 R8 모드에 따른 최적화 강도입니다.

| AGP 버전 | R8 동작 | 비고 |
| :------- | :------ | :--- |
| 3.4 미만 | ProGuard 사용 | 정상 동작 |
| 3.4 – 6.x | R8 호환 모드 (기본) | 기존 룰 거의 그대로 동작 |
| 7.0 – 7.x | R8 풀 모드 (선택적) | `android.enableR8.fullMode=true`로 활성화 |
| 8.0+ | R8 풀 모드 (기본) | 클래스 머징, 인라이닝 등 공격적 최적화 적용 |
| 9.x+ | R8 풀 모드 + 추가 최적화 | 공식 릴리스 노트 참조 |

R8 풀 모드에서는 보존된 패키지 내부의 일부 클래스가 머징이나 인라이닝으로 사라질 수 있습니다. 이는 정상적인 난독화 동작이며, DoveRunner의 패키지 식별에는 영향을 주지 않습니다. 살아남은 클래스의 패키지 경로가 유지되면 충분합니다.

</details>