Free trial

Command-line auto-instrumentation for Android

With the auto-instrumentation script you can perform auto-instrumentation on an APK file via the command line. The instrumented APK file is signed with a DESK debug certificate, so you can test the instrumented app on the emulator or a developer device. You have to sign the instrumented app with your Google Play certificate before you can upload the instrumented APK to the Google Play store.

Run auto-instrumentation from the command line

To run auto-instrumentation from the command line:

Click Applications in the navigation menu.

Select your mobile application.

Click the browse button (...) in the top right corner and select Edit.

Click Instrumentation in the left menu.

Select Google Android.

Select the Command line tab.

Download the latest version of OneAgent for Android. The file name is desk-mobile-agents-<version>.zip. Unpack it to a directory of your choice. You will find the auto-instrumentation script in the <MobileAgentUnzipDir>/Android/auto-instrumentor folder.

Create an empty auto-instrumentation property file.

Copy the provided auto-instrumentation property values into your empty auto-instrumentation property file.

DTXApplicationID=<YourApplicationID>
DTXBeaconURL=<ProvidedBeaconUrl>

Alternatively, you can deactivate the auto-start injection feature from the auto-instrumentor with the DTXAutoStart property. In this case, you don't need to specify the DTXApplicationID and the DTXBeaconURL properties, because you have to specify these values in the manual startup call. You have to add the startup call manually into the Application.onCreate method and load the auto-instrumentation configuration with the DESKConfigurationBuilder.loadDefaultProperties(Context) method. For more information, see the OneAgent SDK for Mobile section.

DESK.startup(this, new DESKConfigurationBuilder("YourApplicationID", "ProvidedBeaconURL")
	.loadDefaultProperties(context)
	...
	.buildConfiguration());

Optionally, you can customize auto-instrumentation by setting additional properties. If you have a multidex app, check the auto-instrumentation properties specific for multidex apps.

Optionally, you can enrich auto-instrumentation via OneAgent SDK for Mobile. To do this, add the OneAgent library to your project.

dependencies {
	implementation 'com.desk.agent:agent-android:<version>'
}

Then you are able to use the OneAgent SDK for Mobile. Another option is to manually include the agent-android-<version>.aar file from the folder Android/agent as new module to your project.

Note:
The added OneAgent library and the used auto-instrumentation must have the same version number.

Note:

For multi-dex applications, ensure all OneAgent for Android classes are in the primary .dex file. Use the multiDexKeepProguard Android plugin property and add the line
-keep class com.desk.android.** { *; }
to the provided file. For example:

buildTypes {
    release {
        multiDexKeepProguard file('<your_keep_file>')
    }
}

Run the instrument command with the apk and prop parameters, for example:

instrument.cmd apk=<YourAppName>.apk prop=<YourPropName>.properties

Auto-instrumentation generates a working folder (with the name of the APK file) at the location of the provided APK file and stores the result in the dist folder. The path to this folder will be <pathToYourApk>/<nameOfAPK>/dist/.

There are three APK files in this folder:

  • <nameOfAPK>.apk: The instrumented APK file. The signing information of this file is invalid. Therefore it has to be signed before it can be used.
  • <nameOfAPK>-zipaligned.apk: Intermediate file. The instrumented APK file is zipaligned but not signed.
  • <nameOfAPK>-final.apk: This instrumented APK file is signed with a DESK debug certificate. It can be directly installed on emulators and/or developer devices.

To upload your mobile app on Google Play, you have to sign the instrumented APK <pathToYourApk>/<nameOfAPK>/dist/<nameOfAPK>.apk with your Google Play certificate. The auto-instrumentation script does not automatically sign the instrumented APK file with your Google Play certificate. Therefore, you have to do this step manually. First, you have to zipalign the APK file and then you have to use the tool apksigner to sign the APK file with your Google Play certificate.