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

**ProGuard/R8을 먼저 적용하세요:** 
이 가이드는 실링 버전 3.x에 해당합니다. 개발자 콘솔의 **기본 설정** 단계에서도 Dex 보호 옵션 바로 아래에 동일한 요구사항이 표시됩니다:

> **필수 조치: ProGuard/R8 기본 난독화 적용 후 Dex Protection 적용**
>
> 고급 커스텀 난독화 기법인 Dex Protection을 적용하기 전에, 반드시 ProGuard/R8을 통한 표준 기본 난독화가 일관되게 올바르게 적용되도록 해야 합니다. 기본 난독화(ProGuard/R8)와 고급 난독화(Dex Protection)를 계층적으로 결합하는 것이 가장 강력한 보안 방어 체계를 구축합니다.


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

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


## 라이브러리 호환성

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