Capacitor Firebase Performance Monitoring Plugin

Unofficial Capacitor plugin for Firebase Performance Monitoring.[^1]

Use Cases

The Firebase Performance Monitoring plugin is typically used to gain insight into the performance characteristics of your app, for example:

• Custom code traces: Measure how long specific tasks in your app take, such as loading data or processing an image.
• Custom metrics: Count performance-related events within a trace, such as cache hits or retries.
• Performance segmentation: Add custom attributes to your traces, such as a user id, to segment your performance data.
• Privacy compliance: Enable or disable performance monitoring at runtime, for example based on the user's consent.

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | >=8.x.x | Active support | | 7.x.x | 7.x.x | Deprecated | | 6.x.x | 6.x.x | Deprecated | | 5.x.x | 5.x.x | Deprecated | | 1.x.x | 4.x.x | Deprecated |

Guides

• Monitor App Performance in Capacitor with Firebase: Automatic and custom traces for app start, rendering, and network calls with this plugin.
• How to Use Firebase in a Capacitor App: The whole plugin family in one guide, with performance monitoring as one half of app health.

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/performance` plugin in my project.

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

npm install @capacitor-firebase/performance firebase
npx cap sync

Add Firebase to your project if you haven't already (Android / iOS / Web).

Android

See Add the Performance Monitoring plugin to your app and follow the instructions to set up your app correctly.

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

• $firebasePerfVersion version of com.google.firebase:firebase-perf (default: 22.0.4)

This can be useful if you encounter dependency conflicts with other plugins in your project.

iOS

Swift Package Manager

Add the following to your capacitor.config.json (or capacitor.config.ts) to avoid a SwiftPM package identity collision:

{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/performance": {
            "symlink": true
          }
        }
      }
    }
  }
}

Attention: SPM packageOptions support requires Capacitor CLI 8.4.0+.

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-firebase-plugin-demo

Usage

The following examples show how to start and stop traces, record custom metrics, add custom attributes, toggle performance monitoring, and record a trace manually.

Start and stop a trace

Start a custom code trace to measure how long a specific task in your app takes and stop it as soon as the task is completed:

import { FirebasePerformance } from '@capacitor-firebase/performance';

const startTrace = async () => {
  await FirebasePerformance.startTrace({ traceName: 'test_trace' });
};

const stopTrace = async () => {
  await FirebasePerformance.stopTrace({ traceName: 'test_trace' });
};

Record custom metrics

Set the value of a custom metric for a trace, increment it atomically, or read its current value. Note that metric values are floored down to the nearest integer:

import { FirebasePerformance } from '@capacitor-firebase/performance';

const putMetric = async () => {
  await FirebasePerformance.putMetric({
    traceName: 'test_trace',
    metricName: 'item_cache_hit',
    num: 1,
  });
};

const incrementMetric = async () => {
  await FirebasePerformance.incrementMetric({
    traceName: 'test_trace',
    metricName: 'item_cache_hit',
    incrementBy: 1,
  });
};

const getMetric = async () => {
  const result = await FirebasePerformance.getMetric({
    traceName: 'test_trace',
    metricName: 'item_cache_hit',
  });
  return result.value;
};

Add custom attributes to a trace

Set custom attributes on a trace, for example a user id, to segment your performance data. You can also read or remove them again:

import { FirebasePerformance } from '@capacitor-firebase/performance';

const putAttribute = async () => {
  await FirebasePerformance.putAttribute({
    traceName: 'test_trace',
    attribute: 'user_id',
    value: '123',
  });
};

const getAttribute = async () => {
  const result = await FirebasePerformance.getAttribute({
    traceName: 'test_trace',
    attribute: 'user_id',
  });
  return result.attributes;
};

const getAttributes = async () => {
  const result = await FirebasePerformance.getAttributes({ traceName: 'test_trace' });
  return result.attributes;
};

const removeAttribute = async () => {
  await FirebasePerformance.removeAttribute({
    traceName: 'test_trace',
    attribute: 'user_id',
  });
};

Enable or disable performance monitoring

Enable or disable performance monitoring at runtime, for example based on the user's consent. The setting is applied with the next start of the app:

import { FirebasePerformance } from '@capacitor-firebase/performance';

const setEnabled = async () => {
  await FirebasePerformance.setEnabled({ enabled: true });
};

const isEnabled = async () => {
  const result = await FirebasePerformance.isEnabled();
  return result.enabled;
};

Record a trace manually

Record a trace for a task that has already been completed by providing its start time and duration. Only available on Web:

import { FirebasePerformance } from '@capacitor-firebase/performance';

const record = async () => {
  await FirebasePerformance.record({
    traceName: 'test_trace',
    startTime: Date.now(),
    duration: 1000,
    options: {
      metrics: {
        item_cache_hit: 1,
      },
      attributes: {
        user_id: '123',
      },
    },
  });
};

API

• startTrace(...)
• stopTrace(...)
• incrementMetric(...)
• setEnabled(...)
• isEnabled()
• putAttribute(...)
• getAttribute(...)
• getAttributes(...)
• removeAttribute(...)
• putMetric(...)
• getMetric(...)
• record(...)
• Interfaces
• Type Aliases

startTrace(...)

startTrace(options: StartTraceOptions) => Promise<void>

Starts a trace.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | StartTraceOptions |

Since: 0.1.0

stopTrace(...)

stopTrace(options: StopTraceOptions) => Promise<void>

Stops a trace.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | StopTraceOptions |

Since: 0.1.0

incrementMetric(...)

incrementMetric(options: IncrementMetricOptions) => Promise<void>

Atomically increments the metric with the given name for the selected trace by the incrementBy value.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | IncrementMetricOptions |

Since: 0.1.0

setEnabled(...)

setEnabled(options: SetEnabledOptions) => Promise<void>

Enables or disables performance monitoring. Will be applied with the next start of the app.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | SetEnabledOptions |

Since: 0.1.0

isEnabled()

isEnabled() => Promise<IsEnabledResult>

Determines whether performance monitoring is enabled or disabled.

Returns: Promise<IsEnabledResult>

Since: 0.1.0

putAttribute(...)

putAttribute(options: PutAttributeOptions) => Promise<void>

Sets a custom attribute of a trace to a given value.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | PutAttributeOptions |

Since: 6.3.0

getAttribute(...)

getAttribute(options: GetAttributeOptions) => Promise<GetAttributeResult>

Returns the value of a custom attribute of a trace.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | GetAttributeOptions |

Returns: Promise<GetAttributeResult>

Since: 6.3.0

getAttributes(...)

getAttributes(options: GetAttributesOptions) => Promise<GetAttributesResult>

Gets the all the custom attributes of a trace with their values.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | GetAttributesOptions |

Returns: Promise<GetAttributesResult>

Since: 6.3.0

removeAttribute(...)

removeAttribute(options: RemoveAttributeOptions) => Promise<void>

Removes a custom attribute from a trace given its name.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | GetAttributeOptions |

Since: 6.3.0

putMetric(...)

putMetric(options: PutMetricOptions) => Promise<void>

Sets the value of a custom metric.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | PutMetricOptions |

Since: 6.3.0

getMetric(...)

getMetric(options: GetMetricOptions) => Promise<GetMetricResult>

Get the value of a custom metric by name.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | GetMetricOptions |

Returns: Promise<GetMetricResult>

Since: 6.3.0

record(...)

record(options: RecordOptions) => Promise<void>

Records a trace given its name and options.

Only available on web.

| Param | Type | | ------------- | ------------------------------------------------------- | | options | RecordOptions |

Since: 6.3.0

Interfaces

StartTraceOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | traceName | string | Custom trace name. Names for custom code traces must meet the following requirements: no leading or trailing whitespace, no leading underscore (_) character, and max length is 100 characters. | 0.1.0 |

StopTraceOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | ------------------------------------------------- | ----- | | traceName | string | Name of the trace that was set with startTrace. | 0.1.0 |

IncrementMetricOptions

| Prop | Type | Description | Default | Since | | ----------------- | ------------------- | ------------------------------------------------- | -------------- | ----- | | traceName | string | Name of the trace that was set with startTrace. | | 0.1.0 | | metricName | string | Name of the metric to be incremented. | | 0.1.0 | | incrementBy | number | Amount by which the metric has to be incremented. | 1 | 0.1.0 |

SetEnabledOptions

| Prop | Type | Description | Since | | ------------- | -------------------- | ----------------------------------------- | ----- | | enabled | boolean | Should performance monitoring be enabled. | 0.1.0 |

IsEnabledResult

| Prop | Type | Description | Since | | ------------- | -------------------- | --------------------------------------------------------------- | ----- | | enabled | boolean | true if performance monitoring is enabled, otherwise false. | 0.1.0 |

PutAttributeOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | --------------------------------------- | ----- | | traceName | string | Name of the trace to set its attribute. | 6.3.0 | | attribute | string | Name of the attribute to set its value. | 6.3.0 | | value | string | The value to set to the attribute. | 6.3.0 |

GetAttributeResult

| Prop | Type | Description | Since | | ----------- | --------------------------- | ---------------------------------- | ----- | | value | string | null | The value of the custom attribute. | 6.3.0 |

GetAttributeOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | -------------------------------------------- | ----- | | traceName | string | Name of the trace to set its attribute. | 6.3.0 | | attribute | string | Name of the attribute to retrieve its value. | 6.3.0 |

GetAttributesResult

| Prop | Type | Description | Since | | ---------------- | --------------------------------------- | ------------------------------------------------------------ | ----- | | attributes | { [key: string]: string; } | A map of all custom attributes of a trace with their values. | 6.3.0 |

GetAttributesOptions

| Prop | Type | Description | Since | | --------------- | ------------------- | ---------------------------------------- | ----- | | traceName | string | Name of the trace to get its attributes. | 6.3.0 |

PutMetricOptions

| Prop | Type | Description | Since | | ---------------- | ------------------- | ---------------------------------------------------------------------------------------- | ----- | | traceName | string | Name of the trace to set its metric. | 6.3.0 | | metricName | string | The metric name. | 6.3.0 | | num | number | The value to set for the metric. The given value is floored down to the nearest integer. | 6.3.0 |

GetMetricResult

| Prop | Type | Description | Since | | ----------- | ------------------- | ---------------------------------- | ----- | | value | number | The value of the metric if exists. | 6.3.0 |

GetMetricOptions

| Prop | Type | Description | Since | | ---------------- | ------------------- | ------------------------------------ | ----- | | traceName | string | Name of the trace to get its metric. | 6.3.0 | | metricName | string | The metric name. | 6.3.0 |

RecordOptions

| Prop | Type | Description | Since | | --------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----- | | traceName | string | Name of the trace to record. | 6.3.0 | | startTime | number | Start time of the trace since epoch in milliseconds. | 6.3.0 | | duration | number | The duration of the trace in milliseconds. | 6.3.0 | | options | { metrics?: { [key: string]: number; }; attributes?: { [key: string]: string; }; } | An optional object that holds optional maps of custom metrics and attributes. | 6.3.0 |

Type Aliases

RemoveAttributeOptions

GetAttributeOptions

FAQ

How do I measure the duration of a specific task in my app?

Start a custom code trace with startTrace(...) before the task begins and stop it with stopTrace(...) as soon as the task is completed, as shown in the usage example above. You can enrich the trace with custom metrics and attributes before stopping it.

What are the requirements for custom trace names?

Names for custom code traces must not contain leading or trailing whitespace, must not start with an underscore (_), and may have a maximum length of 100 characters.

What is the difference between a metric and an attribute?

A metric is a numeric value of a trace, for example a counter for cache hits, which is set with putMetric(...) or incremented with incrementMetric(...). Note that metric values are floored down to the nearest integer. An attribute is a string value of a trace, for example a user id, which is set with putAttribute(...) and can be used to segment your performance data.

Can users disable performance monitoring at runtime?

Yes, call setEnabled(...) to enable or disable performance monitoring, for example based on the user's consent. The setting is applied with the next start of the app. Use isEnabled() to determine whether performance monitoring is currently enabled or disabled.

Why does the record method not work on Android and iOS?

The record(...) method is only available on Web. On Android and iOS, use startTrace(...) and stopTrace(...) to measure the duration of a task instead.

Related Plugins

• Firebase Analytics: Log events and user properties with Firebase Analytics.
• Firebase Crashlytics: Track and analyze app crashes with Firebase Crashlytics.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.