Use the Android Wrapper to Embed Monitoring in an Android App

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 How To Embed 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 Mac 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

Mac OS X 10.7 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 16 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.

  • Ensure the Android device is running Android version 4.1 - 6.0.

  • 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 Contact Customer Services for a link to download and install the Aternity Android Wrapper.

    To install, extract the Aternity Android Wrapper <version>.zip file into a folder to create an AternityWrapper sub-folder containing the wrapper tool.

  2. Step 2 Copy the tool's aternity_conf file (AternityWrapper/samples/sampleAternity.conf) to your own directory.

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

  3. Step 3 Configure the monitoring settings in the aternity.conf file, written in plain text JSON format. For example:

    For on-premise deployments:

    {
    "Server": "https://myserver.com",
    "UseLocation": "true"
}
    Field Description
    Server (on-premise deployments only)

    For Aternity on-premise, specify the full address of the Aternity Aggregation Server, including its protocol (mandatory) and port (optional). For example, "https://aggserver.company.com:443"
    UseLocation

    Set this value to true for apps which report their location.
    (Aternity on-premise only) If the app connects to your Aggregation Server via a proxy server, enter the server name then the proxy server name in the following format:
    http[s]://AggSrv_IP_or_Name[:Agg_port],[user]:[password]@ProxySrv_IP_or_Name:Proxy_port
    Connect via a proxy server

    • AggSrv_IP_or_Name is the address of the Aggregation Server, after going via the proxy server.

    • Agg_port is the (optional) port number for accessing the Aggregation Server.

    • user and password represent the (optional) login required to gain access to your proxy server.

    • ProxySrv_IP_or_Name is the address of your proxy server.

    • Proxy_port is the (mandatory) port to access the proxy server. Use 80 for unsecured http, or 443 for a secured https access to the proxy server.

  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