@capacitor-firebase/performance¶

Unofficial Capacitor plugin for Firebase Performance Monitoring.¹

Installation¶

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¶

This plugin will use the following project variables (defined in your app’s variables.gradle file):

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

Configuration¶

No configuration required for this plugin.

Demo¶

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

Usage¶

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

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

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

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

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

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

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',
  });
};

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

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

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

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
`result`	`{ [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

Changelog¶

See CHANGELOG.md.

License¶

See LICENSE.

This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. ↩