DexGuard Quick Start

Quick Start

DexGuard is a specialized optimizer and obfuscator for Android applications. It is easy to integrate in your Android build process. Once installed, it works transparently, producing code that is optimized and more difficult to crack.

Setting Up the Ant Build

If you develop your applications with the Ant build process of the Android SDK Tools (revision 21.0.0 or higher), you can enable DexGuard as follows:

Copy the two configuration files from DexGuard's ant directory to the main directory of your Android project:
```
dexguard-project.txt
custom_rules.xml
```
Specify the main DexGuard directory on your system in the configuration file local.properties in your Android project. For instance:
```
dexguard.dir=/usr/local/DexGuard5.0
```

The standard Ant build process will now automatically use DexGuard for your Android project.

Setting Up the Eclipse Plugin

If you develop your applications in Eclipse (version 3.7 or higher) with the plugin of the Android Developer Tools (version 23.0.1.1256982 or higher), you can enable DexGuard as follows:

Optionally copy the configuration file from DexGuard's ant directory to the main directory of your Android project:
```
dexguard-project.txt
```
Copy the plugin from DexGuard's eclipse directory to the dropins directory of your Eclipse install:
```
com.saikoa.dexguard.eclipse.adt_*.jar
```

You're set! The standard Eclipse build process will automatically use DexGuard for all Android builds.

Getting the Most Out of DexGuard

DexGuard has been configured to work out of the box for most projects. It transparently combines the functionality of ProGuard, dx, apkbuilder, signjar, and zipalign in a single, seamless process. Instead of creating a whole series of intermediary and final .apk files in the bin directory, it just produces the final .apk file.

When building in debug mode, DexGuard only converts and packages your code. When building in release mode, it additionally optimizes and obfuscates the code.

Once your basic setup works, you should have a look at DexGuard's specialized optimizations and advanced obfuscation. For optimally protecting your application, consider the following options:

-encryptstrings: Encrypt sensitive strings in your code.
-encryptclasses: Encrypt entire classes.
-encryptassetfiles: Encrypt streamed asset files.
-encryptnativelibraries: Encrypt native libraries.
-accessthroughreflection: Hide access to sensitive APIs through reflection.
samples/TamperDetection: Add tamper detection to your application.
samples/EnvironmentCheck: Check the environment in which your application is running.
samples/LoggingRemoval: Thoroughly remove Android logging code.

You can specify custom configurations in the following optional files:

dexguard-project.txt         (for all targets)
dexguard-project-debug.txt   (for target 'debug')
dexguard-project-release.txt (for target 'release')
proguard-project.txt         (for backward compatibility with ProGuard)

All options are all illustrated in the sample projects in the directory samples. Our best practices can serve as a guideline.

Quick Troubleshooting

If you have problems setting up your project:

Make sure you are using a recent Android SDK. You can update it interactively with the standard command:
```
android
```
If you can't find local.properties, make sure your project is updated to work with the installed Android SDK. For example:
```
android update project --path MyAndroidProjectDirectory
```
You can build and run a sample to quickly check if your environment is set up properly:
```
cd samples/HelloWorld
  (edit sdk.dir in the file local.properties)
ant debug install
```
By default, the samples target "android-15", so you should have the target API for Android 4.0.3 installed.

If the obfuscated application doesn't work, you may have to add some custom configuration to dexguard-project.txt. The most common issues on the Android platform:

ClassNotFoundException: the application tries to access a class by means of reflection, but DexGuard has removed or obfuscated it. You should explicitly preserve the class. For example:
```
-keep class mypackage.MyClass
```
NoSuchMethodException: the application tries to access a method by means of reflection (for a WebView, for instance), but DexGuard has removed or obfuscated it. You should explicitly preserve the method. For example:
```
-keepclassmembers class mypackage.MyClass {
    void myMethod(java.lang.String);
}
```

You can look at the generated files bin/proguard/seeds.txt and bin/proguard/usage.txt to check which classes and class members DexGuard has explicitly kept (due to the configuration), or removed (because they appeared unused).

Please consult the extensive troubleshooting section if you encounter other issues.