Mobile RUM - Android SDK

1 Create a RUM application#

2 Install the Android SDK#

1dependencies {
2    implementation 'io.github.middleware-labs:android-sdk:3.0.2'
3}

3 Initialize Middleware#

1import android.app.Application;
2
3import io.middleware.android.sdk.Middleware;
4
5public class MyApplication extends Application {
6
7    @Override
8    public void onCreate() {
9        super.onCreate();
10
11        Middleware.builder()
12            .setTarget("https://<MW_UID>.middleware.io")
13            .setRumAccessToken("<MW_RUM_ACCESS_TOKEN>")
14            .setServiceName("my-android-app")
15            .setProjectName("Android-App")
16            .setDeploymentEnvironment("PROD")
17            .build(this);
18    }
19}

1<application
2    android:name=".MyApplication"
3    ... >
4</application>

1import okhttp3.Call;
2import okhttp3.OkHttpClient;
3
4import io.middleware.android.sdk.Middleware;
5
6Call.Factory httpClient = Middleware.getInstance()
7    .createRumOkHttpCallFactory(new OkHttpClient());

1Retrofit retrofit = new Retrofit.Builder()
2    .baseUrl("https://api.example.com/")
3    .callFactory(httpClient)
4    .build();

Optional configuration#

Enable or disable monitoring features#

Crash reporting, ANR detection, network change monitoring, and slow rendering detection are enabled by default.

You can disable individual features during initialization:

1Middleware.builder()
2    .setTarget("https://<MW_UID>.middleware.io")
3    .setRumAccessToken("<MW_RUM_ACCESS_TOKEN>")
4    .setServiceName("my-android-app")
5    .setProjectName("Android-App")
6    .disableCrashReporting()
7    .disableAnrDetection()
8    .disableNetworkMonitor()
9    .disableSlowRenderingDetection()
10    .build(this);

Only include the disable...() methods for features you do not want to collect.

Configure Session Replay#

Session Replay is enabled by default and starts when the SDK initializes. No additional lifecycle hooks are required with SDK 3.x.

You can configure recording frequency, quality, and privacy settings:

1RecordingOptions.Builder recordingOptions =
2    new RecordingOptions.Builder();
3
4recordingOptions.setFrequency(RecordingFrequency.STANDARD);
5recordingOptions.setQuality(RecordingQuality.STANDARD);
6recordingOptions.setMaskAllTextInputs(true);
7recordingOptions.setMaskAllImages(true);
8
9Middleware.builder()
10    .setTarget("https://<MW_UID>.middleware.io")
11    .setRumAccessToken("<MW_RUM_ACCESS_TOKEN>")
12    .setServiceName("my-android-app")
13    .setProjectName("Android-App")
14    .setRecordingOptions(recordingOptions.build())
15    .build(this);

Recording frequency and quality support LOW, STANDARD, and HIGH.

Disable Session Replay#

To collect RUM telemetry without recording user sessions, add:

1.disableSessionRecording()

Session recording limits#

• Maximum duration: 4 hours per session.
• Idle timeout: 15 minutes.
• Default: Session Replay enabled.

A new session starts when the user resumes activity after the idle timeout.

Mask sensitive information#

The SDK masks text inputs and images by default. You can also exclude specific views from Session Replay.

Mask an Android view#

1final Middleware middleware = Middleware.getInstance();
2
3TextView sensitiveView = findViewById(R.id.some_text_view);
4
5middleware.addSanitizedElement(sensitiveView);

Mask a view using XML#

Add the mw-no-capture tag:

1<ImageView
2    android:id="@+id/card_scan_preview"
3    android:tag="mw-no-capture" />

You can also use:

• mw-no-capture — Always mask the view.
• mw-no-mask — Exclude the view from masking.

Mask Jetpack Compose elements#

For Jetpack Compose applications, use the Session Replay modifiers:

1Text(
2    text = cardNumber,
3    modifier = Modifier.mwSessionReplayMask()
4)

Privacy recommendation: Review payment screens, authentication forms, OTP fields, and other sensitive UI elements before enabling Session Replay in production.

Configure distributed tracing#

Distributed tracing connects Android network requests with backend APM traces.

When enabled, the SDK injects W3C traceparent headers into requests sent through the instrumented OkHttp client.

Prerequisites#

• Your Android application must use the Middleware-wrapped OkHttp Call.Factory.
• Backend services must have APM instrumentation enabled.
• Backend services must support W3C Trace Context propagation.

1Middleware.builder()
2    .setTarget("https://<MW_UID>.middleware.io")
3    .setRumAccessToken("<MW_RUM_ACCESS_TOKEN>")
4    .setServiceName("my-android-app")
5    .setTracePropagationTargets(Arrays.asList(
6        Pattern.compile("api\\.example\\.com"),
7        Pattern.compile("checkout\\.example\\.com")
8    ))
9    .build(this);

Add custom events, errors, and logs#

Custom events#

Record application-specific interactions:

1Middleware.getInstance().addEvent(
2    "Checkout button clicked",
3    BUTTON_ATTRIBUTES
4);

Use custom events to track actions such as checkout, onboarding, or subscription changes.

Custom workflows#

Track a multi-step user flow:

1Span loginWorkflow = Middleware.getInstance()
2    .startWorkflow("User Login Flow");
3
4// Execute the workflow
5
6loginWorkflow.end();

Report handled exceptions#

Crashes are captured automatically. For exceptions handled by your application, report them manually:

1Middleware.getInstance().addException(
2    new RuntimeException("Payment request failed"),
3    Attributes.empty()
4);

Add custom logs#

Use the Middleware SDK to record application logs:

1Middleware logger = Middleware.getInstance();
2
3logger.d("Checkout", "Debug message");
4logger.i("Checkout", "Payment initiated");
5logger.w("Checkout", "Payment response delayed");
6logger.e("Checkout", "Payment failed");

These logs provide additional context when investigating user sessions and application errors.

Add custom attributes#

Use global attributes to associate telemetry with application releases, environments, or user groups.

For example:

1Middleware.builder()
2    .setTarget("https://<MW_UID>.middleware.io")
3    .setRumAccessToken("<MW_RUM_ACCESS_TOKEN>")
4    .setServiceName("my-android-app")
5    .setGlobalAttributes(
6        Attributes.builder()
7            .put("app.version", BuildConfig.VERSION_NAME)
8            .put("user.type", "premium")
9            .build()
10    )
11    .build(this);

Prefer stable, non-sensitive attributes that are useful for filtering and grouping sessions.

Set a custom screen name#

By default, the SDK identifies screens using their Activity class names.

To override the name:

1Middleware.getInstance().setScreenName("checkout");

This is useful when multiple screens share the same Activity or when using custom navigation.

Configuration reference#

Troubleshooting#

No RUM data appears#

If your application is running but telemetry does not appear:

• Verify that the SDK dependency is installed.
• Confirm that Middleware.builder().build(this) is called from Application.onCreate().
• Check that the RUM access token and target URL are correct.
• Verify that the device can connect to Middleware over HTTPS.
• Review Android Logcat for initialization or export errors.

HTTP requests are missing#

If sessions appear but network requests do not:

• Confirm that your application uses OkHttp.
• Verify that requests pass through createRumOkHttpCallFactory().
• For Retrofit, check that .callFactory(httpClient) uses the wrapped factory.
• Make sure other networking clients are not bypassing the instrumented client.

Backend traces are not correlated#

If network requests appear but backend traces are missing:

• Check the network event for http.request.header.traceparent.
• Verify that backend APM instrumentation is enabled.
• Confirm that your backend accepts W3C Trace Context.
• Check setTracePropagationTargets() for incorrect host patterns.

Session Replay is missing#

If sessions appear without recordings:

• Verify that disableSessionRecording() is not enabled.
• Check the application's consent and privacy configuration.
• Confirm that recording initialization completes successfully.
• Review SDK logs for recording or upload errors.

App crashes or ANRs are not reported#

• Verify that crash reporting and ANR detection have not been disabled.
• Confirm that the SDK initializes early in the application lifecycle.
• Check that the device has network connectivity.
• For ANRs, verify that the main thread is blocked long enough to trigger detection.

Slow or frozen frames are not reported#

• Confirm that slow rendering detection is enabled.
• Verify that the application generates UI activity.
• Check the configured detection interval.

Slow frames are reported above 16 ms, and frozen frames above 700 ms.

Network requests fail on Android 9+#

Android 9 (API 28) and later block cleartext HTTP traffic by default.

• Use HTTPS for your backend APIs and Middleware ingestion endpoint.
• For local development using HTTP, configure a scoped Android Network Security Configuration for the required development hosts.

If the issue persists, contact Middleware Support at [email protected].