Home Data Management Managing Sessions Backgrounded Mobile Events

Table of Contents

Was this article helpful?

Yes No

Thank you for your feedback!

Backgrounded Mobile Events

In this article you'll learn:

  • What it means when an app has been backgrounded and how to use Heap to manage backgrounded events
  • How sessionization and termination interact with background/foreground status

Overview

In some cases, events can be captured when an app has been backgrounded (or terminated). We have an App Visibility State property which you can reference to understand this state when analyzing data.

This doc covers the specific semantics involved in the act of an app being backgrounded.

iOS

Generally, an iOS app can receive background events both when it’s running in the background and when it’s been completely terminated. iOS apps can elect to work with a number of background modes, including the ones depicted below:

Backgrounded

All location modes and push notification modes can receive and respond to events when the app has been backgrounded. You can use Heap to manage these background events in a few different ways.

  1. Autocapture pageviews: A programmatic page change (for example, selecting a new tab in a [UITabBarController](https://developer.apple.com/documentation/uikit/uitabbarcontroller)) autocaptures a Heap pageview. This pageview isn’t sent to Heap until the app is brought back to the foreground, but it is captured when the app is backgrounded. The ts parameter is set accurately, and the event is cached correctly (and survives app termination + relaunch).
  2. Autocapture touches: The sendActions:for: method is the only real way to programmatically invoke a UI control. This is not indistinguishable from a real touch, however, and the Heap library currently ignores all such synthetic events, whether the app has been backgrounded or not.
  3. Custom events: Custom events are captured accurately when the app is in the background. Similar semantics apply as in the autocapture pageviews case above.

Sessionization behavior

The iOS session timeout is set at 300 seconds.
For autocaptured events, this timeout is not affected by background/foreground status. Events autocaptured when the app is backgrounded will extend the current session, and a new session will start if the current one has lapsed, exactly the same as if the app was in the foreground.

Custom events do exhibit different sessionization semantics when the app is backgrounded. A foreground custom event extends the current session, but a background custom event does not.

To illustrate:

Scenario 1: The app is backgrounded, and events (either autocaptured pageviews or custom events) are fired in the background more than 300 seconds after the app was backgrounded. The session has expired, so these background events (and subsequent foreground events) form a new session.

Scenario 2: The app is backgrounded, and autocaptured events are fired in the background before 300 seconds have elapsed since the app was backgrounded. This extends the current session, making it possible to send an app to the background, bring it back to the foreground, and maintain one single session.

Terminated

Some location modes (significant-change location service, visits service, region monitoring) and some variants of push notifications (with some caveats) support relaunching a terminated app to deliver a notification. Once relaunched, the app remains running in the background, and needs to be explicitly invoked to be brought to the foreground.

Once the app is relaunched, the same Backgrounded semantics above apply, so there is no material difference between these modes. It is possible to detect that an app has been launched in this manner and disable the Heap library, but this will last until the next time the app is terminated.

Android

On Android, there is no way to perform UI actions on an Android app when it isn’t in the foreground, so there is no need to autocapture backgrounded events. In addition to location/push notification triggers (just like on iOS), Android apps can simply register a Service, which runs arbitrary code regardless of the app’s foreground/background state.

Any custom events fired after the app has been backgrounded each use a synthetic session ID, which makes this sort of scenario possible:

React Native

The React Native library delegates all backgrounding semantics to the underlying native SDK, so the appropriate platform-specific semantics described above apply.