DESK auto-instrumentation for Android

To set up user experience monitoring for your Android app, use DESK auto-instrumentation. Auto-instrumentation automatically adds OneAgent to your app and instruments your app without modifying its source code.

Because auto-instrumentation modifies the Dalvik byte-code of your mobile app after you generate the APK file, you have to ensure that your instrumented app is signed with your Google Play certificate before you upload the instrumented APK to the Google Play store.

In case auto-instrumentation doesn't fit your requirements, you can use manual instrumentation to fully customize instrumentation. Manual instrumentation is done on a source code level and you can only instrument your own source code. It isn't therefore possible to instrument 3rd party libraries.

Requirements

• Supported OS versions. See Android Studio system requirements.

• JAVA_HOME environment variable must point to a JDK 1.8

• Install ia32-libs on 64-bit Linux.

  ia32-lib installation instructions

  For Ubuntu later than 13.10:
  sudo apt-get install ia32-libs

  For older Ubuntu versions:
  sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libncurses5:i386 libstdc++6:i386 zlib1g:i386

  To use a different distribution, use installation commands.

How to use auto-instrumentation

The easiest and fastest way to use auto-instrumentation is via the DESK Gradle plugin. The DESK Gradle plugin automatically triggers auto-instrumentation on every build. Because auto-instrumentation inserts OneAgent start-up at the beginning of the application start procedure, you can't control the start-up sequence using OneAgent SDK calls. OneAgent ignores multiple start-up calls.

If you can't use the DESK Gradle plugin because you don't build your app using the Android Gradle plugin, or the DESK Gradle plugin is incompatible with your build script, then you can run the auto-instrumentation script from the command line.

Limitations

• Auto-instrumentation has to add OneAgent code into the primary .dex file. There are some limitations for multi-dex applications.
• Auto-instrumentation only monitors the native part of a hybrid application.

• Use of special characters and spaces in file and path names (for example, ( ) [ ] $ % *) is not allowed.
• APK protection tools (for example, DexGuard) aren't fully supported, this includes features like byte-code protection and tamper detection.
• You can't auto-instrument apps using minSDK 24 or higher, because Android uses a different dex file format that is currently not supported.
• You can't instrument Android App Bundles
• The agent does not support Direct Boot mode. You have to manually startup the agent (see DTXAutoStart property) once the device is unlocked.