Embed Monitoring in your iOS App with the Aternity iOS SDK

To add monitoring to your iOS app, integrate the Aternity iOS 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 performance statistics like launch times, errors, crashes, network traffic, and also custom activities performance, and some surrounding data on the underlying mobile device and user. 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

This control allows you to introduce your own logic to these features, so for example, your app can report a certain location only when it can access a particular IP address.

To use the Aternity iOS SDK in your app, follow this procedure.

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 iOS mobile app, verify your Mac conforms to the following minimum system requirements (Aternity iOS Wrapper and Aternity iOS Mobile SDK):

Attribute Requirement (iOS Wrapper and Aternity iOS SDK)

Operating system

Mac OS X 10.10 or later.

Java Developer Kit

JDK 1.8 or later.

Programming environment

Apple XCode 7 or newer.

Connectivity

Internet access.

App resource usage

When you add Aternity functionality to an iOS app:

  • Disk storage size increases by 3.3MB.

  • 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

iOS operating system of monitored device

iOS 10 or later.

Android operating system of monitored device

Android 4.4 or later.

Procedure

  1. Step 1 Download Aternity Mobile from the Riverbed support site.

    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.

    Download Aternity Mobile
  2. Step 2 Integrate the Aternity iOS Mobile SDK into your app development environment.
    Embed monitoring to an iOS app using the Aternity iOS Mobile SDK
  3. Step 3 Initialize the Aternity iOS SDK.
    Initialize the IOS SDK

    You can initialize either explicitly with one of the init functions, or automatically by adding the Aternity.plist file to your Xcode project. You create a single Aternity object when the SDK initializes, and use it throughout the app to call API functions. For details, see Initialize the Aternity iOS Mobile SDK Manually (activateWithDictionary).

  4. Step 4 Include the Aternity.h header file (in Objective-C) into your source code file. To add it to a Swift project, use a bridging header (see Apple's documentation).
    Include the Aternity header file in any code with an API call
  5. Step 5 (Optional) Tweak your monitoring 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.

    userNameStr

    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.
  6. Step 6 (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, the system 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 the system 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 tagApplicationWithName with AternityStartPhase.

      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 tagApplicationWithName with AternityEndPhase.

      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.
  7. Step 7 To add breadcrumbs in your iOS app to help troubleshoot mobile app crashes, see (Troubleshoot Mobile App Crashes with Breadcrumbs)).

    Breadcrumbs are the events leading up to a crash in your monitored mobile app. Aternity Mobile SDK captures these events and reports them after you restart the app after the crash. You can view the breadcrumbs for each crash in the Crash Details dashboard.

  8. Step 8 Use setCrashCallback to run a callback function in the event of an iOS app crash.

    See Add a Callback for App Crashes (setCrashCallback).