Android SDK Installation

SDK Initialization

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:

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);
   ...
}

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)

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 specified at Platform/Framework Support Matrix.
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 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.

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.

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

• 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.

setCurrentScreenName()

setCurrentScreenName(String screenName)

This function allows you to provide a custom screen name that replaces the default screen name. The default name is automatically generated based on the current activity name.

Parameters

screenName String

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

Returns

Boolean

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

Examples

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

Remarks

• Clarity starts a new page whenever the screen name changes.
• To mask or disallow a screen, specify the activity name that is displayed as "Activity" custom tag of the page visit on the Clarity dashboard's recordings, rather than the custom screen name. For example, to mask the activity in the previous example, mask the "MainActivity" screen instead of "Settings".
• The custom screen name 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.

FAQ

For more answers, refer to FAQ.

Visit Clarity