Integrate and Initialize the Aternity Android SDK into your App

To add monitoring to a mobile app, you must embed Aternity's monitoring into the app itself, before it is encrypted. 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.

A custom activity for mobile apps starts and ends when the app reports specific events which match the events of an activity's signature file. If Aternity already reports these events by default, you do not need to add manual API calls. However, for some custom activities, you must manually tag and report those events using API calls.

For example, to measure the response time between the start of a sign in and its response, if those events are not automatically reported, insert an API to tag the sign in action, and add another API call to tag its response. When you report each tag to Aternity, it matches them to the custom activity already in place, and then reports the response time in the dashboards. To create your own custom activities, contact Customer Services.

To activate the Aternity Android Mobile SDK, you must integrate it into your development environment and add the init method to initialize it.

The Aternity Android SDK is a zip archive of several files which you add to your development environment and then rebuild the app. The instructions in this section use Android Studio as the example development environment, but it is compatible with other Android development environments like Eclipse. The Aternity Android SDK includes the following files:

  • A plain text configuration file, aternity.conf which defines the monitoring settings locally in the app

  • A library file called aternity_sdk.jar.

Important

(Android only) To monitor the wait times and usage times to display the UXI, you must also wrap the app.

Before you begin

Ensure your app compiles and builds cleanly with no errors, and runs on a simulator or a mobile device.

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%.

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

Attribute Requirement

Android operating system of monitored device

Android 4.4 or later.

Procedure

  1. Step 1 Contact Customer Services to download the Aternity Android SDK.

    Open the zip file and extract the library file (aternity_sdk.jar) and the configuration file (aternity.conf).

  2. Step 2 Open your app project in Android Studio, and verify you can view the libs folder in the Project view.

    If the libs folder does not yet exist, create it by right-clicking the app folder in Android Studio and selecting Reveal in Finder (Mac) or Reveal in Explorer (Windows). Create the libs folder there. Then go back to the project tree in Android Studio and refresh.

  3. Step 3 Drag the aternity_sdk.jar file to the libs folder.
    Drag the jar file into your development environment
  4. Step 4 Right-click the jar file and select Add As Library to add it to the app.
    Adding the jar file as a library
  5. Step 5 Create (or verify you already have) a sub-folder under the res folder, whose Resource type is raw.

    This type of directory must house the configuration file aternity.conf, which is formatted in plain text JSON format.

    Creating a sub-directory in the res folder whose Resource type is raw
  6. Step 6 Drag the configuration file aternity.conf into the res folder as a resource in your development project.
  7. Step 7 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

    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) sign in 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.

  8. Step 8 Add the following recommended permissions to the AndroidManifest.xml file in your project to benefit from the full range of Aternity features:

    • 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.

    Add the permissions before the <application> tag, using the following syntax:

    <uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.GET_ACCOUNTS"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    Add required permissions to AndroidManifest.xml
  9. Step 9 Add the init method to your code to integrate and initialize the app with the Aternity Android SDK.

    The init method's mandatory parameters are the app's standard context object (standard with all Android apps) and the resource ID of the aternity.conf file.

    Aternity.getInstance().init(this, R.raw.aternity.conf);

    where this refers to the standard Android app's context object, and R.raw.aternity.conf is the ID of the configuration file stored in the res\raw folder.

    For example, to initialize the Aternity Android SDK when the app launches, you can override the onCreate method from the app's Application class to add the init at the end of the method. For more information, see Initialize the Aternity Android SDK Manually (init).

    Example to initialize the Aternity Android SDK when the app launches
    Note

    Whenever a class uses the Aternity Android SDK API methods, you must add the statement:

    import com.aternity.sdk.Aternity;
  10. Step 10 Build the app and run it on a device or in the simulator.
  11. Step 11 Within a few minutes, you can see the device in Aternity.

    Select the device icon in the top bar to open the Device Inventory dashboard. Select the Smartphone circle in the Device Types section and view the simulator there.

    Verify the details of the device (or simulator) in the Device Inventory dashboard