@capacitor-firebase/performance 8.2.0 → 8.4.0

package/CapacitorFirebasePerformance.podspec

@@ -13,7 +13,7 @@ Pod::Spec.new do |s|
   s.source_files = 'ios/Plugin/**/*.{swift,h,m,c,cc,mm,cpp}'
   s.ios.deployment_target = '15.0'
   s.dependency 'Capacitor'
-  s.dependency 'FirebasePerformance', '~> 12.7.0'
+  s.dependency 'FirebasePerformance', '~> 12.7'
   s.swift_version = '5.1'
   s.static_framework = true
 end

package/README.md

@@ -1,4 +1,4 @@
-# @capacitor-firebase/performance
+# Capacitor Firebase Performance Monitoring Plugin
 
 Unofficial Capacitor plugin for [Firebase Performance Monitoring](https://firebase.google.com/docs/perf-mon).[^1]
 
@@ -8,9 +8,14 @@ Unofficial Capacitor plugin for [Firebase Performance Monitoring](https://fireba
   </a>
 </div>
 
-## Newsletter
+## Use Cases
 
-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/).
+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
 
@@ -28,7 +33,7 @@ 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:
 
 ```bash
-npx skills add capawesome-team/skills
+npx skills add capawesome-team/skills --skill capacitor-plugins
 ```
 
 Then use the following prompt:
@@ -58,6 +63,30 @@ If needed, you can define the following project variable in your app’s `variab
 
 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](https://github.com/capawesome-team/capacitor-firebase/issues/959):
+
+```json
+{
+  "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.
@@ -68,6 +97,12 @@ 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:
+
 ```typescript
 import { FirebasePerformance } from '@capacitor-firebase/performance';
 
@@ -78,6 +113,22 @@ const startTrace = async () => {
 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:
+
+```typescript
+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({
@@ -87,14 +138,21 @@ const incrementMetric = async () => {
   });
 };
 
-const setEnabled = async () => {
-  await FirebasePerformance.setEnabled({ enabled: true });
+const getMetric = async () => {
+  const result = await FirebasePerformance.getMetric({
+    traceName: 'test_trace',
+    metricName: 'item_cache_hit',
+  });
+  return result.value;
 };
+```
 
-const isEnabled = async () => {
-  const result = await FirebasePerformance.isEnabled();
-  return result.enabled;
-};
+### 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:
+
+```typescript
+import { FirebasePerformance } from '@capacitor-firebase/performance';
 
 const putAttribute = async () => {
   await FirebasePerformance.putAttribute({
@@ -123,22 +181,31 @@ const removeAttribute = async () => {
     attribute: 'user_id',
   });
 };
+```
 
-const putMetric = async () => {
-  await FirebasePerformance.putMetric({
-    traceName: 'test_trace',
-    metricName: 'item_cache_hit',
-    num: 1,
-  });
+### 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:
+
+```typescript
+import { FirebasePerformance } from '@capacitor-firebase/performance';
+
+const setEnabled = async () => {
+  await FirebasePerformance.setEnabled({ enabled: true });
 };
 
-const getMetric = async () => {
-  const result = await FirebasePerformance.getMetric({
-    traceName: 'test_trace',
-    metricName: 'item_cache_hit',
-  });
-  return result.value;
+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:
+
+```typescript
+import { FirebasePerformance } from '@capacitor-firebase/performance';
 
 const record = async () => {
   await FirebasePerformance.record({
@@ -513,6 +580,37 @@ Only available on web.
 
 </docgen-api>
 
+## 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](#start-and-stop-a-trace) 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](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Log events and user properties with Firebase Analytics.
+- [Firebase Crashlytics](https://capawesome.io/docs/sdks/capacitor/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](https://cloud.capawesome.io/newsletter/).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/performance/CHANGELOG.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capacitor-firebase/performance",
-  "version": "8.2.0",
-  "description": "Capacitor plugin for Firebase Performance Monitoring.",
+  "version": "8.4.0",
+  "description": "Capacitor plugin for Firebase Performance Monitoring on Android, iOS, and Web.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
@@ -37,7 +37,15 @@
   "keywords": [
     "capacitor",
     "plugin",
-    "native"
+    "native",
+    "capacitor-plugin",
+    "firebase",
+    "firebase performance",
+    "performance monitoring",
+    "app performance",
+    "tracing",
+    "custom traces",
+    "metrics"
   ],
   "scripts": {
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",
@@ -59,17 +67,16 @@
   },
   "devDependencies": {
     "@capacitor/android": "8.0.0",
-    "@capacitor/cli": "8.0.0",
+    "@capacitor/cli": "8.4.2",
     "@capacitor/core": "8.0.0",
     "@capacitor/docgen": "0.3.1",
     "@capacitor/ios": "8.0.0",
     "@ionic/eslint-config": "0.4.0",
     "eslint": "8.57.0",
     "firebase": "11.2.0",
-    "prettier": "3.4.2",
-    "prettier-plugin-java": "2.6.7",
+    "prettier-plugin-java": "2.9.7",
     "rimraf": "6.1.2",
-    "rollup": "4.53.3",
+    "rollup": "4.62.3",
     "swiftlint": "2.0.0",
     "typescript": "5.9.3"
   },