@capacitor-firebase/performance

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

Installation

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

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

$3

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: 21.0.4)

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

Configuration

No configuration required for this plugin.

Demo

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

Usage

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

API

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

$3

`typescript
startTrace(options: StartTraceOptions) => Promise
`

Starts a trace.

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

Since: 0.1.0

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

$3

`typescript
stopTrace(options: StopTraceOptions) => Promise
`

Stops a trace.

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

Since: 0.1.0

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

$3

`typescript
incrementMetric(options: IncrementMetricOptions) => Promise
`

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

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

Since: 0.1.0

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

$3

`typescript
setEnabled(options: SetEnabledOptions) => Promise
`

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

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

Since: 0.1.0

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

$3

`typescript
isEnabled() => Promise
`

Determines whether performance monitoring is enabled or disabled.

Returns: Promise<IsEnabledResult>

Since: 0.1.0

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

$3

`typescript
putAttribute(options: PutAttributeOptions) => Promise
`

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

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

Since: 6.3.0

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

$3

`typescript
getAttribute(options: GetAttributeOptions) => Promise
`

Returns the value of a custom attribute of a trace.

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

Returns: Promise<GetAttributeResult>

Since: 6.3.0

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

$3

`typescript
getAttributes(options: GetAttributesOptions) => Promise
`

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

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

Returns: Promise<GetAttributesResult>

Since: 6.3.0

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

$3

`typescript
removeAttribute(options: RemoveAttributeOptions) => Promise
`

Removes a custom attribute from a trace given its name.

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

Since: 6.3.0

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

$3

`typescript
putMetric(options: PutMetricOptions) => Promise
`

Sets the value of a custom metric.

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

Since: 6.3.0

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

$3

`typescript
getMetric(options: GetMetricOptions) => Promise
`

Get the value of a custom metric by name.

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

Returns: Promise<GetMetricResult>

Since: 6.3.0

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

$3

`typescript
record(options: RecordOptions) => Promise
`

Records a trace given its name and options.

Only available on web.

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

Since: 6.3.0

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

$3


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

$3

#### RemoveAttributeOptions

GetAttributeOptions

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.