Android RUM Agent – Split Help Center

This guide provides detailed information about Split's Real User Monitoring (RUM) Agent for Android.

Split's Android RUM Agent collects events about your users' experience when they use your application and sends this information to Split services. This allows you to measure and analyze the impact of feature flag changes on performance metrics.

Language Support

Split's Android RUM Agent is designed for Android applications written in Java or Kotlin and is compatible with Android SDK versions 15 and later (4.0.3 Ice Cream Sandwich).

Initialization

Set up Split's RUM Agent in your code with the following three steps:

1. Import the Agent into your project

Import the Agent into your project with the following line:

implementation 'io.split.client:android-rum-agent:0.1.0'

implementation("io.split.client:android-rum-agent:0.1.0")

2. Setup the Agent

To allow the Agent to send information to Split services, specify the SDK through your app's AndroidManifest.xml file, as a meta-data tag inside the application tag.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

  <application ...>
    <activity ...>...</activity>

    <meta-data
      android:name="io.split.android.rum.SPLIT_SDK_KEY"
      android:value="YOUR_SDK_KEY" />

  </application>
</manifest>

Alternatively, you can call the setup method on the SplitRumAgent object. This value will override the one specified through the AndroidManifest.xml.

SplitRumAgent.setup("YOUR_SDK_KEY");

SplitRumAgent.setup("YOUR_SDK_KEY")

3. Add an Identity

While the Agent will work without having an Identity, events won't be sent to Split services until at least one is set.

Identity objects consist of a key and a traffic type. You can only pass values that match the names of traffic types already defined in the Split Management Console.

The RUM Agent provides methods to manage Identities, as shown in the table below.

// add one Identity
SplitRumAgent.addIdentity(new Identity("my_user", "user"));

// add multiple Identities
SplitRumAgent.addIdentities(
  new Identity("my_user", "user"),
  new Identity("my_account", "account")
);

// remove one Identity
SplitRumAgent.removeIdentity(new Identity("my_user", "user"));

// remove all Identities
SplitRumAgent.removeIdentities();

// add one Identity
SplitRumAgent.addIdentity(Identity("my_user", "user"))

// add multiple Identities
SplitRumAgent.addIdentities(
  Identity("my_user", "user"),
  Identity("my_account", "account")
)

// remove one Identity
SplitRumAgent.removeIdentity(Identity("my_user", "user"))

// remove all Identities
SplitRumAgent.removeIdentities()

Configuration

Split's Android RUM Agent can be configured to change its default behavior. The following options are available:

Log Level: level of logging. Valid values are DEBUG, INFO, WARNING and ERROR.
Prefix: Optional prefix to append to the eventTypeId of the events sent to Split. For example, if you set the prefix to 'my-app', the event type 'error' will be sent as 'my-app.error'.

These options can be configured using the AndroidManifest.xml or programmatically. Values specified programmatically will override values set through the AndroidManifest.xml. Both methods are demonstrated below.

Configuration using the manifest file:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

  <application ...>
    <activity ...>...</activity>

    <meta-data
      android:name="io.split.android.rum.SPLIT_SDK_KEY"
      android:value="YOUR_SDK_KEY" />

    <!-- Configuration -->
    <meta-data
      android:name="io.split.android.rum.LOG_LEVEL"
      android:value="DEBUG" />

    <meta-data
      android:name="io.split.android.rum.PREFIX"
      android:value="pre" />

  </application>
</manifest>

Configuration specified programatically:

SplitRumConfiguration config = new SplitRumConfiguration.Builder()
  .setPrefix("pre")
  .setLogLevel(LogLevel.DEBUG)
  .build();

SplitRumAgent.setup("YOUR_SDK_KEY", config);

val config = SplitRumConfiguration.Builder()
  .setPrefix("pre")
  .setLogLevel(LogLevel.DEBUG)
  .build()

  SplitRumAgent.setup("YOUR_SDK_KEY", config)

Events

Split's Android RUM Agent collects a number of events by default.

Default events

Event type ID	Description	Has value?	Has properties?
crash	Any unhandled exception that causes the application to crash.	No	`{ message: string, is_fatal: boolean, trace: string }`
app_start	Time in milliseconds elapsed until app is launched	Yes	No
anr	Sent if an ANR (Application Not Responding) is detected.	No	No
device_info	Information provided by the OS about a device. This is sent the first time the Agent runs on the device.	No	`{ id: string, display: string, product: string, device: string, board: string, manufacturer: string, brand: string, model: string, hardware: string, base: string, incremental: string, sdkVersion: string, host: string, fingerprint: string, release: string, baseOs: string, socManufacturer: string, securityPatch: string, abis: string }`

Advanced use cases

Custom properties

Each event for the metrics described above automatically includes a session_id property that can be use to filter certain events when defining Split metrics for experimentation purposes. Learn more about metric definitions and how to define property filters

name	Description
session_id	ID of the session in which the event took place.

Custom properties can be also added to tracked event by using the various methods for managing them.

// add a single property
SplitRumAgent.setProperty("property_name", "property_value");

// add multiple properties
Map<String, Object> newProperties = new HashMap<>();
newProperties.put("property_name", "property_value");
newProperties.put("property_name_2", "property_value_2");
SplitRumAgent.setProperties(newProperties);

// get all properties
Map<String, Object> properties = SplitRumAgent.getProperties();

// remove a single property
SplitRumAgent.removeProperty("property_name_2");

// remove all properties
SplitRumAgent.removeProperties();

// add a single property
SplitRumAgent.setProperty("property_name", "property_value")

// add multiple properties
SplitRumAgent.setProperties(
  mapOf(
    "property_name" to "property_value",
    "property_name_2" to "property_value_2",
  )
)

// get all properties
val properties: Map<String, Object> = SplitRumAgent.getProperties()

// remove a single property
SplitRumAgent.removeProperty("property_name_2")

// remove all properties
SplitRumAgent.removeProperties()

Custom events

Custom events can be tracked using the following options:

the track method
the specialized trackError method
These methods are demonstrated below.

Using the track methods:

Map<String, Object> properties = new HashMap<>();
properties.put("property_name", "property_value");

// Track event
SplitRumAgent.track("event_type_id");

// Track event with value
SplitRumAgent.track("event_type_id", 100L);

// Track event with properties
SplitRumAgent.track("event_type_id", properties);

// Track event with value and properties
SplitRumAgent.track("event_type_id", 100L, properties);

// Track event
SplitRumAgent.track("event_type_id")

// Track event with value
SplitRumAgent.track("event_type_id", 100)

// Track event with properties
SplitRumAgent.track("event_type_id", mapOf("property_name" to "property_value"))

// Track event with value and properties
SplitRumAgent.track("event_type_id", 100, mapOf("property_name" to "property_value"))

Using the trackError method:

SplitRumAgent.trackError(new Throwable("my_error"));

SplitRumAgent.trackError(Throwable("my_error"))