> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Monitoring for Android App

> The GermainUX Mobile App library can collect application lifecycle events and selected Android system events.

Components
[`Engine`](https://docs.germainux.com/main/germain-ux-engine)
[`Mobile App`](https://docs.germainux.com/main/germain-ux-mobile-app)
[`RUM JS`](https://docs.germainux.com/main/germain-ux-rum-js)

Availability
2022.1 or later

> [card] [Application Events](#application-events)
>
> Auto-tracked lifecycle events

> [card] [Possible System-Event Categories](#possible-system-event-categories)
>
> Device and network event types

> [card] [Analyze Events](#analyze-events)
>
> Correlate events with failures

> [card] [Troubleshooting](#troubleshooting)
>
> Resolve missing Android events

## Configure Event Monitoring for an Android Application

## Overview

The GermainUX Mobile App library can collect application lifecycle events and selected Android system events.

Application events provide reliable context about the monitored application itself. System-event availability varies according to:

* Android version
* Application state
* Declared and granted permissions
* Background-execution restrictions
* Device manufacturer
* Event-delivery rules imposed by Android

Modern Android versions restrict many implicit broadcasts and device events. GermainUX can collect only events delivered to the monitored application and accessible through supported Android APIs.

## Application Events

After GermainUX initializes, it can automatically monitor supported application events such as:

| Event | Description |
| - | - |
| Application startup | Application process started and GermainUX initialized |
| Application launch | Duration of the monitored application launch |
| Application foreground | Application became visible to the user |
| Application background | Application is no longer in the foreground |
| Low-memory condition | Android notified the application of memory pressure |
| Application crash | Application terminated because of a captured unhandled exception |
| Application exit | Application-controlled termination explicitly reported to GermainUX |
| Application uptime | Total monitored lifetime and foreground or background duration |

The final uptime value requires GermainUX to observe or receive an end condition. Android does not always notify an application before terminating its process.

## Application Launch Monitoring

GermainUX automatically starts application monitoring during initialization.

To obtain meaningful launch measurements:

**1. Initialize GermainUX from the application’s `Application` subclass**

**2. Initialize it only once per process**

**3. Perform initialization early in the application lifecycle**

**4. Avoid unnecessary blocking work before or during initialization**

**5. Test cold, warm, and normal user launches**

Application launch performance can be analyzed by:

* Application version
* Android version
* Device manufacturer and model
* Network state
* User segment
* Release
* Environment

## Foreground and Background Monitoring

GermainUX can record when the application transitions between foreground and background states.

These events help measure:

* Active application usage
* Foreground duration
* Background duration
* Session boundaries
* Interrupted business processes
* Application behavior before a crash or error

Android lifecycle events do not prove that a user intentionally closed the application. A transition to the background may result from navigation to another application, locking the device, receiving a system interruption, or Android lifecycle management.

## Low-Memory Events

GermainUX can capture memory-pressure callbacks delivered to the application by Android.

These events can help investigate:

* Slow application behavior
* Process termination
* Failed operations
* Excessive memory consumption
* Crashes associated with memory pressure
* Device-specific problems

A low-memory callback indicates that Android requested the application to reduce memory usage. It does not necessarily mean that the application itself has a memory leak.

## Configure System-Event Monitoring

Use `setSystemEventsMonitoring()` on `GermainAPMConfiguration` to enable or disable supported system-event monitoring.

### Java

```text theme={null}
GermainAPMConfiguration config =
    new GermainAPMConfiguration(
        "https://YOUR_GERMAINUX_HOST/ingestion/fact"
    );

config.setSystemEventsMonitoring(true);

GermainAPM.init(this, config);
```

### Kotlin

```text theme={null}
val config = GermainAPMConfiguration(
    "https://YOUR_GERMAINUX_HOST/ingestion/fact"
)

config.setSystemEventsMonitoring(true)

GermainAPM.init(this, config)
```

When enabled, the library attempts to collect the system events supported by the installed library and delivered to the application.

The current configuration enables or disables system-event monitoring as a group. Review the installed library version for the precise events it supports.

## Possible System-Event Categories

Depending on Android and application permissions, GermainUX may receive events related to:

* Network connectivity
* Wi-Fi state
* Power connection
* Battery state
* Power-saving mode
* Storage conditions

> [accordion] Show all 12
>
> * Locale and time-zone changes
> * Device configuration
> * Media or external storage
> * Application package changes
> * Device startup
> * Idle state

Do not assume that every event in these categories will be available on every device.

Events involving calls, messages, Bluetooth devices, media, other applications, or sensitive device state can require restricted permissions or may be unavailable to ordinary applications on modern Android versions.

Do not request sensitive permissions solely for monitoring unless the event is necessary, permitted by platform policy, and approved by the organization.

## Application Exit and Uptime

Android does not provide a universal callback when an application is closed. The process can be terminated without allowing the application to execute final code.

GermainUX can complete application-uptime monitoring in the following situations:

* An unhandled exception is captured before the process terminates.
* The application explicitly reports its controlled exit.
* Another supported lifecycle end condition is observed.

Normal background transitions should not be reported as application exits.

## Report an Application-Controlled Exit

If the application deliberately ends its own workflow or process, call `collectApplicationExit()` before the termination logic.

### Java

```text theme={null}
boolean calledFromForeground = true;

GermainAPM.collectApplicationExit(
    calledFromForeground
);

// Application-controlled exit logic
```

### Kotlin

```text theme={null}
val calledFromForeground = true

GermainAPM.collectApplicationExit(
    calledFromForeground
)

// Application-controlled exit logic
```

Set the parameter to:

| Value | Meaning |
| - | - |
| `true` | when the application is in the foreground. |
| `false` | when it is in the background. |

Call this method only for an actual application-controlled exit. Do not call it for ordinary activity destruction, configuration changes, navigation, or background transitions.

Android applications generally should not terminate their own processes during normal operation.

## Removal from Recent Applications

Swiping an application from the recent-applications screen is not a reliable application-termination signal on modern Android versions.

Behavior varies by:

* Android release
* Device manufacturer
* Task and service configuration
* Background-execution policy
* Application state

Do not depend on recent-task removal to calculate complete application uptime or guarantee delivery of a final event. The legacy listener intended for older Android releases should not be presented as a supported solution for applications targeting current Android SDK versions.

## Add Custom Business Events

System and lifecycle events describe application context. Add custom events or transactions for activities that have business meaning, such as:

* Login completed
* Search performed
* Form submitted
* Record created
* Synchronization started or failed
* Order submitted
* Payment completed
* Workflow abandoned

Use transactions instead of events when duration, completion, or failure must be measured.

Keep event names stable and store dynamic information in approved attributes rather than generating a unique event name for every occurrence.

## Analyze Events

Use GermainUX dashboards to analyze events by:

* Application
* Environment
* Application version
* Android version
* Device model
* User session

> [accordion] Show all 11
>
> * Screen or fragment
> * Business process
> * Network or power state
> * Error or crash
> * Timestamp and trend

Event context can help determine whether failures are concentrated around network changes, memory pressure, background transitions, particular devices, or application releases.

## Alerts

Configure alerts only for events that require action, such as:

* Repeated low-memory notifications
* Unexpected application restarts
* Increased launch failures
* Critical application event missing
* Business event failure
* System event correlated with widespread application failures

Most lifecycle and system events are informational and should be analyzed rather than individually alerted on.

## Privacy and Permissions

Before enabling system-event monitoring:

* Review each requested Android permission.
* Collect only events needed for the monitoring objective.
* Avoid call, message, contact, and other sensitive device telemetry.
* Do not capture values containing personal information.
* Use anonymous or pseudonymous user identifiers.
* Review Google Play and organizational privacy requirements.
* Document monitoring behavior in the application’s privacy disclosures where required.
* Test data anonymization and exclusion rules.

Android permission approval does not automatically make data collection appropriate. Apply the organization’s privacy and security requirements independently.

## Validation

Test event monitoring on supported Android versions and representative devices:

**1. Launch the application**

**2. Move it between foreground and background**

**3. Trigger an approved configuration change**

**4. Connect and disconnect the device from power**

**5. Change network state where safe**

**6. Simulate a low-memory callback in a test environment**

**7. Execute an application-controlled exit if the application supports one**

**8. Confirm that each event reaches GermainUX**

**9. Verify application, session, device, and version context**

**10. Confirm that restricted or unnecessary data is not collected**

Do not validate production behavior based on a single emulator or Android version.

## Troubleshooting

### System events are missing

Verify that:

* System-event monitoring is enabled.
* The installed GermainUX library supports the event.
* Android permits the event to be delivered.
* Required permissions are declared and granted.
* Background-execution restrictions do not prevent collection.
* The application remained active long enough to distribute telemetry.
* The device can reach the GermainUX ingestion endpoint.

### Application uptime has no final value

The application process may have been terminated without a final callback. This is expected behavior on Android and cannot always be prevented.

Use session, foreground, and background telemetry for usage analysis when no reliable application-exit event is available.

### Duplicate lifecycle events appear

Confirm that:

* GermainUX initializes only once per process.
* Multiple application processes are not being combined incorrectly.
* Custom events do not duplicate automatic lifecycle events.
* The same event is not submitted by multiple libraries or application components.

### An event works on one device but not another

Compare:

* Android version
* Device manufacturer
* Application permissions
* Battery-optimization settings
* Background restrictions
* Application state
* Installed library version

## Get Help

> [card] [Contact GermainUX Support](https://docs.germainux.com/main/support.md)
>
> The GermainUX team helps you get up and running faster, empower your team, turn data into actionable insights, and optimize performance to deliver measurable business outcomes.

> [card] Can't find what you need?
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.