Run offline instrumentation on Android apps

To run offline instrumentation on Android apps, perform the following steps. Before you start, review the Offline instrumentation for Android apps prerequisites.

On this page:

Step 1 | Install the tool

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

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. The folder contains the following six files:
- offline-instrumentation-jars.zip
- offline-tools.zip
- pmlib.zip
- install_offline_instrumentation.sh
- install_offline_instrumentation.bat
- extract.ps1
Do not extract the inner ZIP files. Keep all six files together until you run the installer. The installer extracts the ZIP files and deletes them when installation finishes. On Windows, keep extract.ps1 beside the installer because it is used if extraction with PowerShell's Expand-Archive and tar is unavailable.
Open a command-line window in the folder to which you extracted the package. On Windows, open Command Prompt with Run as Administrator. The Windows installer exits if it does not have Administrator rights, which it needs to create symbolic links for the Android build tools.
Run the installation command for your platform. On Windows, use install_offline_instrumentation.bat; the install_offline_instrumentation.sh script is not supported on Windows. Replace <target-install-folder> with an installation path that contains only English letters, digits, hyphens, underscores, dots, and parentheses.

If the selected installation folder contains a previous installation, the installer overwrites it without confirmation, including deleting and replacing the Android build tools. To upgrade or downgrade the tool, run the installer with the same target folder.
Copy
Windows (Command Prompt)
```
install_offline_instrumentation.bat <target-install-folder>
```
Copy
Linux/macOS
```
./install_offline_instrumentation.sh <target-install-folder>
```
On Linux/macOS, if you omit the target folder, the script prompts you with Enter the installation folder name:. If execution fails with Permission denied, run the following command and then run the installer again:
Copy
Linux/macOS
```
chmod +x install_offline_instrumentation.sh
```

The script creates an OfflineInstrumentation folder inside the installation location. The installed folder contains the following files and dependencies:

LICENSE.txt: License information.
offline-instrumentation.version: Build metadata.
offline-instrumentation.jar: The tool to run with java -jar.
pmlib.zip: Used automatically by the tool. Do not specify it on the command line.
bin/instrumentation.jar: A bundled dependency. Do not run it directly.
bin/Android/tools: Android build tools selected for your operating system, including aapt2, zipalign, dexdump, apksigner.jar, bundletool.jar, ManifestEditor.jar, and the default signing certificate, PerfectoKey.jks.

Keep the installed folder intact. Do not move offline-instrumentation.jar out of it on its own; the tool depends on bin/instrumentation.jar, bin/Android, and pmlib.zip.

Step 2 | Perform offline instrumentation

Repeat the following steps for each original, uninstrumented app you want to instrument. Do not instrument an output file again because this can corrupt it.

In the command-line window, change to the installed OfflineInstrumentation folder. Alternatively, use the full path to offline-instrumentation.jar in the command.
While running, the tool uses inner folders and removes most of their contents when the run finishes. Make sure there is enough free space for the run on the installation drive.

Run the tool with -f for the input app, -o for the output folder, and at least one instrumentation flag. The output folder is created if it does not exist, and it must not be the folder that contains the input app. Each flag requires an explicit true or false value. Set each instrumentation type you want to enable to true; omitted flags default to false. Enabling one type does not enable any other type.

To learn more about the available parameters, see Parameters for Android offline instrumentation.
Copy

Object (hybrid) instrumentation with default signing
```
java -jar offline-instrumentation.jar -f "<input-file-path>.apk" -o "<output-folder-path>" -spy true
```
Copy

Camera and fingerprint injection for an Android App Bundle
```
java -jar offline-instrumentation.jar -f "<input-file-path>.aab" -o "<output-folder-path>" -camera true -finger true
```
Copy

All instrumentation types with debug logging
```
java -jar offline-instrumentation.jar -f "<input-file-path>.apk" -o "<output-folder-path>" -spy true -camera true -finger true -securedscreen true -loglevel DEBUG
```
By default, the tool signs the output with its bundled certificate. To use your own keystore, supply all four custom-signing parameters together:
Copy

Signing with your organization's certificate
```
java -jar offline-instrumentation.jar -f "<input-file-path>.apk" -o "<output-folder-path>" -spy true -keypath "<keystore-file>" -keystorepass "<keystore-password>" -keyalias "<key-alias>" -keypassword "<key-password>"
```
Locate the instrumented file in the output folder. An .aab input is converted to a split-APK set and produces an .apks output, not an .aab. An .apk or .apks input retains its file type on output.

Step 3 | Upload the app to Perfecto

Upload the resulting .apk or .apks file from the output folder.

How you upload the instrumented application to Perfecto depends on whether you are a manual tester or an automation tester.

Make sure not to instrument the app again during the app installation process.

Manual tester: Install and start the app through the Perfecto UI.

To learn more, see Application management.
Automation tester: Upload the app to the Perfecto repository, and then install and start the app on the device using Appium drivers.

To learn more, see Upload the file to the Perfecto repository media folder and Install the file and start the app on the device.

What's next?

When the app is instrumented, installed, and running on the device, you can inject sensory input. If you enabled object (hybrid) instrumentation, you can also use Object Spy to inspect app objects. To learn more, see Sensor testing.