Overview

Apteligent monitors, prioritizes, troubleshoots, and trends your mobile app performance issues in real-time; this document provides a detailed explanation on how this is accomplished.

Apteligent offers the following capabilities:

Supported Platforms

Developers can integrate Apteligent for apps that run on the following platforms:

  • Apple (iOS / tvOS)
  • Android
  • HTML5
  • Unity
  • PhoneGap
  • Hybrid apps (native platform with HTML5 components)

Usage Tracking

An app load occurs whenever a user launches the app on their device. When the user begins using an instrumented application, the library automatically records an app load event. Apteligent then aggregates app loads into rolling daily and monthly active user counts (using a Apteligent-generated unique identifier), and provides (on the Crash Trends page) insight into the relative usage of the application’s released versions. For example, you can see the number of app loads per version of your app, or the percentage of app loads that resulted in a crash (crash percentage).

Crash Reporting

A crash is a run-time exception that occurs due to some unexpected event that terminates the user session. Crashes are events that are not handled within a try/catch block in the app. When an app crash occurs, the Apteligent library records the device state and sends the stack trace to the Apteligent platform. The Crash Reporting page of the portal shows the event, alongside additional metrics to help with root cause analysis and debugging. Crashes are grouped together to make it easier to identify the most frequent crashes. Apteligent alerts the developer of the error, and provides the information necessary to reproduce the issue in local development / testing.

Tracking exceptions allows developers to:

  • Identify potential hotspots where errors might occur.
  • Analyze exceptions by viewing the stacktrace, diagnostics, metadata, and breadcrumbs related to that issue.
  • Prioritize and resolve bugs to reduce or eliminate errors and crashes.

User Flows Monitoring

User flows allows developers to track key interactions or user flows in their app such as login, account registration, and in app purchase. By default, the SDK will automatically track application load time as a user flow. You can specify additional user flows by adding a few more lines of code to your application.

A user flow failure rate can be monitored in the Apteligent portal. Each failed user flow comes with a slew of diagnostics that allow developers to debug why a particular user flow is failing. The business impact of each user flow is displayed in dollars to allow business owners to assess the impact of user flow failures and bugs.

Data Reported with User Flows

The following information is reported with each user flow:

  • User flow group name (eg. “user login”)
  • Completion state: success and failure (crashed, timed out or declared failure)
  • Business value (a user defined value, measured in dollars)
  • Start time
  • Stop time
  • Active time (the time the user flow was running in the foreground)
  • Diagnostics which include app version, operating system, device Model, carrier, and more.

User Flows Final States

Each user flow may stop in one of a few possible final states.

  • Success. A success state is reached through the end userflow API. Success can be used to denote that a user flow’s goal was accomplished. Calling the end userflow API is required to finish a user flow in a success state.
  • Cancelled. A cancelled state is reached through the cancel userflow API. An unfinished user flow that is cancelled is removed and will not be reported to Apteligent. Cancelled user flows are ignored. If a developer does not specify success, failure, or cancelled in code, then the only possible remaining final states a user flow can reach are crashed and timed out.
  • Failed states:
    • Crashed. A crashed state occurs only if the app crashes while the user flow is in progress. During a crash, Apteligent automatically marks all started user flows as crashed, and reports the user flows to Apteligent. On the Apteligent portal, users may view which crashes impacted a user flow.
    • Timed Out. A timed out state is reached when a user flow has remained started longer than a specified period of time. The timed out user flow is stopped and sent to Apteligent. Timeout periods for user flows can be adjusted in the Apteligent portal.
    • Declared failures. A failed state that is reached through the fail user flow API. Failed can be used to denote that a user flow’s goal was not accomplished. Calling the fail user flow API is required to finish a user flow in a failed state. Example: If a user does not allow your photo-sharing app to access the phone’s camera during onboarding, you may wish to declare the onboarding user flow you’ve defined as failed

Once a user flow has stopped in a final state, the state can no longer be changed.

User Flows Traces

Every non-successful user flow (failed, crashed, or timed out) is reported with a log of events that occurred while the user flow was in progress. User flows traces can be used by developers to diagnose why a user flow is failing. The events collected include Breadcrumbs left by the developer, networking calls captured by Service Monitoring, and important system events that may have impacted the user flow. The following system breadcrumbs are captured automatically by Apteligent:

  • Network connectivity gained / lost
  • Network connection type changes (eg. wireless to wifi)
  • App backgrounds
  • App foregrounds
  • Screen transitions (Android only; Apple coming soon!)
  • Handled Exceptions

Handled Exceptions

A handled exception is a run-time exception that gets handled within a try / catch block. Handled exceptions are anticipated errors that developers can log with a Apteligent API call. For apps with integrated Apteligent functionality, whenever a handled exception occurs, Apteligent logs it as a handled exception event.

Note

Handled exception tracking is available only on a paid subscription plan.

The Apteligent portal displays handled exception metrics to help developers with root cause analysis and debugging.

Automatic Breadcrumbs

Automatic breadcrumbs allow developers to get additional information about the steps users have taken or key events that happen in the apps without requiring additional code changes. Events that trigger these breadcrumbs are stored by our SDK and displayed in our portal alongside developer-defined breadcrumbs, allowing you to trace back through the last steps users took or key events in your app before an error occurred. These breadcrumbs help you reproduce issues more easily and contain valuable diagnostics information.

Note

Automatic breadcrumb logging is available only on a paid subscription plan.

Here are the different events that are stored as automatic breadcrumbs:

  • Handled Exceptions​​
  • App Background/Foreground
    • “App foregrounded”
    • “App backgrounded”
  • Network Breadcrumbs
    • URL
    • Request type
    • Latency
    • HTTP Status
    • Bytes in/Bytes out
  • Network Connectivity Changes
    • “Internet connection UP”
    • “Internet connection DOWN”
    • “XX (Connectivity State) connectivity gained”
    • “Switching from XX (Connectivity State) to XX (Connectivity State)”
    • Android connectivity states are: unknown, disconnected, 2G, 3G, EDGE, GPRS, LTE, Wifi
    • Apple connectivity states are limited to: Wifi, cellular
  • UIView Loads (and View Names)
    • (Name of the View) loaded
    • (Name of the View) unloaded
  • App Launched
    • “Session Start”
  • Apple Watch Communication
    • handleWatchKitExtensionRequest

User Metadata

Developers can associate metadata with each user in order to help differentiate users on both the portal and the client. Apteligent displays this information in the Crash Report tab (under Affected Users when you select a specific user).

Note

User metadata logging is available only on a paid subscription plan.

Examples of user metadata include shopping cart or userflow information associated with the user at time of a crash, and factors (events, variables or state information) within the user flow (such as the level of a game, its location, or current app view).

This capability allows customer support staff to view metadata in the portal by:

  • searching by user name to determine how many crashes a given user has experienced, and
  • viewing a list of users who experienced a crash or handled exception.

Tracking user metadata, in combination with stack traces and diagnostics, enables support staff to better correlate data, priorities issues, and respond to support tickets.

Developers can also attach an arbitrary amount of metadata to each user through a method that accepts key and value parameters. The Apteligent Portal displays this information when viewing a user profile.

Note

Apteligent collects certain diagnostic information about a crash automatically, such as the device type, the OS and OS version on the device, and the app version. This information does not need to be collected separately as user metadata.

Apteligent takes user privacy very seriously. If we detect an app sending Device Identifiers or other personally identifying information (PII) that does not help with debugging a crash, we will ask the app developer to remove the gathering of this information through our service.

Service Monitoring

Whenever an app makes a network call, Apteligent monitors and captures certain information:

  • service name
  • device type
  • device OS and OS version
  • app version
  • location information

Note

Location information allows visibility into a user’s geographic location, which can help with quantifying the number of app users within a geographic region, or with contexualizing a certain issue based on location (e.g. outages). By default, location information is determined by performing a reverse Geo lookup on the IP address of the device. The IP address is immediately thrown-away and not stored on our platform. Optionally, for more granular and detailed location information, the SDK provides an API to send latitude & longitude coordinates for the device.

  • endpoint URI (available only on a paid subscription plan)

For HTTP calls (such as REST apps), Apteligent monitors and captures the following information:

  • HTTP URL
  • HTTP status codes to help determine whether a call succeeded or failed
  • latency (elapsed time between request and response received)
  • amount of data received in the response

Symbolication

Symbolication is the process of translating stack traces into a human-readable form by mapping hexadecimal addresses to function names using symbol file(s). Apteligent automatically symbolicates crashes once you have uploaded your app’s symbol file(s).

  • For Apple applications, stack traces are reported in hexidecimal characters. Symbolication allows developers to convert these hex strings into human-readable text. For more information, see Configuring Crash Symbolication.
  • For Android applications that use the Android Native Development Kit (NDK), developers can upload a shared object (.so) file that contains debug characters in order to convert stack traces into human-readable text. For more information, see Configuring Android NDK Symbolication.
  • For Android applications that use the ProGuard tool to obfuscate their function names, developers can use a Proguard mapping file to replace the obfuscated name with a human-readable name. For more information, see Configuring Proguard Symbolication.

Opt Out of Apteligent

Certain app users might want to opt out of Apteligent logging and tracking. Apteligent provides a static opt-out status setting that disables all app reporting to Apteligent. This feature is optional. If used, developers must implement the code that prompts the app user to select whether or not to opt out. If a user has opted out, their instance of the app will not report any activity back to Apteligent.

Setup SAML Single Sign-On

Apteligent supports Security Assertion Markup Language (SAML) 2.0 Single Sign-On from various Identity Providers. Configuration is needed in both Apteligent and your Identity Provider, so it will require users to have both Apteligent Account Owner access and admin access in the Identity Provider system.

Currently Supported Identity Providers:

Note

Don’t see your identity provider listed below? Contact us and we will help you with your SAML integration.