Instrument Android applications offline

With Perfecto, you can instrument Android applications even if you are subjected to network and security restrictions that do not allow you to connect through the internet to Perfecto servers. Any of the following reasons may prevent you from leveraging Perfecto's online instrumentation service:

Your build environment is not connected to the internet
Your organization's security team does not permit online app transfer
Performance considerations prevent you from connecting to the online instrumentation service
You cannot install the app using Perfecto's regular app installation process
You have to sign your app with your organization's certificate and this prevents you from performing instrumentation during Perfecto's online app installation process

If any of these restrictions apply to you, contact Perfecto Support about Perfecto's offline instrumentation option for Android applications, a CLI instrumentation tool.

On this page:

Prerequisites

Perfecto's offline instrumentation tool for Android requires the following:

Access to the application's .aab or .apk file to be instrumented
Java 17 or later

Limitations

Perfecto only supports the latest version of the offline instrumentation tool. Make sure you always run the latest version of this tool. To request the latest version, contact Perfecto Support .

If you are not sure which version you use, run the tool with the optional parameter -V to display the current version.

If you are not sure which version is the latest version, see our Release highlights.

Installation steps

Perform the following steps to install the offline instrumentation tool. Repeat these steps whenever a new version of the tool becomes available.

To install the offline instrumentation tool:

Contact Perfecto Support to request the offline instrumentation tool. The Perfecto Support team will send you the offline instrumentation installation package (a file called offlineInstrumentation-offlineBundle-<version>.zip).
Extract the offline instrumentation installation package to a folder of your choice.
On Linux/macOS, to verify and set the proper permissions before executing the script, open a command-line window and run the following command from the folder to which you extracted the package.
Copy
Linux/macOS
```
chmod +x install_offline_instrumentation.sh
```
In a command-line window, from the folder to which you extracted the package, execute the install script depending on your platform.
Copy
Windows
```
install_offline_instrumentation.bat
```
Copy
Linux/macOS
```
bash install_offline_instrumentation.sh
```
When prompted for the installation location, provide the path to the installation folder. Make sure the installation path does not contain spaces or special characters.

Important: If the selected installation folder is not empty, the installation will override any files from a previous installation without any notification.

The script creates an OfflineInstallation folder inside the installation location you specified in step 5 and extracts files to this folder. When the installation is complete, the script deletes the .zip files and scripts that you extracted from the package you received from Perfecto Support.

Offline instrumentation steps

Perform the following procedure to instrument your Android application locally, offline. Repeat these steps for each app you want to instrument.

During the execution, the script reports its progress. Upon completion, the fully instrumented .aab or .apk file is generated.

To perform offline instrumentation:

From the command-line window, run the following command with the relevant parameters. To learn more, following the code snippets, expand the sections Required parameters, Instrumentation parameters, Parameters for signing your app with your organization's certificate, and Other optional parameters.

Copy

Example 1 with parameters

java -jar "<path_to_file>/offline-instrumentation.jar"

-f "/<path_to_file>/SecureScreen_demo.apk"

-o "/<path_to_output_folder>"

-pmlib "/<path_to_file>/pmlib.zip"

-androidsdk "/Users/{user}/Library/Android/sdk"

-below5 false

-camera false

-finger false

-spy false

-activity false

-securedscreen true

Copy

Example 2 with parameters

java -jar "/<path_to_file>/offline-instrumentation.jar"

-f "/<path_to_file>/SecureScreen_demo.apk"

-o "/<path_to_output_folder>"

-pmlib "/<path_to_file>/pmlib.zip"

-securedscreen true

Required parameters

The following table lists the available required parameters.

Parameter Description

Parameter	Description
`-f`	The path to the input `.aab` or `.apk` file. Make sure the file path does not include any white spaces.
`-o`	The path to the output folder of the `.aab` or `.apk` file. Ideally, this is a different location than the input file. When instrumenting an`.aab` file, the instrumented output file is unbundled and has an `.apks` extension. Ignore the `.aab` file in the output folder.
`-pmlib`	The path to the `pmlib.zip` file. Make sure the file path does not include any white spaces. Important: This parameter is deprecated. It will be removed in the next version of the offline instrumentation tool.

-f

The path to the input .aab or .apk file. Make sure the file path does not include any white spaces.

-o

The path to the output folder of the .aab or .apk file. Ideally, this is a different location than the input file.

When instrumenting an.aab file, the instrumented output file is unbundled and has an .apks extension. Ignore the .aab file in the output folder.

-pmlib

The path to the pmlib.zip file. Make sure the file path does not include any white spaces.

Important: This parameter is deprecated. It will be removed in the next version of the offline instrumentation tool.

Instrumentation parameters

The following table lists the available instrumentation parameters. At least one instrumentation parameter must be set to true. If a parameter is not included, its value defaults to false. If none of the parameters is included, the default is -spy "true".

Parameter	Description
`-spy`	`true`/`false` where `true` initializes object instrumentation (also called hybrid instrumentation)
`-camera`	`true`/`false` `The value true` initializes camera instrumentation for image injection. Works in mutual exclusion with the `cameraX` parameter. If set to `true`, the `cameraX` parameter is ignored.
`-cameraX`	`true`/`false` `The value true` initializes CameraX (based on androidx) instrumentation for image injection. Works in mutual exclusion with the `camera` parameter. If set to `true`, the `camera` parameter is ignored.
`-finger`	`true`/`false` `The value true` initializes fingerprint instrumentation for fingerprint injection.
`-securedscreen`	`true`/`false` `The value true` removes the secured screen flag from the app.

Parameters for signing your app with your organization's certificate

The following table lists the parameters to be used to re-sign your app with your organization's certificate. Re-signing your application is optional.

Parameter	Description
`-keypath`	The full path to the keystore file. If this information is not provided, the app is signed with Perfecto's certificate.
`-keystorepass`	The secure password for the keystore file.
`-keyalias`	The identifying name for your key.
`-keypassword`	The secure password for your key.

Other optional parameters

The following table lists the available optional parameters.

Parameter	Description
`-below5`	`true`/`false` `A value of true` builds an instrumented version of an application for Android versions earlier than 5.0. The default is `false`. Important: This parameter is deprecated. It will be removed in the next version of the offline instrumentation tool.
`-sign`	`true`/`false` Indicates whether to sign the app. The default is `true`. Important: This parameter is deprecated. It will be removed in the next version of the offline instrumentation tool.
`-androidsdk`	The path to the Android SDK (for multidex apps and Android versions earlier than 5.0).
`-h`, `--help`	Bring up a help message and exits.
`-V`, `--version`	Print version information and exits.