Share via

Android SDK Installation

  • Article

SDK Initialization

Important

  • Android SDK supports API levels 29-34 inclusive. Applications that with API levels 19-28 inclusive will build successfully but data will not be sent to Clarity.
  • If your app uses Jetpack Compose, use clarity-compose package. For more information, see Jetpack compose support.

Install the Clarity SDK in order to track how users interact with your app. The Clarity Android SDK is available on a MavenCentral. It can take up to 2 hours to start seeing data.

Step 1

Add mavenCentral() to your project repositories. Add the dependency to your module build.gradle script.

Note: latest version could be found here.

repositories {
   mavenCentral()
}

dependencies {
   implementation 'com.microsoft.clarity:clarity:2.+'
}

Step 2

Add the following code to your startup activity only:

import com.microsoft.clarity.Clarity
import com.microsoft.clarity.ClarityConfig

override fun onCreate(savedInstanceState: Bundle?) {
   ...
   val config = ClarityConfig("<ProjectId>")
   Clarity.initialize(applicationContext, config)
   ...
}

Or if you're using Java

import com.microsoft.clarity.Clarity;
import com.microsoft.clarity.ClarityConfig;
import com.microsoft.clarity.models.ApplicationFramework;
import com.microsoft.clarity.models.LogLevel;

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
   ...
   ClarityConfig config = new ClarityConfig(
    "<ProjectId>",
    null, // Default user id
    LogLevel.None,
    false, // Disallow metered network usage
    true, // Enable web view capturing
    Collections.singletonList("*"), // Allowed domains
    ApplicationFramework.Native,
    Collections.emptyList(), // Allowed activities
    Collections.emptyList(), // Disallowed activities (ignore activities)
    false, // Disable on low-end devices
    null // Maximum allowed daily network usage in MB (null = unlimited)
   );

   Clarity.initialize(getApplicationContext(), config);
   ...
}

Note

You need to invoke this function only once during your startup activity. If you have multiple startup activities, you can either call it within a custom application class or duplicate the call in each startup activity.

If you want to late initialize Clarity after the activity onCreate function is called, you can use a different initialization function that takes the current activity as a parameter:

Clarity.initialize(currentActivity, config)

Note

  • This function has to be called on the main thread.
  • If you use a custom WorkManager initializer, Clarity initialization must take place after the WorkManager initializer. Otherwise, Clarity won't function properly.

Step 3

Once you integrated Clarity with your application, ensure the following if you want to test it on a device or an emulator:

  1. Your device/emulator is connected to the internet.
  2. Your device/emulator Android version is within the supported range 29-34 inclusive.
  3. Your first run might require setting the log level to Verbose to obtain the Clarity logs. These logs could help identifying any initialization errors, if present.

Allow approximately 2 hours for the data to appear in your Clarity project on the Clarity website.

Configuration options

class ClarityConfig(
   val projectId: String,
   val userId: String? = null,
   val logLevel: LogLevel = LogLevel.None,
   val allowMeteredNetworkUsage: Boolean = false,
   val enableWebViewCapture: Boolean = true,
   val allowedDomains: String? = listOf("*"),
   val allowedActivities: List<String> = listOf(),
   val disallowedActivities: List<String> = listOf(),
   val disableOnLowEndDevices: Boolean = false,
   val maximumDailyNetworkUsageInMB: Long? = null
)

Project ID

Distinct project ID from Clarity. You can find it in the Settings Page.

User ID

The current user's identifier. The user ID remains persistent across sessions on the same device. If there's no user ID, a randomly generated one is used.

  • User ID must be a base-36 string and smaller than the upper limit of 1Z141Z4.
  • If an invalid user ID is provided, a randomly generated ID, and the invalid user ID is added as the CustomUserID parameter.
  • If an invalid user ID is provided and the user sets the CustomUserID, the invalid user ID is ignored.

Note

CustomUserID has no format restrictions.

Log Level

The level of logging to show in the device's Logcat stream. By default, the SDK logs nothing.

Allow Metered Network Usage

Allows uploading session data to the servers on device metered network. By default, the SDK starts uploading sessions on unmetered networks only.

Enable WebView Capture

Allows Clarity to capture the web views DOM content for recording and heatmap reconstruction.

Allowed Domains

The accepted domains for Clarity to track and capture their DOM content. If it contains * as an element, all domains visited in a session are captured.

Allowed Activities

If disallowed activities list is empty, Clarity only captures activities defined in this list. If both lists are empty, then Clarity captures all screens.

Disallowed Activities

The list of activities to prevent Clarity from capturing them entirely. If this list isn't empty, then the allowed activities list is disregarded.

Disable on Low-End Devices

When enabled, Clarity doesn't capture any data for the low-end devices.

Maximum daily network usage

Once configured, Clarity only sends data to a specified daily limit (in megabytes). Clarity activates lean mode for future sessions within the same day once the limit is reached. In lean mode, only user interactions with the application are recorded, and session playback is dropped. Setting this option to null allows Clarity to transmit all captured data. This limit applies to both metered and unmetered networks.

API

Pause

pause()

Returns

Boolean

Clarity was successfully paused.

Resume

resume()

Returns

Boolean

Clarity was successfully resumed.

isPaused

isPaused()

Returns

Boolean

Clarity capturing is paused.

maskView

maskView(View view)

Parameters

view View

The view instance to mask.

Returns

Boolean

The view was added to the masked views.

unmaskView

unmaskView(View view)

Parameters

view View

The view instance to unmask.

Returns

Boolean

The view was added to the unmasked views.

setCustomUserId

setCustomUserId(String customUserId)

Parameters

customUserId String

The custom user ID to associate with this session. This value can't be null or empty, or consists only of whitespace.

Returns

Boolean

The custom user ID was successfully registered.

Remarks

  • The custom user ID value can be used to filter and search sessions on the Clarity dashboard.
  • Unlike the userID, the custom userID value has fewer restrictions.
  • We recommend not to set any PII values inside this field.

setCustomSessionId

setCustomSessionId(String customSessionId)

Parameters

customSessionId String

The custom session ID to associate with this session. This value can't be null or empty, or consists only of whitespace.

Returns

Boolean

The custom session ID was successfully registered.

Remarks

The custom session ID value can be used to filter and search sessions on the Clarity dashboard.

getCurrentSessionId

getCurrentSessionId()

Returns

String

The current active session ID. If there's no active session, it returns null.

Remarks

  • The retrieved ID can be used to correlate Clarity sessions with other telemetry services you might be using.
  • Initially, this function might return null until the Clarity session begins.

getCurrentSessionUrl()

getCurrentSessionUrl()

Returns

String

The current active session URL to play the recording. If there's no active session, it returns null.

Remarks

Initially, this function might return null until the Clarity session begins.

setCustomTag

setCustomTag(String key, String value)

Sets a custom tag for the current session.

Parameters

key String

The custom tag key. This value can't be null or empty, or consists only of whitespace.

value String

The custom tag value. This value can't be null or empty, or consists only of whitespace.

Returns

Boolean

The custom tag was successfully set.

Remarks

  • The custom tag can be used to filter and search for sessions on the Clarity dashboard.
  • We recommend not to set any PII values inside this field.

setCurrentScreenName()

setCurrentScreenName(String name)

Sets the name of the currently active screen. Only allowed for React Native apps.

Parameters

name String

The name of current screen. This value can't be empty, or consists only of whitespace. The value null can be used to unset the screen name.

Returns

Bool

true if the screen name was successfully set/unset; otherwise false.

Remarks

This function should be called on the main thread only.

setOnNewSessionStartedCallback()

setOnNewSessionStartedCallback(Function1<String, Unit> callback)

Sets a callback that triggers whenever a new session of Clarity starts. The callback should take the session ID as a string.

Parameters

callback Function1<String, Unit>

The callback to be called each time a new session starts.

Returns

Bool

true if the callback was successfully set; otherwise false.

Remarks

  • If this function was called to set a callback after a session already started, the callback triggers immediately with the existing session ID.
  • The callback is guaranteed to run on the main thread.

Implementation Notes

  • In case you'd like to associate a name with your fragment for filtering on the Clarity dashboard, assign a certain tag (R.id.clarity_fragment_tag) to the topmost/root view within your fragment view tree:

    view.setTag(R.id.clarity_fragment_tag, "SettingFragment")

  • The invocation of View masking APIs should occur in the onCreate() of the activity that hosts the targeted view.

Important

Remember to update your terms & conditions (if any) for your app users after integrating Clarity with your mobile app.

FAQ

For more answers, refer to FAQ.

Next steps

IP blocking

Jetpack Compose Support

Installation for iOS

Explore more

Heatmaps overview

Recordings overview

Insights overview

Visit Clarity

Demo

Sign in

Blog