Instrument Android application with customer certificate

Perfecto provides an instrumentation activation tool that enables you to inject an Android Application Kit (APK) or Android Application Bundle (AAB) into Amazon's AWS S3 without connection to the MCM. The result of the tool's processing is the instrumented APK or AAB file that can be installed on the Perfecto device.

Additionally, the tool supports signing the instrumented app with a certificate that you supply. This allows automation testing of the app in a form that better resembles the app that will be used by the end user. The main advantages of this Customized Instrumentation feature include:

• Users have the ability to instrument the app while maintaining the original application entitlements and signature.

• The instrumentation process remains the same, except for the re-sign step.
  

  Instead of re-signing with the Perfecto certificate, the application signature is performed locally, at the customer's premises, on a Mac machine with the customer’s enterprise certificate.

Supported environments

The instrumentation tool supports the following environments:

• Windows
• Mac OS
• Linux OS

Prerequisites

Before installing the tool, verify that the workstation that will run the instrumentation with a customer certificate has Python 3 with request module installed, as follows. Python 2.x is not supported.

To install the request module, run the following command:

python -m pip install requests

python -m pip install requests

Obtain the Python script

The script to activate the instrumentation is customInstrumentWrapperAndroid.py. You can retrieve the script from our Perfecto Code site. 

Install the script on the workstation that will be used to perform the instrumentation, in a folder of your choice.

Execute the script

The script performs the following steps:

1. Uploads the APK or AAB file to the AWS cloud.

2. Instruments and signs the application. The AWS cloud stores the resulting APK or AAB file at S3.

3. Returns a link to the instrumented and signed APK or AAB file.

   The APK or AAB file is also stored in the folder indicated in the output folder parameter (see the following Parameters section).

To run the script:

1. Open the command-line interface for the workstation and the folder where the script was installed.

   Execute the script only from the folder where it was installed.

2. Supply the mandatory parameters. To learn more, see the following Parameters section.

3. To sign the application with a certificate, provide the following:

   • The certificate

   • The certificate password or the Keystore password

   • The certificate user

4. Run the script.

Add a certificate

The tool can receive a certificate and send it to the server. The server signs the app with the certificate and returns the signed app. For signing, the tool needs the certificate file, the certificate key, the certificate user, and the key store password.

If a user does not supply any of the certificate parameters, the app returns a default debug certificate.

Generate a security token

To create a Perfecto security token, use the following link: Generate security tokens via public API

Run the activator tool

Perform the following steps to run the activator tool:

1. Place the following on the local workstation:

   • The APK or AAB file (mandatory)

   • The Python script (mandatory)

   • The token file (mandatory)

   • The certificate file (optional)

2. To activate the instrumentation, execute the instrumentation activation tool (Python script): customInstrumentWrapperAndroid.py

   Important: The path of the shell must be the path of the script.
   Copy

   Windows

   python customInstrumentWrapperAndroid.py

   Copy

   macOS

   python3 customInstrumentWrapperAndroid.py

   For Linux, use either the python or the python3 command, whichever activates Python 3.

When the instrumentation completes, a notification is presented to the user and the instrumented APK or AAB file is copied to the target folder indicated by the output folder parameter (see examples).

Every run, the application hash must be replaced. Otherwise, AWS uses the old APK or AAB file and does not store a new one.

Parameters

The following table describes the parameters to be included in the instrumentation activation script.

[-i]

[-o]

[-t]

[-T]

[-u]

[-v]

[-ih]

[-is]

[-iscr]

[-os]

[-cu]

[-cp]

[-kp]

[-cf]

[-dc]

¹ Verify that there are no white spaces in the file path.

² At least one of the following instrumentation type parameters (path to text file or the text) must be true: -t or -T

³ At least one of the following instrumentation type parameters must be true: -ih (=hybrid), -is (=sensors), -iscr (=secured screens). If the parameter is not included, its value defaults to false.

⁴ The app must be signed in another process because it cannot run without any signature.

Instrumentation examples

Following are instrumentation examples for each OS. Make sure to run the script in the same directory where the Python script is installed.

Windows

Copy

Without certification (the instrumented APK file, in this example, will be copied to C:\PM\target)

python "customInstrumentWrapperAndroid.py" -i "C:\PM\MultipleWebViews.apk" -o "C:\PM\target\MultipleWebViews.apk" -t "C:\PM\cloudToken.txt" -u "mycloud.perfectomobile.com" -v 18.4 -ih -os 6

Copy

With certification (the instrumented APK file, in this example, will be copied to C:\PM\target)

python "customInstrumentWrapperAndroid.py" -i "C:\PM\MultipleWebViews.apk" -o "C:\PM\target\MultipleWebViews.apk" -t "C:\PM\cloudToken.txt" -u "mycloud.perfectomobile.com" -v 18.4 -ih -os 6 -cu "cer_user" -cp "pass!" -cf "C:\PM\my.keystore"

Linux

Copy

Without certification (the instrumented APK file, in this example, will be copied to home/PM/target)

python "customInstrumentWrapperAndroid.py" -i "home/PM/Barcodes.apk" -o "home/PM/target/Barcodes.apk" -t "home/PM/cloudToken.txt" -u "mycloud.perfectomobile.com" -v 18.4 -ih -is -os 6

Copy

With certification (the instrumented APK file, in this example, will be copied to home/PM/target)

python "customInstrumentWrapperAndroid.py" -i "home/PM/MultipleWebViews.apk" -o "home/PM/target/MultipleWebViews.apk" -t "home/PM/cloudToken.txt" -u "mycloud.perfectomobile.com" -v 18.4 -ih -os 6 -cu 'cer_user' -cp 'pass!' -cf 'home/PM/my.keystore'

Mac

Copy

Without certification (the instrumented APK file, in this example, will be renamed and saved to the same directory)

python3 customInstrumentWrapperAndroid.py -i Barcodes.apk -o Barcodes_Instrumented.apk -t cloudToken.txt -u mycloud.perfectomobile.com -v 18.4 -ih -is -os 6

Copy

With certification (the instrumented APK file, in this example, will be renamed and saved to the same directory)

python3 customInstrumentWrapperAndroid.py -i MultipleWebViews.apk -o MultipleWebViews_output.apk -t cloudToken.txt -u mycloud.perfectomobile.com -v 18.4 -ih -os 6 -cu cer_user -cp 'pass!' -cf my.keystore

Troubleshooting customized instrumentation