Firebase Analytics

@capacitor-community/firebase-analytics

Capacitor community plugin for native Firebase Analytics.

❗❗ Breaking changes when updating to ✏️v5.0.0✏️❗❗

✏️✏️ This plugin now supports Capacitor 5 only. For Capacitor 4 please use version 4.x. For Capacitor 3 please use version 1.0.1 ! ✏️✏️

Maintainers

Maintainer	GitHub	Social
mesur.io	mesur-io	@mesur_io

Installation

Using npm:

npm install @capacitor-community/firebase-analytics@latest

Using yarn:

yarn add @capacitor-community/firebase-analytics@latest

Sync native files:

# Update the native plugins and dependencies referenced in package.json
npx cap sync

Note: You may also need to run File > Sync Project with Gradle Files in order for Android Studio to recognize the import.

Configuration

No configuration is required for this plugin.

Examples

Click here for an example on how to implement this plugin.

You can also clone the repository:

git clone https://github.com/jcesarmobile/capacitor-firebase-analytics-example

Supported methods

Name	Android	iOS	Web
setUserId	✅	✅	✅
setUserProperty	✅	✅	✅
getAppInstanceId	✅	✅	❌
setScreenName	✅	✅	❌
reset	✅	✅	❌
logEvent	✅	✅	✅
setCollectionEnabled	✅	✅	✅
setSessionTimeoutDuration	✅	✅	✅
enable	✅	✅	✅
disable	✅	✅	✅

Usage

import { FirebaseAnalytics } from "@capacitor-community/firebase-analytics";

/**
 * Platform: Web
 * Configure and initialize the firebase app.
 * @param options - firebase web app configuration options
 * */
FirebaseAnalytics.initializeFirebase({
  apiKey: "...",
  authDomain: "...",
  databaseURL: "...",
  projectId: "...",
  storageBucket: "...",
  messagingSenderId: "...",
  appId: "...",
  measurementId: "...",
});

/**
 * Platform: Web/Android/iOS
 * Sets the user ID property.
 * @param userId - unique identifier of a user
 * @returns void
 * https://firebase.google.com/docs/analytics/userid
 */
FirebaseAnalytics.setUserId({
  userId: "john_doe_123",
});

/**
 * Platform: Web/Android/iOS
 * Sets a user property to a given value.
 * @param options - property name and value to set
 * @returns void
 * https://firebase.google.com/docs/analytics/user-properties
 */
FirebaseAnalytics.setUserProperty({
  name: "favorite_food",
  value: "pizza",
});

/**
 * Platform: Android/iOS
 * Retrieves the app instance id from the service.
 * @param none
 * @returns instanceId - individual instance id value
 * https://firebase.google.com/docs/analytics/user-properties
 */
FirebaseAnalytics.getAppInstanceId();

/**
 * Platform: Android/iOS
 * Sets the current screen name, which specifies the current visual context in your app.
 * @param screenName - name of the current screen to track
 *        nameOverride - name of the screen class to override
 * @returns instanceId - individual instance id value
 * https://firebase.google.com/docs/analytics/screenviews
 */
FirebaseAnalytics.setScreenName({
  screenName: "login",
  nameOverride: "LoginScreen",
});

/**
 * Platform: Web/Android/iOS
 * Clears all analytics data for this app from the device and resets the app instance id.
 * @param none
 * @returns void
 */
FirebaseAnalytics.reset();

/**
 * Platform: Web/Android/iOS
 * Logs an app event.
 * @param name - name of the event to log
 *        params - key/value pairs of properties (25 maximum per event)
 * @returns void
 */
FirebaseAnalytics.logEvent({
  name: "select_content",
  params: {
    content_type: "image",
    content_id: "P12453",
    items: [{ name: "Kittens" }],
  },
});

/**
 * Platform: Web/Android/iOS
 * Sets whether analytics collection is enabled for this app on this device.
 * @param name - enabled - boolean true/false
 * @returns void
 */
FirebaseAnalytics.setCollectionEnabled({
  enabled: false,
});

/**
 * Platform: Web/Android/iOS
 * Deprecated - use setCollectionEnabled() instead
 * Enable analytics collection for this app on this device.
 * @param none
 * @returns void
 */
FirebaseAnalytics.enable();

/**
 * Platform: Web/Android/iOS
 * Deprecated - use setCollectionEnabled() instead
 * Disable analytics collection for this app on this device.
 * @param none
 * @returns void
 */
FirebaseAnalytics.disable();

/**
 * Platform: Web/Android/iOS
 * Sets the duration of inactivity that terminates the current session.
 * @param duration - duration in seconds (default - 18000)
 * @returns void
 */
FirebaseAnalytics.setSessionTimeoutDuration({
  duration: 10000,
});

Setup

Navigate to the project settings page for your app on Firebase.

iOS

Download the GoogleService-Info.plist file. In Xcode right-click on the yellow folder named "App" and select the Add files to "App".

Tip: if you drag and drop your file to this location, Xcode may not be able to find it.

Android

Download the google-services.json file and copy it to android/app/ directory of your capacitor project.

Variables

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

• $firebaseAnalyticsVersion version of com.google.firebase:firebase-analytics (default: 21.2.2)

iOS setup

• ionic start my-cap-app --capacitor
• cd my-cap-app
• npm install --save @capacitor-community/firebase-analytics
• mkdir www && touch www/index.html
• sudo gem install cocoapods (only once)
• npx cap add ios
• npx cap sync ios (every time you run npm install)
• npx cap open ios
• sign your app at xcode (general tab)
• add GoogleService-Info.plist to the app folder in xcode

Enable debug view

1. In Xcode, select Product > Scheme > Edit scheme
2. Select Run from the left menu
3. Select the Arguments tab
4. In the Arguments Passed On Launch section, add -FIRAnalyticsDebugEnabled

Tip: every time you change a native code you may need to clean up the cache (Product > Clean build folder) and then run the app again.

Android setup

• ionic start my-cap-app --capacitor
• cd my-cap-app
• npm install --save @capacitor-community/firebase-analytics
• mkdir www && touch www/index.html
• npx cap add android
• npx cap sync android (every time you run npm install)
• npx cap open android
• add google-services.json to your android/app folder

Now you should be set to go. Try to run your client using ionic cap run android --livereload --address=0.0.0.0.

Tip: every time you change a native code you may need to clean up the cache (Build > Clean Project | Build > Rebuild Project) and then run the app again.

Updating

For existing projects you can upgrade all capacitor related packages (including this plugin) with this single command

npx npm-upgrade '*capacitor*' && npm install

Migration

If you were previously using the capacitor-analytics package from npm

1. Update NPM package:

   npm uninstall --save capacitor-analytics
   npm install --save-prod @capacitor-community/firebase-analytics@latest

2. Update the plugin initialization in Android's MainActivity.java

   Remove the old plugin import:

   -import io.stewan.capacitor.analytics.AnalyticsPlugin;

   Update the init() call to remove the old plugin import. You may be able to remove the entire init() call if there is nothing else in there.

   // Initializes the Bridge
   this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
     // Additional plugins you've installed go here
     // Ex: add(TotallyAwesomePlugin.class);
   - add(AnalyticsPlugin.class);
   }});

3. Public API changes:

   • instance() has been renamed to getAppInstanceId()
   • setScreen() has been renamed to setScreenName()
   • setUserID() has been renamed to setUserId()
   • setUserProp() has been renamed to setUserProperty()
   • enable() has been deprecated in favor of setCollectionEnabled()
   • disable() has been deprecated in favor of setCollectionEnabled()

Further info

• Android
• iOS
• Web

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Chris Abernethy 🚧	Priyank Patel 💻	stewwan 💻	Karmjit Singh ⚠️ 🐛	Michel Roca 🐛	Matthias 👀	Tobi 💻
Nicholas Norris 🐛	gabrielscarvalho 🐛 💻	ptmkenny 🐛 💻 📖	vkyeswa 🐛	losciur ⚠️ 🐛	wyattades 💻	losciur 💻

This project follows the all-contributors specification. Contributions of any kind welcome!