Microsoft Clarity

https://learn.microsoft.com/en-us/clarity/
Admin
Microsoft Clarity is a behavioral analysis tool that helps you understand user experience through...
Tokens:170,399
Snippets:2,181
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install native dependencies for iOS

Source: https://learn.microsoft.com/en-us/clarity/mobile-sdk/react-native-sdk

Run this command in the ios directory to install native dependencies for iOS. Required for iOS support.

```bash
cd ios && pod install

```

--------------------------------

### Initialize Clarity with Clarity.initialize()

Source: https://learn.microsoft.com/en-us/clarity/mobile-sdk/flutter-sdk

Initializes Clarity to start capturing session data. The method signature shows it takes a BuildContext and ClarityConfig and returns a boolean indicating success. The example demonstrates calling it with a ClarityConfig containing a projectId. Must be called on the UI isolate with a valid BuildContext, typically in initState.

```dart
bool Clarity.initialize(BuildContext context, ClarityConfig clarityConfig)
```

```dart
import 'package:clarity_flutter/clarity_flutter.dart';

void _initializeClarity() {
  final config = ClarityConfig(
    projectId: "your_project_id"
  );
  
  Clarity.initialize(context, config);
}

```

--------------------------------

### Start the Clarity MCP server with npx

Source: https://learn.microsoft.com/en-us/clarity/third-party-integrations/clarity-mcp-server

Run this command to start the Clarity MCP server. The API token can be provided directly via the command line interface or as a tool parameter when invoking commands.

```bash
npx @microsoft/clarity-mcp-server --clarity_api_token=your-token-here

```

--------------------------------

### Install gatsby-plugin-clarity with npm

Source: https://learn.microsoft.com/en-us/clarity/third-party-integrations/gatsby

Run this command in the root of your Gatsby project to install the Clarity plugin using npm.

```bash
npm install gatsby-plugin-clarity
```

--------------------------------

### initialize(config:)

Source: https://learn.microsoft.com/en-us/clarity/mobile-sdk/ios-sdk

Initializes Clarity to start capturing the current session data. Returns true if initialization is possible, otherwise false.

```APIDOC
## initialize(config:)

### Description
Initializes Clarity to start capturing the current session data.

### Method
static func

### Signature
static func initialize(config: ClarityConfig) -> Bool

### Parameters
- **config** (ClarityConfig) - Required - Configuration of Clarity that tunes the SDK behavior (for example, which project to send to, which log level to use, and so on).

### Returns
- **Bool** - `true` if Clarity initialization is possible; otherwise `false`.

### Remarks
- The initialization function is asynchronous and 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.
```

--------------------------------

### getCurrentSessionId()

Source: https://learn.microsoft.com/en-us/clarity/mobile-sdk/android-sdk

Gets the current Clarity session ID, or null if no session has started. Deprecated; use getCurrentSessionUrl instead.

```APIDOC
## getCurrentSessionId()

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

### Method
N/A (Java SDK method)

### Endpoint
N/A (Java SDK method)

### Parameters
No parameters.

### 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.
```

--------------------------------

### initialize(Context context, ClarityConfig config)

Source: https://learn.microsoft.com/en-us/clarity/mobile-sdk/android-sdk

Initializes Clarity to start capturing the current session data. Must be called in the startup activity's onCreate().

```APIDOC
## [initialize] initialize(Context context, ClarityConfig config)

### Description
Initializes Clarity to start capturing the current session data. Must be called in the startup activity's onCreate().

### Method
initialize

### Signature
initialize(Context context, ClarityConfig config)

### Parameters
- **context** (Context) - Required - The application or activity context.
- **config** (ClarityConfig) - Required - 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.
```

```APIDOC
## [POST] /initialize

### Description
Initializes Clarity to start capturing the current session data. Must be called in the startup activity's onCreate().

### Method
POST

### Endpoint
/initialize

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **context** (Context) - Required - The application or activity context.
- **config** (ClarityConfig) - Required - Configuration of Clarity that tunes the SDK behavior (for example, which project to send to, which log level to use, and so on).

### Request Example
```json
{
  "context": "<Context>",
  "config": "<ClarityConfig>"
}
```

### Response
#### Success Response (200)
- **Boolean** - `true` if Clarity initialization is possible; otherwise `false`.

#### Response Example
```json
true
```

### Error Handling
- No explicit error responses are documented. The method returns a Boolean indicating success or failure.

## [POST] /pause

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

### Method
POST

### Endpoint
/pause

### Parameters
None

### Request Example
{}

### Response
#### Success Response (200)
- **Boolean** - `true` if Clarity was successfully paused; otherwise `false`.

#### Response Example
```json
true
```

## [POST] /resume

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

### Method
POST

### Endpoint
/resume

### Parameters
None

### Request Example
{}

### Response
#### Success Response (200)
- **Boolean** - `true` if Clarity was successfully resumed; otherwise `false`.

#### Response Example
```json
true
```

## [GET] /isPaused

### Description
Checks whether Clarity session capturing is currently paused.

### Method
GET

### Endpoint
/isPaused

### Parameters
None

### Response
#### Success Response (200)
- **Boolean** - `true` if Clarity session capturing is currently paused; otherwise `false`.

#### Response Example
```json
true
```

## [POST] /startNewSession

### Description
Forces Clarity to start a new session asynchronously.

### Method
POST

### Endpoint
/startNewSession

### Parameters
#### Request Body
- **callback** (Function1<String, Unit>) - Required - A callback invoked when the new session starts, receiving the new session ID as a string.

### Request Example
```java
Clarity.startNewSession(new Function1<String, Unit>() {
    @Override
    public Unit invoke(String sessionId) {
        // handle new session
        return Unit.INSTANCE;
    }
});
```

### Response
#### Success Response (200)
- **result** (Boolean) - `true` if a new session can start asynchronously; otherwise `false`.

#### Response Example
```json
{
  "result": true
}
```

### maskView()

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

#### Method
POST

#### Endpoint
/maskView

#### Parameters
##### Path Parameters
None

##### Query Parameters
None

##### Request Body
- **view** (View) - Required - The View instance to mask its content.

### Request Example
```json
{
  "view": "<View object>"
}
```

### Response
#### Success Response (200)
- **result** (Boolean) - `true` if the view was added to the masked views; otherwise `false`.

#### Response Example
```json
{
  "result": true
}
```

### unmaskView()

#### Description
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.

#### Method
POST

#### Endpoint
/unmaskView

#### Parameters
##### Path Parameters
None

##### Query Parameters
None

##### Request Body
- **view** (View) - Required - The view instance to unmask.

### Request Example
{
  "view": "<View object>"
}

### Response
#### Success Response (200)
- **Boolean** (boolean) - `true` if the view was added to the unmasked views; otherwise `false`.

#### Response Example
{
  "result": true
}

ERROR HANDLING:
- 400 Bad Request: Invalid request body.
- 500 Internal Server Error: Unexpected error.

### setCustomUserId(String customUserId)

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

#### Parameters
- **customUserId** (String) - Required - 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.

### setOnSessionStartedCallback()
Java
Copy
```
setOnSessionStartedCallback(Function1<String, Unit> callback)
```

Sets a callback that is invoked when a new session starts. The callback receives the new session ID as a string parameter.
#### Parameters
`callback` Function1<String, Unit>
A callback that is invoked when a new session starts. The callback receives the new session ID as a string parameter.
#### Remarks
  * This function should only be called on the main thread.

### setCustomUserId()
Java
Copy
```
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.
```

```APIDOC
## [POST] /initialize

### Description
Initializes Clarity to start capturing the current session data.

### Method
POST

### Endpoint
/initialize

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **context** (Context) - Required - The application or activity context.
- **config** (ClarityConfig) - Required - Configuration of Clarity that tunes the SDK behavior (for example, which project to send to, which log level to use, and so on).

### Request Example
```json
{
  "context": "Activity or Context instance",
  "config": { "projectId": "...", "logLevel": "..." }
}
```

### Response
#### Success Response (200)
- **result** (Boolean) - `true` if Clarity initialization is possible; otherwise `false`.

#### Response Example
```json
{
  "result": true
}
```

### Error Handling
- No explicit error responses are documented. The method returns `false` if initialization is not possible.
```

--------------------------------

### setCurrentScreenName() usage example

Source: https://learn.microsoft.com/en-us/clarity/mobile-sdk/flutter-sdk

Imports the clarity_flutter package and calls Clarity.setCurrentScreenName with a screen name. Clarity starts a new page whenever the screen name changes; recommended to call inside a RouteObserver.

```dart
import 'package:clarity_flutter/clarity_flutter.dart';

void setClarityScreenName() {
  Clarity.setCurrentScreenName('screen_name');
}

```

--------------------------------

### Install gatsby-plugin-clarity with yarn

Source: https://learn.microsoft.com/en-us/clarity/third-party-integrations/gatsby

Run this command in the root of your Gatsby project to install the Clarity plugin using yarn.

```bash
yarn add gatsby-plugin-clarity
```

--------------------------------

### Initialize Clarity SDK in AppDelegate.swift

Source: https://learn.microsoft.com/en-us/clarity/mobile-sdk/ios-sdk

Initializes the Clarity SDK in an AppDelegate.swift file. Must run on the main thread. Replace <project-id> with your project ID from the Clarity Settings -> Overview page. Set the logLevel to .verbose while testing to debug initialization issues.

```swift
import Clarity

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Note: Replace `<project-id>` with actual project ID found Clarity Settings -> Overview page.
        // Note: Set `.verbose` value for `logLevel` parameter while testing to debug initialization issues.
        let clarityConfig = ClarityConfig(projectId: "<project-id>")
        ClaritySDK.initialize(config: clarityConfig)
        return true
    }
    // ...
}
```
Tokens:
Raw