Embed Monitoring in an Android App with the Aternity Android SDK

To add monitoring to your Android app, integrate the Aternity Android Mobile SDK into the app, and then initialize and perform common monitoring tasks with the API. A monitored mobile app is a regular iOS or Android app which has Aternity's monitoring functionality inside, enabling it to report app performance like launch times, errors, crashes, network traffic, and also custom activities performance, and some mobile device data. 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.

Using the API to monitor your mobile app
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 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 Integrate the Aternity Android Mobile SDK into your app development environment. For details, see Integrate and Initialize the Aternity Android SDK into your App.

    Part of integrating the Aternity Android SDK into the app requires initializing it. For full details of the init method in Aternity Android SDK, see Initialize the Aternity Android SDK Manually (init).

  3. Step 3 Whenever a class uses the Aternity Android SDK API methods, you must add the statement:
    import com.aternity.sdk.Aternity;
    Add an import statement whenever a class uses the API
  4. Step 4 (Optional) Tweak monitoring parameters with the following APIs:
    Use Description

    setDeviceName

    You can set a device name for a mobile app using the Aternity Mobile SDK, to display custom device names in the dashboards.

    setSite or setOffSite

    You can set the location's site name for a mobile app in the Aternity Mobile SDK, to track the performance of all end users in that location.

    setUsername

    You can set a username for a mobile app in Aternity Mobile SDK to be consistent with desktops and laptops, so you can track this user's experience across all devices and platforms.

  5. Step 5 (Optional) You can tag an event to monitor custom activities in your mobile app by inserting a call to the tagging API.

    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.

    Reporting custom events from a mobile app which mark the start and end of an activity

    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.

    Tagging a custom event with the API

    While Aternity automatically monitors most user actions (native app or web), if the events you need are not monitored by default, you can tag them manually as the start or end events of your custom activity.

    1. a Mark the event which starts the activity by calling tagApplication with Aternity.Phase.Start.

      The tag APIs return a newly created AternityContext object, which you then send to the server using reportTag.

    2. b Send the start of the event (the AternityContext object) to the Aternity Aggregation Server by calling reportTag.

      The reportTag API sends a tagged event from a mobile app to Aternity when monitoring custom activities.

    3. c Mark the event which ends the activity by calling tagApplication with Aternity.Phase.End.

      The API returns a new (different) AternityContext object.

    4. d Send the end of the event (the new AternityContext object) to the Aternity Aggregation Server by calling reportTag.