Embed Monitoring in an Android App with the Android Wrapper

To add monitoring to a mobile app, you must embed Aternity's monitoring into the app itself, before it is encrypted. This automatically starts reporting a wealth of performance and usage data by default. This article describes how to embed monitoring in Android apps using the Aternity Android Wrapper.

Adding a mobile app for monitoring

The Aternity Wrapper is a command line tool which quickly and automatically adds monitoring features to your mobile app, without requiring access to the app's source code.

To determine whether to use the Aternity Android Wrapper or the Aternity Android Mobile SDK to integrate monitoring in your app, see Start Embedding Monitoring in a Mobile App.

With the Aternity Wrapper, you can sign the app at the same time as applying Aternity's monitoring functionality, all in a single command.

Before you begin

Before embedding Aternity's monitoring into an Android mobile app, verify your device conforms to the following minimum system requirements (Aternity Android Wrapper or Aternity Android Mobile SDK):

Attribute Requirement (Android Wrapper and Aternity Android SDK)

Operating system

Android 4.4 or later.

Java Developer Kit

JDK 1.8 or later.

Programming environment

Google Android Studio or a standalone Android SDK.

Using the SDK Manager, install the latest Android SDK tools (platform tools and build tools) for SDK Platform API level 19 or newer.

Connectivity

Internet access.

App resource usage

When you add Aternity functionality to an Android app:

  • Disk storage barely changes at all.

  • RAM size is an extra 5-10MB.

  • CPU usage rises by 1%.

  • Your app must be fully functional and ready for deployment.

  • To run a monitored app, the device must have the following operating systems:

    Attribute Requirement

    iOS operating system of monitored device

    iOS 10 or later.

    Android operating system of monitored device

    Android 4.4 or later.

  • Download and install Google Android Studio or a standalone Android SDK on the same computer as the Aternity Wrapper.

  • Download and install JDK. Once installed, type java -version in the command shell to verify the Java installation and version.

  • Ensure your certificate is properly installed in a keystore accessible on the computer you are using to wrap and sign the app. For more information on the Java keytool utility, check Oracle's keytool documentation.

Procedure

  1. Step 1 Download Aternity Mobile by selecting the Gear Icon > Agent Download.

    To add monitoring to a mobile app, you must embed Aternity's monitoring into the app itself, before it is encrypted. This automatically starts reporting a wealth of performance and usage data by default.

    Select the embedding tool for your mobile operating system.

    Download Aternity Mobile
    Field Description
    Wrapper for iOS / Wrapper for Android

    The Aternity Wrapper is a command line tool which quickly and automatically adds monitoring features to your mobile app, without requiring access to the app's source code.

    With the Aternity Wrapper, you can sign the app at the same time as applying Aternity's monitoring functionality, all in a single command.

    SDK for Android / SDK for iOS

    With the Mobile SDK you can insert API calls to fine-tune the monitoring, by dynamically setting properties (like the device name, location), or tag events for use in some types of custom activities, or you can use APIs to report breadcrumbs for later troubleshooting of crashes.

  2. Step 2 Extract the zip file to view the AternityWrapper folder containing the wrapper tool.
  3. Step 3 Copy the file (AternityWrapper/aternity.conf) to your project folder as a resource.

    The conf file defines the monitoring settings locally in the app, where each setting has a value.

  4. Step 4 On a Mac with the Android SDK, Java and the Aternity Wrapper installed, open a command shell.
  5. Step 5 To view a brief description of the Aternity Wrapper's parameters, run it without any parameters.

    Type AternityWrapper/wrapper.sh

  6. Step 6 To activate the Aternity Wrapper, type the following:
    AternityWrapper/wrapper.sh -k MyCompany.keystore -kp ABCD123 -kt pkcs12 -ka MyCompanyCertificate -l Aternity.conf ~/Documents/MyApp.apk ~/Documents/MyApp_wrapped.apk
    Important

    You can copy and paste directly from here to the command shell. Do not copy and paste via a rich text word processor like Microsoft Word, as sometimes they automatically replace a hyphen with an m-dash which are not recognized.

    Field Description
    -k <keystore_path>

    Use -k or --keystore to provide the pathname of the keystore containing the certificate to sign your app.

    -kp <keystore_pswd>

    Use -kp or --storepass to provide the password required to access the keystore as a whole (not an individual item in the keystore).

    -kt <keystore_type>

    Use -kt or --storetype to provide the format standard used for creating the certificates in this keystore. For example, pkcs11 or pkcs12.

    -ka <filename>

    Use -ka or --keystore_alias to provide the name (handle or alias) which refers to a specific certificate in the keystore.

    -l <filename>

    Use -l or --config to specify the pathname of the configuration of Aternity's monitoring, written in JSON format.

    input_app

    Add the pathname of the .apk app which you want to wrap.

    wrapped_app

    Add the pathname of the .apk which is wrapped.

    You can also add the following optional parameters:

    Field Description
    -ja

    Use -ja or --jarsigner_args to provide the pathname to a plain text file containing (only) additional parameters for signing the app. Use this if you want to enhance the signing of the app with additional security options, to supplement those parameters already listed in the command line when running the Aternity Wrapper tool.

    The Aternity Wrapper automatically calls the jarsigner utility from your JDK, using the parameters you gave (like the name of the keystore, its password and so on), and any parameters listed in this parameters file (like -tsa to generate a timestamp using a known timestamp authority. The file would contain a single line, and might be something similar to this:

    -tsa http://timestamp.digicert.com -protected -strict
    Note

    Do not include any parameters in the file which are already present as arguments in the command line (like -k, -ka).

    For more information on jarsigner options, see Oracle's jarsigner documentation.

    -p <permissions_list>

    Use -p or --permissions to override the default list of Android runtime permissions for this app.

    By default, the Aternity Wrapper adds the following Android permissions to the app:

    • INTERNET enables the app to access the Aternity Aggregation Server (mandatory).

    • GET_ACCOUNTS enables the app to report the device name.

    • ACCESS_COARSE_LOCATION enables the app to report the device's location coordinates. This requires UseLocation in the conf file to be set to true.

    • ACCESS_WIFI_STATE enables the app to report its IP address to determine if the device is on site or off site.

    • ACCESS_NETWORK_STATE enables the app to report if the device is connected via WiFi or cellular network connection, and to report the mobile signal strength.

    Customize with your own privileges by listing each permission separated by a comma and no space. For example:

    ./wrapper.sh -p INTERNET,READ_PHONE_STATE,GET_ACCOUNTS
    -pp <password>

    Use -pp or --keypass to add a password (if required) for the specific entity (alias) in the keystore.

    You must use this argument when the signing identity extracted from the provisioning profile matches more than one certificate in the Key Chain store. It is highly recommended though to always specify this argument in order to avoid ambiguous matching of signing identity.

Example

Wrapping a standard Android apk app:

AternityWrapper/wrapper.sh -k MyCompany.keystore -kp ABCD123 -kt pkcs12 -ka MyCompanyCertificate -l Aternity.conf ~/Documents/MyApp.apk ~/Documents/MyApp_wrapped.apk

Wrap an app while signing with a keystore entity's password and extra jarsigner options:

AternityWrapper/wrapper.sh -k MyCompany.keystore -kp ABCD123 -kt pkcs12 -ka MyCompanyCertificate -pp CertPassword -ja ~/Documents/jarsigner.extras -l Aternity.conf ~/Documents/MyApp.apk ~/Documents/MyApp_wrapped.apk