AndResGuard Documentation

repository·master·Indexed 27 days ago

https://github.com/shwenzhang/andresguard

AndResGuard is a tool for reducing Android APK size and obfuscating Android resources, such as drawables, layouts, and strings. It provides a Gradle plugin for integration into Android projects, a command-line interface (CLI) for resource obfuscation, and an integrated apksigner tool for signing and verifying APKs. Key features include resource renaming, 7zip compression for higher APK density, and white-listing to exclude specific resources from obfuscation.

Tokens: 7.2K
Snippets: 10
Records: 32
Agent score: 93%

What's inside AndResGuard

Install and configure AndResGuard via Gradle

master

AndResGuard is a tool to reduce APK size by obfuscating resource paths (e.g., converting res/drawable/wechat to r/d/a). It works similarly to Proguard but specifically for resources. It does not involve the compilation process; it takes an APK as input and produces an obfuscated APK and a resource ID mapping file.

To use it in your Android project, apply the plugin and configure the andResGuard block in your build.gradle file.

apply plugin: 'AndResGuard'

buildscript {
    repositories {
        jcenter()
        google()
    }
    dependencies {
        classpath 'com.tencent.mm:AndResGuard-gradle-plugin:1.2.21'
    }
}

andResGuard {
    mappingFile = null
    use7zip = true
    useSign = true
    keepRoot = false
    fixedResName = "arg"
    mergeDuplicatedRes = true
    whiteList = [
        "R.drawable.icon",
        "R.string.com.crashlytics.*",
        "R.string.google_app_id"
    ]
    compressFilePattern = [
        "*.png",
        "*.jpg",
        "*.jpeg",
        "*.gif"
    ]
    sevenzip {
         artifact = 'com.tencent.mm:SevenZip:1.2.21'
    }
}

Integrate AndResGuard with Gradle
master
To use AndResGuard in your Android project, apply the AndResGuard plugin and add the AndResGuard-gradle-plugin to your buildscript dependencies. You can then configure the andResGuard block to control obfuscation, white-listing, and compression settings.
```
apply plugin: 'AndResGuard'

buildscript {
    repositories {
        jcenter()
        google()
    }
    dependencies {
        classpath 'com.tencent.mm:AndResGuard-gradle-plugin:1.2.21'
    }
}

andResGuard {
    // configuration goes here
}
```
https://github.com/shwenzhang/andresguard/blob/master/README.md
Verify APK signatures with apksigner
master
Use the apksigner verify command to check if a provided APK will verify on Android. By default, it verifies against all Android platform versions supported by the APK as declared in its AndroidManifest.xml via minSdkVersion.
```
$ apksigner verify app.apk
```
https://github.com/shwenzhang/andresguard/blob/master/AndResGuard-core/src/main/java/apksigner/help_verify.txt
Use the apksigner CLI to sign or verify APKs
master
The apksigner tool is used to sign Android APK files and verify if their signatures are compatible with Android devices.
Available commands:
- sign: Signs a provided APK.
- verify: Checks if the provided APK is expected to verify on Android.
- version: Displays the tool's version.
- help: Displays the usage information.
https://github.com/shwenzhang/andresguard/blob/master/AndResGuard-core/src/main/java/apksigner/help.txt

Configure WhiteList for Third-Party SDKs

master

When using AndResGuard, certain third-party SDKs require specific Android resources to remain un-obfuscated to function correctly. You should add these resource patterns to your WhiteList configuration. Below are common resource patterns for popular SDKs.

### Umeng sdk
"R.anim.umeng*",
"R.string.umeng*",
"R.string.UM*",
"R.string.tb_*",
"R.layout.umeng*",
"R.layout.socialize_*",
"R.layout.*messager*",
"R.layout.tb_*",
"R.color.umeng*",
"R.color.tb_*",
"R.style.*UM*",
"R.style.umeng*",
"R.drawable.umeng*",
"R.drawable.tb_*",
"R.drawable.sina*",
"R.drawable.qq_*",
"R.drawable.tb_*",
"R.id.umeng*",
"R.id.*messager*",
"R.id.progress_bar_parent",
"R.id.socialize_*",
"R.id.webView"

### google-services
"R.string.google_app_id",
"R.string.gcm_defaultSenderId",
"R.string.default_web_client_id",
"R.string.ga_trackingId",
"R.string.firebase_database_url",
"R.string.google_api_key",
"R.string.google_crash_reporting_api_key"

### getui(个推)
"R.drawable.push",
"R.drawable.push_small",
"R.layout.getui_notification"

### JPush(极光推送)
"R.drawable.jpush_notification_icon"

### GrowingIO
"R.string.growingio_project_id",
"R.string.growingio_url_scheme",
"R.string.growingio_channel"

### Firebase (firStore)
"R.string.project_id"

### Huawei push
"R.string.hms_*",
"R.string.connect_server_fail_prompt_toast",
"R.string.getting_message_fail_prompt_toast",
"R.string.no_available_network_prompt_toast",
"R.string.third_app_*",
"R.string.upsdk_*",
"R.style.upsdkDlDialog",
"R.style.AppTheme",
"R.style.AppBaseTheme",
"R.dimen.upsdk_dialog_*",
"R.color.upsdk_*",
"R.layout.upsdk_*",
"R.drawable.upsdk_*",
"R.drawable.hms_*",
"R.layout.hms_*",
"R.id.hms_*"

### Firebase Crashlytics
"R.bool.com.crashlytics.useFirebaseAppId",
"R.string.com.crashlytics.useFirebaseAppId",
"R.string.google_app_id",
"R.bool.com.crashlytics.CollectDeviceIdentifiers",
"R.string.com.crashlytics.CollectDeviceIdentifiers",
"R.bool.com.crashlytics.CollectUserIdentifiers",
"R.string.com.crashlytics.CollectUserIdentifiers",
"R.bool.com.crashlytics.ApiEndpoint",
"R.string.io.fabric.android.build_id",
"R.string.com.crashlytics.android.build_id",
"R.bool.com.crashlytics.RequireBuildId",
"R.string.com.crashlytics.RequireBuildId",
"R.bool.com.crashlytics.CollectCustomLogs",
"R.string.com.crashlytics.CollectCustomLogs",
"R.bool.com.crashlytics.Trace",
"R.string.com.crashlytics.Trace",
"R.string.com.crashlytics.CollectCustomKeys"

### shareSDK
"R.id.ssdk*",
"R.string.mobcommon*",
"R.string.ssdk*",
"R.string.mobdemo*",
"R.drawable.mobcommon*",
"R.drawable.ssdk*",
"R.layout.mob*",
"R.style.mobcommon*"

### 穿山甲广告SDK
"R.string.tt_*",
"R.integer.tt_*",
"R.layout.tt_*",
"R.drawable.tt_*",
"R.style.tt_*",
"R.dimen.tt_*",
"R.anim.tt_*",
"R.color.tt_*",
"R.id.tt_*"

Verify APK against a custom SDK version range
master
You can use --min-sdk-version and --max-sdk-version to verify the APK against a specific range of API Levels instead of using the values from the AndroidManifest.xml.
```
$ apksigner verify --min-sdk-version 15 app.apk
```
https://github.com/shwenzhang/andresguard/blob/master/AndResGuard-core/src/main/java/apksigner/help_verify.txt
Best practices for AndResGuard
master
To avoid common issues and performance degradation, follow these best practices:
1. Avoid compressing resources.arsc: Unless you have extreme APK size requirements, do not add resources.arsc to your compressFilePattern.
2. Google Play Compatibility: If publishing to Google Play, it is recommended not to use 7Zip compression, as it can interfere with Google Play's optimization Patch algorithm.
3. WhiteList for SDKs: Always add resources used by third-party SDKs (like Umeng or Firebase) to the whiteList to prevent crashes.
https://github.com/shwenzhang/andresguard/blob/master/README.zh-cn.md
Protect resources accessed via getIdentifier using mappingFile
master
The whiteList only protects the resource name, not the path. If you need to preserve the full resource path (e.g., for resources accessed via getIdentifier), you must use a mappingFile.
Example mappingFile content:
```
res path mapping:
    res/mipmap-hdpi-v4 -> res/mipmap-hdpi-v4
    res/mipmap-mdpi-v4 -> res/mipmap-mdpi-v4
```
https://github.com/shwenzhang/andresguard/blob/master/README.md
Run AndResGuard tasks
master
You can trigger the resource obfuscation process in two ways:
1. Android Studio: Look for the generate task under the andresguard group in the Gradle tool window.
2. Terminal: Run the Gradle task using the format ./gradlew resguard[BuildType | Flavor]. For example, if you have a build type named release, run ./gradlew resguardRelease.
https://github.com/shwenzhang/andresguard/blob/master/README.md
Use AndResGuard via Command Line
master
Run the AndResGuard JAR file to obfuscate Android resources. By default, it looks for a config.xml in the current directory and outputs the result to a folder named after the input APK.
Basic Usage: java -jar andresguard.jar input.apk
Common CLI Flags:
- -config <path>: Specify a custom configuration XML file.
- -out <path>: Specify the output directory. A mapping file named resource_mapping_<input_apk_name>.txt will be created here.
- -signature <file_path> <storepass> <keypass> <storealias>: Provide signing information (overrides config.xml).
- -mapping <path>: Specify an old mapping file to ensure consistent resource names across versions (overrides config.xml).
- -7zip <path>: Path to the 7zip executable (required if using 7z compression; must be absolute path, e.g., /path/to/7za on Linux or C:\path\7za.exe on Windows).
- -zipalign <path>: Path to the zipalign executable.
- -repackage: Enables 7zip repackaging mode (useful for creating channel builds). Note: In this mode, other parameters are not supported.
https://github.com/shwenzhang/andresguard/blob/master/doc/how_to_work.zh-cn.md
Run AndResGuard via Command Line
master
To obfuscate an APK, use the java -jar command. The simplest usage is providing only the input APK; the tool will automatically look for a config.xml in the current directory and output results to a folder named after the input APK.
Basic Usage
```
java -jar andresguard.jar input.apk
```
Common CLI Flags
- -config <path>: Set a custom configuration file path. Defaults to config.xml in the running location.
- -out <path>: Set a custom output directory.
- -signature <file_path> <storepass> <keypass> <storealias>: Overlays signature data from the config file with these parameters.
- -mapping <file_path>: Overlays mapping data from the config file with this file path.
- -7zip <path>: Set the path to the 7zip executable (e.g., /path/to/7za or C:\path\7za.exe).
- -zipalign <path>: Set the path to the zipalign tool.
- -repackage: Used when building channel APKs that might have broken 7zip compression. It repackages the APK using 7zip.
Advanced Examples
Custom config and output directory:
```
java -jar andresguard.jar input.apk -config yourconfig.xml -out output_directory
```
Custom signature and mapping data:
```
java -jar andresguard.jar input.apk -config yourconfig.xml -out output_directory -signature signature_file_path storepass_value keypass_value storealias_value -mapping mapping_file_path
```
Specifying 7zip and zipalign paths:
```
java -jar andresguard.jar input.apk -7zip /shwenzhang/tool/7za -zipalign /shwenzhang/sdk/tools/zipalign
```
Repackaging an APK with 7zip:
```
java -jar andresguard.jar -repackage input.apk -out output_directory -7zip /shwenzhang/tool/7za -zipalign /shwenzhang/sdk/tools/zipalign
```
```
java -jar andresguard.jar input.apk
```
https://github.com/shwenzhang/andresguard/blob/master/doc/how_to_work.md
Sign an APK using apksigner
master
Use the apksigner sign command to sign an APK. This process strips any pre-existing signatures and applies new ones using one or more signers. You can provide signers via a Java KeyStore or via individual PKCS #8 private key and X.509 certificate files.
https://github.com/shwenzhang/andresguard/blob/master/AndResGuard-core/src/main/java/apksigner/help_sign.txt

AndResGuard Documentation

What's inside AndResGuard

Basic Usage

Common CLI Flags

Advanced Examples