---
description: Capacitor plugin to integrate Grafana Faro for logs, events, errors, measurements, and native crash reporting on Android, iOS, and Web.
title: Capacitor Grafana Faro Plugin - Capawesome
image: https://capawesome.io/docs/assets/images/social/plugins/grafana-faro.png
---

[ Skip to content](#capawesomecapacitor-grafana-faro) 

[ 🎉 Introducing **Capawesome Platform** — one platform for Live Updates, Native Builds, App Store Publishing, and Insider SDKs.](https://capawesome.io) 

* [  Formbricks ](/docs/plugins/formbricks/)
* [  Geocoder ](/docs/plugins/geocoder/)
* [  Google Sign-In ](/docs/plugins/google-sign-in/)
* Grafana Faro [  Grafana Faro ](/docs/plugins/grafana-faro/)
* [  Configuration ](#configuration)
* [  Usage ](#usage)
* [  API ](#api)
* [  Type Aliases ](#type-aliases)
* [  Changelog ](#changelog)
* [  License ](#license)
* [  libSQL ](/docs/plugins/libsql/)
* [  Live Update ](/docs/plugins/live-update/)
* [  Managed Configurations ](/docs/plugins/managed-configurations/)
* [  Media Session ](/docs/plugins/media-session/)
* [  ML Kit ](/docs/plugins/mlkit/)
* [  Navigation Bar ](/docs/plugins/navigation-bar/)
* [  NFC ](/docs/plugins/nfc/)
* [  OAuth ](/docs/plugins/oauth/)
* [  Pedometer ](/docs/plugins/pedometer/)
* [  Photo Editor ](/docs/plugins/photo-editor/)
* [  PostHog ](/docs/plugins/posthog/)
* [  Printer ](/docs/plugins/printer/)
* [  Purchases ](/docs/plugins/purchases/)
* [  RealtimeKit ](/docs/plugins/realtimekit/)
* [  Screen Orientation ](/docs/plugins/screen-orientation/)
* [  Screenshot ](/docs/plugins/screenshot/)
* [  Secure Preferences ](/docs/plugins/secure-preferences/)
* [  Speech Recognition ](/docs/plugins/speech-recognition/)
* [  Speech Synthesis ](/docs/plugins/speech-synthesis/)
* [  Share Target ](/docs/plugins/share-target/)
* [  Square Mobile Payments ](/docs/plugins/square-mobile-payments/)
* [  SQLite ](/docs/plugins/sqlite/)
* [  Superwall ](/docs/plugins/superwall/)
* [  Torch ](/docs/plugins/torch/)
* [  Wifi ](/docs/plugins/wifi/)
* [  Zip ](/docs/plugins/zip/)
* [  Cloud ](/docs/cloud/)
* [  Live Updates ](/docs/cloud/live-updates/)
* Advanced
* Integrations
* [  Native Builds ](/docs/cloud/native-builds/)
* [  Configuration ](/docs/cloud/native-builds/configuration/)
* [  Environments ](/docs/cloud/native-builds/environments/)
* Guides
* [  Sample Projects ](/docs/cloud/native-builds/sample-projects/)
* [  Troubleshooting ](/docs/cloud/native-builds/troubleshooting/)
* [  Automations ](/docs/cloud/automations/)
* [  Assist ](/docs/cloud/assist/)
* Account
* Organizations
* [  Organization and User Management ](/docs/cloud/organizations/memberships/)
* [  Single Sign-On (SSO) ](/docs/cloud/organizations/sso/)
* [  Teams ](/docs/cloud/organizations/teams/)
* [  Two-Factor Authentication ](/docs/cloud/organizations/two-factor-authentication/)
* [  Integrations ](/docs/cloud/integrations/)
* [  License Keys ](/docs/cloud/license-keys/)
* [  Webhooks ](/docs/cloud/webhooks/)
* [  Pricing ](https://capawesome.io/pricing/)
* [  FAQ ](/docs/cloud/faq/)
* [  Support ](/docs/cloud/support/)
* [  Contributing ](/docs/contributing/)
* [  LLMs ](/docs/llms/)
* [  Insiders ](/docs/insiders/)
* [  License ](https://capawesome.io/legal/eula/)
* [  Support ](/docs/insiders/support/)
* [  FAQ ](/docs/insiders/faq/)
* [  Blog ](/blog/)
* Categories

* [  Configuration ](#configuration)
* [  Usage ](#usage)
* [  API ](#api)
* [  Type Aliases ](#type-aliases)
* [  Changelog ](#changelog)
* [  License ](#license)

# @capawesome/capacitor-grafana-faro[¶](#capawesomecapacitor-grafana-faro "Permanent link")

Unofficial Capacitor plugin for [Grafana Faro](https://grafana.com/oss/faro/).[1](#fn:1)

> ⚠️ **Experimental:** This plugin is in early development. APIs may change between minor versions. Feedback and bug reports are very welcome — please [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues).

[ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) 

## Newsletter[¶](#newsletter "Permanent link")

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).

## Features[¶](#features "Permanent link")

We are proud to offer one of the most complete and feature-rich Capacitor plugins for Grafana Faro. Here are some of the key features:

* 🖥️ **Cross-platform**: Supports Android, iOS and Web.
* 📝 **Logs**: Capture log messages with severity levels and structured context.
* 📡 **Events**: Track custom events with attributes and a platform domain.
* 💥 **Errors**: Capture errors with optional stack frames (compatible with [stacktrace.js](https://www.stacktracejs.com/)).
* 📊 **Measurements**: Record numeric metrics for performance and business KPIs.
* 👤 **User, Session and View Metadata**: Attach user, session and view information to every signal.
* 🛡️ **Native Crash Reporting**: Capture native crashes via [PLCrashReporter](https://github.com/microsoft/plcrashreporter) on iOS and [ApplicationExitInfo](https://developer.android.com/reference/android/app/ApplicationExitInfo) on Android.
* 🐌 **ANR Detection**: Detect Application Not Responding events on the Android main thread.
* 🌐 **Web Auto-Instrumentation**: Automatically capture uncaught errors, console output, Core Web Vitals, route changes and network performance on Web.
* ⏯️ **Pause and Resume**: Pause and resume telemetry on demand.
* 🎯 **Session Sampling**: Sample sessions with a configurable rate to control data volume.

## Compatibility[¶](#compatibility "Permanent link")

| Plugin Version | Capacitor Version | Status         |
| -------------- | ----------------- | -------------- |
| 0.1.x          | \>=8.x.x          | Active support |

## Installation[¶](#installation "Permanent link")

You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:

`[](#%5F%5Fcodelineno-0-1)npx skills add capawesome-team/skills --skill capacitor-plugins
`

Then use the following prompt:

`` [](#%5F%5Fcodelineno-1-1) Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-grafana-faro` plugin in my project.
 ``

If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:

`[](#%5F%5Fcodelineno-2-1)npm install @capawesome/capacitor-grafana-faro @grafana/faro-web-sdk
[](#%5F%5Fcodelineno-2-2)npx cap sync
`

### iOS[¶](#ios "Permanent link")

#### Minimum Deployment Target[¶](#minimum-deployment-target "Permanent link")

This plugin depends on [PLCrashReporter](https://github.com/microsoft/plcrashreporter) for native crash reporting. Make sure that your iOS deployment target is set to at least `15.0` in your Xcode project settings (usually in `ios/App/App.xcodeproj`):

`[](#%5F%5Fcodelineno-3-1)-IPHONEOS_DEPLOYMENT_TARGET = 14.0
[](#%5F%5Fcodelineno-3-2)+IPHONEOS_DEPLOYMENT_TARGET = 15.0
`

If you are using **CocoaPods**, make sure that your iOS deployment target is set to at least `15.0` in your `Podfile`:

`[](#%5F%5Fcodelineno-4-1)platform :ios, '15.0'
`

#### Conflicts with other crash reporters[¶](#conflicts-with-other-crash-reporters "Permanent link")

PLCrashReporter installs global crash handlers. Running this plugin alongside another crash reporter that also installs handlers (e.g. Firebase Crashlytics, Sentry) can lead to one or both reporters losing crash reports. Enable `instrumentations.nativeCrashReporting` only when no other crash reporter is active.

## Configuration[¶](#configuration "Permanent link")

Build-time configuration for the Grafana Faro plugin.

When `url` and `appName` are both provided, the native plugin auto-initializes during app startup. This allows native crash and ANR handlers to be installed before any JavaScript code runs. Calling`GrafanaFaro.initialize(...)` from JavaScript afterwards is not required and will fail with an `already initialized` error.

Only applies to Android and iOS.

| Prop                 | Type                                                       | Description                                                                                                                | Since |
| -------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----- |
| **apiKey**           | string                                                     | The API key sent as the x-api-key header.                                                                                  | 0.1.0 |
| **appEnvironment**   | string                                                     | The environment of the application (e.g. production, staging).                                                             | 0.1.0 |
| **appName**          | string                                                     | The name of the application.                                                                                               | 0.1.0 |
| **appNamespace**     | string                                                     | The namespace of the application.                                                                                          | 0.1.0 |
| **appVersion**       | string                                                     | The version of the application.                                                                                            | 0.1.0 |
| **instrumentations** | { anrTracking?: boolean; nativeCrashReporting?: boolean; } | Toggles for built-in automatic instrumentations. Only the toggles that apply at build time on Android and iOS are honored. | 0.1.0 |
| **url**              | string                                                     | The Faro collector endpoint URL.                                                                                           | 0.1.0 |

### Examples[¶](#examples "Permanent link")

In `capacitor.config.json`:

`[](#%5F%5Fcodelineno-5-1){
[](#%5F%5Fcodelineno-5-2)  "plugins": {
[](#%5F%5Fcodelineno-5-3)    "GrafanaFaro": {
[](#%5F%5Fcodelineno-5-4)      "apiKey": undefined,
[](#%5F%5Fcodelineno-5-5)      "appEnvironment": undefined,
[](#%5F%5Fcodelineno-5-6)      "appName": undefined,
[](#%5F%5Fcodelineno-5-7)      "appNamespace": undefined,
[](#%5F%5Fcodelineno-5-8)      "appVersion": undefined,
[](#%5F%5Fcodelineno-5-9)      "instrumentations": undefined,
[](#%5F%5Fcodelineno-5-10)      "url": 'https://faro-collector-prod.grafana.net/collect/<token>'
[](#%5F%5Fcodelineno-5-11)    }
[](#%5F%5Fcodelineno-5-12)  }
[](#%5F%5Fcodelineno-5-13)}
`

In `capacitor.config.ts`:

`[](#%5F%5Fcodelineno-6-1)/// <reference types="@capawesome/capacitor-grafana-faro" />
[](#%5F%5Fcodelineno-6-2)
[](#%5F%5Fcodelineno-6-3)import { CapacitorConfig } from '@capacitor/cli';
[](#%5F%5Fcodelineno-6-4)
[](#%5F%5Fcodelineno-6-5)const config: CapacitorConfig = {
[](#%5F%5Fcodelineno-6-6)  plugins: {
[](#%5F%5Fcodelineno-6-7)    GrafanaFaro: {
[](#%5F%5Fcodelineno-6-8)      apiKey: undefined,
[](#%5F%5Fcodelineno-6-9)      appEnvironment: undefined,
[](#%5F%5Fcodelineno-6-10)      appName: undefined,
[](#%5F%5Fcodelineno-6-11)      appNamespace: undefined,
[](#%5F%5Fcodelineno-6-12)      appVersion: undefined,
[](#%5F%5Fcodelineno-6-13)      instrumentations: undefined,
[](#%5F%5Fcodelineno-6-14)      url: 'https://faro-collector-prod.grafana.net/collect/<token>',
[](#%5F%5Fcodelineno-6-15)    },
[](#%5F%5Fcodelineno-6-16)  },
[](#%5F%5Fcodelineno-6-17)};
[](#%5F%5Fcodelineno-6-18)
[](#%5F%5Fcodelineno-6-19)export default config;
`

## Usage[¶](#usage "Permanent link")

`` [](#%5F%5Fcodelineno-7-1)import { GrafanaFaro } from '@capawesome/capacitor-grafana-faro';
[](#%5F%5Fcodelineno-7-2)
[](#%5F%5Fcodelineno-7-3)const initialize = async () => {
[](#%5F%5Fcodelineno-7-4)  await GrafanaFaro.initialize({
[](#%5F%5Fcodelineno-7-5)    app: {
[](#%5F%5Fcodelineno-7-6)      environment: 'production',
[](#%5F%5Fcodelineno-7-7)      name: 'my-app',
[](#%5F%5Fcodelineno-7-8)      version: '1.0.0',
[](#%5F%5Fcodelineno-7-9)    },
[](#%5F%5Fcodelineno-7-10)    instrumentations: {
[](#%5F%5Fcodelineno-7-11)      anrTracking: true,
[](#%5F%5Fcodelineno-7-12)      console: true,
[](#%5F%5Fcodelineno-7-13)      errors: true,
[](#%5F%5Fcodelineno-7-14)      nativeCrashReporting: true,
[](#%5F%5Fcodelineno-7-15)      performance: true,
[](#%5F%5Fcodelineno-7-16)      view: true,
[](#%5F%5Fcodelineno-7-17)      webVitals: true,
[](#%5F%5Fcodelineno-7-18)    },
[](#%5F%5Fcodelineno-7-19)    url: 'https://faro-collector-prod-us-central-0.grafana.net/collect/REPLACE_ME',
[](#%5F%5Fcodelineno-7-20)  });
[](#%5F%5Fcodelineno-7-21)};
[](#%5F%5Fcodelineno-7-22)
[](#%5F%5Fcodelineno-7-23)const pushLog = async () => {
[](#%5F%5Fcodelineno-7-24)  await GrafanaFaro.pushLog({
[](#%5F%5Fcodelineno-7-25)    level: 'info',
[](#%5F%5Fcodelineno-7-26)    message: 'User pressed sign-in button',
[](#%5F%5Fcodelineno-7-27)  });
[](#%5F%5Fcodelineno-7-28)};
[](#%5F%5Fcodelineno-7-29)
[](#%5F%5Fcodelineno-7-30)const pushEvent = async () => {
[](#%5F%5Fcodelineno-7-31)  await GrafanaFaro.pushEvent({
[](#%5F%5Fcodelineno-7-32)    attributes: { provider: 'google' },
[](#%5F%5Fcodelineno-7-33)    name: 'sign_in_started',
[](#%5F%5Fcodelineno-7-34)  });
[](#%5F%5Fcodelineno-7-35)};
[](#%5F%5Fcodelineno-7-36)
[](#%5F%5Fcodelineno-7-37)const pushError = async (error: Error) => {
[](#%5F%5Fcodelineno-7-38)  await GrafanaFaro.pushError({
[](#%5F%5Fcodelineno-7-39)    type: error.name,
[](#%5F%5Fcodelineno-7-40)    value: error.message,
[](#%5F%5Fcodelineno-7-41)  });
[](#%5F%5Fcodelineno-7-42)};
[](#%5F%5Fcodelineno-7-43)
[](#%5F%5Fcodelineno-7-44)const pushErrorWithStacktrace = async (error: Error) => {
[](#%5F%5Fcodelineno-7-45)  // Use `stacktrace-js` (or any equivalent) to parse the stack into
[](#%5F%5Fcodelineno-7-46)  // structured frames.
[](#%5F%5Fcodelineno-7-47)  const StackTrace = await import('stacktrace-js');
[](#%5F%5Fcodelineno-7-48)  const stackFrames = await StackTrace.fromError(error);
[](#%5F%5Fcodelineno-7-49)  await GrafanaFaro.pushError({
[](#%5F%5Fcodelineno-7-50)    type: error.name,
[](#%5F%5Fcodelineno-7-51)    value: error.message,
[](#%5F%5Fcodelineno-7-52)    stackFrames: stackFrames.map(frame => ({
[](#%5F%5Fcodelineno-7-53)      columnNumber: frame.columnNumber,
[](#%5F%5Fcodelineno-7-54)      fileName: frame.fileName,
[](#%5F%5Fcodelineno-7-55)      functionName: frame.functionName,
[](#%5F%5Fcodelineno-7-56)      lineNumber: frame.lineNumber,
[](#%5F%5Fcodelineno-7-57)    })),
[](#%5F%5Fcodelineno-7-58)  });
[](#%5F%5Fcodelineno-7-59)};
[](#%5F%5Fcodelineno-7-60)
[](#%5F%5Fcodelineno-7-61)const pushMeasurement = async () => {
[](#%5F%5Fcodelineno-7-62)  await GrafanaFaro.pushMeasurement({
[](#%5F%5Fcodelineno-7-63)    type: 'sign_in_duration',
[](#%5F%5Fcodelineno-7-64)    values: { duration_ms: 320 },
[](#%5F%5Fcodelineno-7-65)  });
[](#%5F%5Fcodelineno-7-66)};
[](#%5F%5Fcodelineno-7-67)
[](#%5F%5Fcodelineno-7-68)const setUser = async () => {
[](#%5F%5Fcodelineno-7-69)  await GrafanaFaro.setUser({
[](#%5F%5Fcodelineno-7-70)    email: 'jane@example.com',
[](#%5F%5Fcodelineno-7-71)    id: 'user-123',
[](#%5F%5Fcodelineno-7-72)    username: 'jane',
[](#%5F%5Fcodelineno-7-73)  });
[](#%5F%5Fcodelineno-7-74)};
[](#%5F%5Fcodelineno-7-75)
[](#%5F%5Fcodelineno-7-76)const setView = async () => {
[](#%5F%5Fcodelineno-7-77)  await GrafanaFaro.setView({ name: 'SignInView' });
[](#%5F%5Fcodelineno-7-78)};
 ``

## API[¶](#api "Permanent link")

* [getSession()](#getsession)
* [getView()](#getview)
* [initialize(...)](#initialize)
* [pause()](#pause)
* [pushError(...)](#pusherror)
* [pushEvent(...)](#pushevent)
* [pushLog(...)](#pushlog)
* [pushMeasurement(...)](#pushmeasurement)
* [resetSession()](#resetsession)
* [resetUser()](#resetuser)
* [setSession(...)](#setsession)
* [setUser(...)](#setuser)
* [setView(...)](#setview)
* [unpause()](#unpause)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)

### getSession()[¶](#getsession "Permanent link")

`[](#%5F%5Fcodelineno-8-1)getSession() => Promise<GetSessionResult>
`

Get the current session.

**Returns:** `Promise<[GetSessionResult](#getsessionresult)>`

**Since:** 0.1.0

---

### getView()[¶](#getview "Permanent link")

`[](#%5F%5Fcodelineno-9-1)getView() => Promise<GetViewResult>
`

Get the current view.

**Returns:** `Promise<[GetViewResult](#getviewresult)>`

**Since:** 0.1.0

---

### initialize(...)[¶](#initialize "Permanent link")

`[](#%5F%5Fcodelineno-10-1)initialize(options: InitializeOptions) => Promise<void>
`

Initialize the Faro SDK.

**Attention**: This method must be called before any other method.

| Param       | Type                                    |
| ----------- | --------------------------------------- |
| **options** | [InitializeOptions](#initializeoptions) |

**Since:** 0.1.0

---

### pause()[¶](#pause "Permanent link")

`[](#%5F%5Fcodelineno-11-1)pause() => Promise<void>
`

Pause sending telemetry. New signals are still buffered locally.

**Since:** 0.1.0

---

### pushError(...)[¶](#pusherror "Permanent link")

`[](#%5F%5Fcodelineno-12-1)pushError(options: PushErrorOptions) => Promise<void>
`

Push an error/exception.

| Param       | Type                                  |
| ----------- | ------------------------------------- |
| **options** | [PushErrorOptions](#pusherroroptions) |

**Since:** 0.1.0

---

### pushEvent(...)[¶](#pushevent "Permanent link")

`[](#%5F%5Fcodelineno-13-1)pushEvent(options: PushEventOptions) => Promise<void>
`

Push a custom event.

| Param       | Type                                  |
| ----------- | ------------------------------------- |
| **options** | [PushEventOptions](#pusheventoptions) |

**Since:** 0.1.0

---

### pushLog(...)[¶](#pushlog "Permanent link")

`[](#%5F%5Fcodelineno-14-1)pushLog(options: PushLogOptions) => Promise<void>
`

Push a log message.

| Param       | Type                              |
| ----------- | --------------------------------- |
| **options** | [PushLogOptions](#pushlogoptions) |

**Since:** 0.1.0

---

### pushMeasurement(...)[¶](#pushmeasurement "Permanent link")

`[](#%5F%5Fcodelineno-15-1)pushMeasurement(options: PushMeasurementOptions) => Promise<void>
`

Push a measurement (numeric metric).

| Param       | Type                                              |
| ----------- | ------------------------------------------------- |
| **options** | [PushMeasurementOptions](#pushmeasurementoptions) |

**Since:** 0.1.0

---

### resetSession()[¶](#resetsession "Permanent link")

`[](#%5F%5Fcodelineno-16-1)resetSession() => Promise<void>
`

Clear the current session and start a new one.

**Since:** 0.1.0

---

### resetUser()[¶](#resetuser "Permanent link")

`[](#%5F%5Fcodelineno-17-1)resetUser() => Promise<void>
`

Clear the current user.

**Since:** 0.1.0

---

### setSession(...)[¶](#setsession "Permanent link")

`[](#%5F%5Fcodelineno-18-1)setSession(options: SetSessionOptions) => Promise<void>
`

Set the current session.

| Param       | Type                                    |
| ----------- | --------------------------------------- |
| **options** | [SetSessionOptions](#setsessionoptions) |

**Since:** 0.1.0

---

### setUser(...)[¶](#setuser "Permanent link")

`[](#%5F%5Fcodelineno-19-1)setUser(options: SetUserOptions) => Promise<void>
`

Set the current user.

| Param       | Type                          |
| ----------- | ----------------------------- |
| **options** | [UserMetadata](#usermetadata) |

**Since:** 0.1.0

---

### setView(...)[¶](#setview "Permanent link")

`[](#%5F%5Fcodelineno-20-1)setView(options: SetViewOptions) => Promise<void>
`

Set the current view (e.g. screen / route name).

| Param       | Type                          |
| ----------- | ----------------------------- |
| **options** | [ViewMetadata](#viewmetadata) |

**Since:** 0.1.0

---

### unpause()[¶](#unpause "Permanent link")

`[](#%5F%5Fcodelineno-21-1)unpause() => Promise<void>
`

Resume sending telemetry.

**Since:** 0.1.0

---

### Interfaces[¶](#interfaces "Permanent link")

#### GetSessionResult[¶](#getsessionresult "Permanent link")

| Prop           | Type                         | Description                     | Since |
| -------------- | ---------------------------- | ------------------------------- | ----- |
| **attributes** | { \[key: string\]: string; } | The current session attributes. | 0.1.0 |
| **id**         | string                       | The current session ID.         | 0.1.0 |

#### GetViewResult[¶](#getviewresult "Permanent link")

| Prop     | Type   | Description            | Since |
| -------- | ------ | ---------------------- | ----- |
| **name** | string | The current view name. | 0.1.0 |

#### InitializeOptions[¶](#initializeoptions "Permanent link")

| Prop                    | Type                                                | Description                                                       | Default | Since |
| ----------------------- | --------------------------------------------------- | ----------------------------------------------------------------- | ------- | ----- |
| **apiKey**              | string                                              | API key sent as the x-api-key header to the collector.            | 0.1.0   |       |
| **app**                 | [AppMetadata](#appmetadata)                         | Application metadata attached to every signal.                    | 0.1.0   |       |
| **ignoreErrors**        | string\[\]                                          | Error message patterns to ignore.                                 | 0.1.0   |       |
| **ignoreUrls**          | string\[\]                                          | URL patterns to ignore when instrumenting network calls.          | 0.1.0   |       |
| **instrumentations**    | [InstrumentationsOptions](#instrumentationsoptions) | Toggles for built-in automatic instrumentations.                  | 0.1.0   |       |
| **paused**              | boolean                                             | Start in a paused state. Telemetry must be resumed via unpause(). | false   | 0.1.0 |
| **sessionAttributes**   | { \[key: string\]: string; }                        | Initial session attributes.                                       | 0.1.0   |       |
| **sessionSamplingRate** | number                                              | Session sampling rate in \[0, 1\]. 1 \= all sessions, 0 \= none.  | 1       | 0.1.0 |
| **url**                 | string                                              | The Faro collector endpoint URL.                                  | 0.1.0   |       |
| **user**                | [UserMetadata](#usermetadata)                       | Initial user metadata.                                            | 0.1.0   |       |
| **view**                | [ViewMetadata](#viewmetadata)                       | Initial view metadata.                                            | 0.1.0   |       |

#### AppMetadata[¶](#appmetadata "Permanent link")

| Prop            | Type   | Description                                                    | Since |
| --------------- | ------ | -------------------------------------------------------------- | ----- |
| **environment** | string | The environment of the application (e.g. production, staging). | 0.1.0 |
| **name**        | string | The name of the application.                                   | 0.1.0 |
| **namespace**   | string | The namespace of the application.                              | 0.1.0 |
| **version**     | string | The version of the application.                                | 0.1.0 |

#### InstrumentationsOptions[¶](#instrumentationsoptions "Permanent link")

Toggles for built-in automatic instrumentations.

Note: some toggles only apply on specific platforms. The plugin silently ignores toggles that do not apply on the current platform.

| Prop                     | Type    | Description                                                                                | Default | Since |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------ | ------- | ----- |
| **anrTracking**          | boolean | Detect Application Not Responding events on the main thread. Only available for Android.   | false   | 0.1.0 |
| **console**              | boolean | Capture console.warn and console.error calls. Only available for Web.                      | true    | 0.1.0 |
| **errors**               | boolean | Capture uncaught errors and unhandled promise rejections. Only available for Web.          | true    | 0.1.0 |
| **nativeCrashReporting** | boolean | Capture native crashes (reported on the next session). Only available for Android and iOS. | false   | 0.1.0 |
| **performance**          | boolean | Capture fetch and XHR performance entries. Only available for Web.                         | true    | 0.1.0 |
| **view**                 | boolean | Capture History API navigation as view changes. Only available for Web.                    | true    | 0.1.0 |
| **webVitals**            | boolean | Capture Core Web Vitals (LCP, FID, CLS, INP, TTFB). Only available for Web.                | true    | 0.1.0 |

#### UserMetadata[¶](#usermetadata "Permanent link")

| Prop           | Type                         | Description                                   | Since |
| -------------- | ---------------------------- | --------------------------------------------- | ----- |
| **attributes** | { \[key: string\]: string; } | Additional key-value attributes for the user. | 0.1.0 |
| **email**      | string                       | The user's email address.                     | 0.1.0 |
| **fullName**   | string                       | The user's full name.                         | 0.1.0 |
| **id**         | string                       | The user's ID.                                | 0.1.0 |
| **username**   | string                       | The user's username.                          | 0.1.0 |

#### ViewMetadata[¶](#viewmetadata "Permanent link")

| Prop     | Type   | Description           | Since |
| -------- | ------ | --------------------- | ----- |
| **name** | string | The name of the view. | 0.1.0 |

#### PushErrorOptions[¶](#pusherroroptions "Permanent link")

| Prop            | Type                         | Description                                         | Default | Since |
| --------------- | ---------------------------- | --------------------------------------------------- | ------- | ----- |
| **context**     | { \[key: string\]: string; } | Additional context attached to the error.           | 0.1.0   |       |
| **fatal**       | boolean                      | Mark the error as fatal (e.g. caused a crash).      | false   | 0.1.0 |
| **stackFrames** | StackFrame\[\]               | Pre-parsed stack frames generated by stacktrace.js. | 0.1.0   |       |
| **type**        | string                       | The error type (e.g. 'TypeError').                  | 0.1.0   |       |
| **value**       | string                       | The error message.                                  | 0.1.0   |       |

#### StackFrame[¶](#stackframe "Permanent link")

Subset of the stacktrace generated by `stacktrace.js`.

| Prop             | Type   | Since |
| ---------------- | ------ | ----- |
| **columnNumber** | number | 0.1.0 |
| **fileName**     | string | 0.1.0 |
| **functionName** | string | 0.1.0 |
| **lineNumber**   | number | 0.1.0 |

#### PushEventOptions[¶](#pusheventoptions "Permanent link")

| Prop           | Type                         | Description                                                                                | Since |
| -------------- | ---------------------------- | ------------------------------------------------------------------------------------------ | ----- |
| **attributes** | { \[key: string\]: string; } | Key-value attributes attached to the event.                                                | 0.1.0 |
| **domain**     | string                       | Logical grouping for the event. Defaults to the platform domain ('web', 'android', 'ios'). | 0.1.0 |
| **name**       | string                       | The name of the event.                                                                     | 0.1.0 |

#### PushLogOptions[¶](#pushlogoptions "Permanent link")

| Prop        | Type                         | Description                             | Default | Since |
| ----------- | ---------------------------- | --------------------------------------- | ------- | ----- |
| **context** | { \[key: string\]: string; } | Additional context attached to the log. | 0.1.0   |       |
| **level**   | [LogLevel](#loglevel)        | The log level.                          | 'info'  | 0.1.0 |
| **message** | string                       | The log message.                        | 0.1.0   |       |

#### PushMeasurementOptions[¶](#pushmeasurementoptions "Permanent link")

| Prop        | Type                         | Description                                     | Since |
| ----------- | ---------------------------- | ----------------------------------------------- | ----- |
| **context** | { \[key: string\]: string; } | Additional context attached to the measurement. | 0.1.0 |
| **type**    | string                       | The measurement type (e.g. 'custom\_latency').  | 0.1.0 |
| **values**  | { \[key: string\]: number; } | Key-value numeric measurements.                 | 0.1.0 |

#### SetSessionOptions[¶](#setsessionoptions "Permanent link")

| Prop           | Type                         | Description                                               | Since |
| -------------- | ---------------------------- | --------------------------------------------------------- | ----- |
| **attributes** | { \[key: string\]: string; } | The session attributes.                                   | 0.1.0 |
| **id**         | string                       | Optional session ID. A UUID v4 is generated when omitted. | 0.1.0 |

### Type Aliases[¶](#type-aliases "Permanent link")

#### LogLevel[¶](#loglevel "Permanent link")

`'debug' | 'error' | 'info' | 'log' | 'trace' | 'warn'`

#### SetUserOptions[¶](#setuseroptions "Permanent link")

`[UserMetadata](#usermetadata)`

#### SetViewOptions[¶](#setviewoptions "Permanent link")

`[ViewMetadata](#viewmetadata)`

## Changelog[¶](#changelog "Permanent link")

See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/grafana-faro/CHANGELOG.md).

## License[¶](#license "Permanent link")

See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/grafana-faro/LICENSE).

---

1. This project is not affiliated with, endorsed by, sponsored by, or approved by Grafana Labs or any of their affiliates or subsidiaries. [↩](#fnref:1 "Jump back to footnote 1 in the text")

May 27, 2026 

 Back to top