Android SDK Installation

Article
11/22/2024

SDK Initialization

Important

The Clarity Android SDK collects sessions from Android API levels within the supported range specified at Platform/Framework Support Matrix. Applications that are with API levels 19-28 inclusive build successfully, but they cannot send data 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:3.+'
}

Step 2

Add the following code to your startup activity only:

Kotlin
Java

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

override fun onCreate(savedInstanceState: Bundle?) {
   ...
   val config = ClarityConfig(
       projectId = "<ProjectId>",
       logLevel = LogLevel.Verbose // default is None
   )

   Clarity.initialize(applicationContext, config)
   ...
}

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

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
   ...
   ClarityConfig config = new ClarityConfig("<ProjectId>");
   
   config.setLogLevel(LogLevel.Verbose); // default is None

   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:

Your device/emulator is connected to the internet.
Your device/emulator Android version is within the supported range specified at Platform/Framework Support Matrix.
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 complete sessions to appear in your Clarity project on the Clarity website. However, in-progress sessions can still be viewed in real time. See Clarity Recordings in Real Time.

Configuration options

class ClarityConfig(
   val projectId: String,
   val userId: String? = null, // DEPRECATED
   val logLevel: LogLevel = LogLevel.None
)

Project ID (`projectId`)

The unique identifier assigned to your Clarity project. You can find it on the Settings page of Clarity dashboard. This ID is essential for routing data to the correct Clarity project.

User ID (`userId`)

The unique identifier associated with the application user. This ID persists across multiple sessions on the same device.

Deprecated: This field is deprecated and would be removed in a future major version. Use setCustomUserId instead.
If userId isn't provided, a random one is generated automatically.
Must be a base-36 string smaller than 1Z141Z4.
If an invalid userId is supplied:
- If customUserId isn't specified: userId acts as the customUserId, and a new random userId is assigned.
- If customUserId isn't specified: invalid userId is ignored.

Note

For greater flexibility in user identification, use the setCustomUserId API. Ensure that the customUserId length is between 1 and 255 characters.

Log Level (`logLevel`)

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

Allowed log levels are:

Verbose
Debug
Info
Warning
Error
None

Application framework (`applicationFramework`)

Signals to the SDK which framework is being used to develop the current application. This parameter is internal to the SDK and shouldn't be set manually.

Note

For Clarity versions 3.0.0 and above, the following configuration options are no longer configurable from code and can now be adjusted dynamically from the Clarity dashboard:

Allow Metered Network Usage (allowMeteredNetworkUsage): Allows uploading session data to the servers on device's metered networks. By default, the SDK only uploads sessions on unmetered networks.
Enable WebView Capture (enableWebViewCapture): Allows Clarity to capture the web views DOM content for recording and heatmap reconstruction.
Disable on Low-End Devices (disableOnLowEndDevices): When enabled, Clarity doesn't capture any data for the low-end devices.
Allow or disallow activities (allowedActivities, disallowedActivities): Include or exclude some activities from being recorded by Clarity. By default, all activities are included.
Network limit (maximumDailyNetworkUsageInMB): Daily limit of wifi/cellular data per device that could be used to upload session recordings.
Allowed domains (allowedDomains): The accepted domains for Clarity to track and capture DOM content. This has now been updated to Allowed URLs, which can be configured from the dashboard to specify the accepted URLs. By default, all URLs are included.

API

initialize()

Initializes Clarity to start capturing the current session data.

initialize(Context context, ClarityConfig config)

It's a must to be called in the startup activity onCreate().

initialize(Activity activity, ClarityConfig config)

Use this function if you want to initialize clarity later, i.e. later stages of an activity's lifecycle, like when the activity has resumed.

Parameters

config ClarityConfig

Configuration of Clarity that tunes the SDK behavior (for example, which project to send to, which log level to use, and so on).

Returns

Boolean

true if Clarity initialization is possible; otherwise false.

Remarks

The initialization function is asynchronous, meaning it returns before Clarity is fully initialized.
For actions that require Clarity to be fully initialized, it's recommended to use the setOnSessionStartedCallback function.
This function should only be called on the main thread.

Pause()

pause()

Pauses the Clarity session capturing until a call to the resume function is made.

Returns

Boolean

true if Clarity was successfully paused; otherwise false.

Resume()

resume()

Resumes the Clarity session capturing only if it was previously paused by a call to the pause function.

Returns

Boolean

true if Clarity was successfully resumed; otherwise false.

Remarks

This function should only be called on the main thread.

isPaused()

isPaused()

Returns

Boolean

true if Clarity session capturing is currently in the paused state based on an earlier call to the pause function; otherwise false.

startNewSession()

startNewSession(Function1<String, Unit> callback)

Forces Clarity to start a new session asynchronously.

Parameters

callback Function1<String, Unit>

A callback that is invoked when the new session starts. The callback receives the new session ID as a string parameter.

Returns

Boolean

true if a new session can start asynchronously; otherwise false.

Remarks

This function is asynchronous, meaning it returns before the new session is started.
Use the callback parameter to execute logic that needs to run after the new session begins.
Events that occur before invoking the callback are associated with the previous session.
To ensure proper association of custom tags, user ID, or session ID with the new session, set them within the callback.
This function should only be called on the main thread.

maskView()

maskView(View view)

Masks a specific View to prevent Clarity from capturing its content (text or images). Masked content is replaced with placeholders.

Parameters

view View

The View instance to mask its content.

Returns

Boolean

true if the view was added to the masked views; otherwise false.

Remarks

This function should only be called on the main thread.

unmaskView()

unmaskView(View view)

Unmasks a specific View to allow Clarity to capture its content, even if it's a child of a masked view or within a masked screen.

Parameters

view View

The view instance to unmask.

Returns

Boolean

true if the view was added to the unmasked views; otherwise false.

Remarks

This function should only be called on the main thread.

setCustomUserId()

setCustomUserId(String customUserId)

Sets a custom user ID for the current session. This ID can be used to filter sessions on the Clarity dashboard.

Parameters

customUserId String

The custom user ID to associate with the current session. The value must be a nonempty string with a maximum length of 255 characters and can't consist only of whitespace.

Returns

Boolean

true if the custom user ID was set successfully; otherwise false.

Remarks

To ensure that the custom user ID is associated with the correct session, it's recommended to call this function within the callbacks of setOnSessionStartedCallback or startNewSession.
Unlike the userID, the customUserId value has fewer restrictions.
We recommend not to set any Personally Identifiable Information (PII) values inside this field.
This function should only be called on the main thread.

setCustomSessionId()

setCustomSessionId(String customSessionId)

Sets a custom session ID for the current session. This ID can be used to filter sessions on the Clarity dashboard.

Parameters

customSessionId String

The custom session ID to associate with the current session. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace.

Returns

Boolean

true if the custom session ID was set successfully; otherwise false.

Remarks

To ensure that the custom session ID is associated with the correct session, it's recommended to call this function within the callbacks of setOnSessionStartedCallback or startNewSession.
This function should only be called on the main thread.

getCurrentSessionId()

getCurrentSessionId()

A string representing the ID of the currently active Clarity session if a session has already started; otherwise null.

Returns

String

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

Remarks

Deprecated: This API is deprecated and would be removed in a future major version. Use getcurrentsessionurl instead.
The session ID can be used to correlate Clarity sessions with other telemetry services.
Initially, this function might return null until a Clarity session begins.
To ensure a valid session ID, use this method within the callbacks of setOnSessionStartedCallback or startNewSession.
This function should only be called on the main thread.

getCurrentSessionUrl()

getCurrentSessionUrl()

Returns the URL of the current Clarity session recording on the Clarity dashboard if a session has already started; otherwise null.

Returns

String

A string representing the URL of the current Clarity session recording on the Clarity dashboard if a session has already started; otherwise null.

Remarks

Initially, this function might return null until a Clarity session begins.
To ensure a valid session URL, use this method within the callbacks of setOnSessionStartedCallback or startNewSession.
This function should only be called on the main thread.

setCustomTag()

setCustomTag(String key, String value)

Sets a custom tag for the current session. This tag can be used to filter sessions on the Clarity dashboard.

Parameters

key String

The key for the custom tag. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace.

value String

The value for the custom tag. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace.

Returns

Boolean

true if the custom tag was set successfully; otherwise false.

Remarks

<<<<<<< HEAD

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. =======
To ensure that the custom tag is associated with the correct session, it's recommended to call this function within the callbacks of setOnSessionStartedCallback or startNewSession.
This function should only be called on the main thread.

sendCustomEvent()

sendCustomEvent(String value)

Sends a custom event to the current Clarity session. These custom events can be used to track specific user interactions or actions that Clarity's built-in event tracking doesn't automatically capture.

Parameters

value String

The name of the custom event. The value must be a nonempty string, with a maximum length of 254 characters, and can't consist only of whitespace.

Returns

Boolean

true if the custom event was sent successfully; otherwise false.

Remarks

This API can be called multiple times per page to track various user actions.
Each custom event is logged individually and can be filtered, viewed, and analyzed on the Clarity dashboard.

main

setCurrentScreenName()

setCurrentScreenName(String screenName)

This function allows you to provide a custom screen name tag that's added as a suffix to the base screen name. The base name is automatically generated based on the current activity name.

Parameters

screenName String

The desired screen name tag. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace nor contain / character. Set to null to reset.

Returns

Boolean

true if the specified screen name tag was set successfully; otherwise false.

Examples

If the current activity is MainActivity, and setCurrentScreenName("Home") is called, the screen name is tracked as "MainActivity/Home".
If setCurrentScreenName(null) is called on the same activity, the screen name is tracked as "MainActivity".

Remarks

Clarity starts a new page whenever either the base screen name (generated from the activity) or the custom name tag changes.
To mask or disallow a screen, specify the base screen name without the custom tag suffix. For example, to mask the activity in the previous example, mask the "MainActivity" screen instead of "Main Tab Bar/Settings".
The screen name tag is set globally and persists across all subsequent activities until explicitly reset.
For accurate tracking, call this function immediately after navigating to the new screen:
- If there are activities, you can call it inside Activity.onResume function.
- While using androidx.navigation, you can call it inside OnDestinationChangedListener.
This function should only be called on the main thread.

setOnSessionStartedCallback()

setOnSessionStartedCallback(Function1<String, Unit> callback)

Sets a callback function that's invoked whenever a new Clarity session starts or an existing session is resumed at app startup.

Parameters

callback Function1<String, Unit>

The callback to be invoked whenever a Clarity session starts. The callback receives the new or resumed session ID as a string parameter.

Returns

Boolean

true if the callback was set successfully; otherwise false.

Remarks

If the callback is set after a session has already started, the callback is invoked right away with the current session ID.
The specified 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

Data capture rules

Jetpack Compose Support

Installation for iOS

Explore more

Heatmaps overview

Recordings overview

Insights overview

Visit Clarity

Demo

Sign in

Blog

Share via

Android SDK Installation

SDK Initialization

Step 1

Step 2

Step 3

Configuration options

Project ID (projectId)

User ID (userId)

Log Level (logLevel)

Application framework (applicationFramework)

API

initialize()

Parameters

Returns

Remarks

Pause()

Returns

Resume()

Returns

Remarks

isPaused()

Returns

startNewSession()

Parameters

Returns

Remarks

maskView()

Parameters

Returns

Remarks

unmaskView()

Parameters

Returns

Remarks

setCustomUserId()

Parameters

Returns

Remarks

setCustomSessionId()

Parameters

Returns

Remarks

getCurrentSessionId()

Returns

Remarks

getCurrentSessionUrl()

Returns

Remarks

setCustomTag()

Parameters

Returns

Remarks

sendCustomEvent()

Parameters

Returns

Remarks

setCurrentScreenName()

Parameters

Returns

Examples

Remarks

setOnSessionStartedCallback()

Parameters

Returns

Remarks

Implementation notes

FAQ

Next steps

Explore more

Visit Clarity

Additional resources

Project ID (`projectId`)

User ID (`userId`)

Log Level (`logLevel`)

Application framework (`applicationFramework`)