npm:@capacitor-community/firebase-analytics

README

Firebase Analytics

@capacitor-community/firebase-analytics

Capacitor community plugin for native Firebase Analytics.

Maintainers

Maintainer	GitHub	Social
mesur.io	mesur-io	@mesur_io

Installation

Using npm:

# Capacitor v3
npm install @capacitor-community/firebase-analytics@latest

# Capacitor v2
npm install @capacitor-community/firebase-analytics@capacitor2-lts

Using yarn:

# Capacitor v3
yarn add @capacitor-community/firebase-analytics@latest

# Capacitor v2
yarn add @capacitor-community/firebase-analytics@capacitor2-lts

Sync native files:

npx cap sync

On iOS, no further steps are needed.

On Android, register the plugin in your main activity:

import com.getcapacitor.community.firebaseanalytics.FirebaseAnalytics;

public class MainActivity extends BridgeActivity {

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    registerPlugin(FirebaseAnalytics.class);
  }
}

Note: You may 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/priyankpat/capacitor-plugins-example
git checkout -b firebase-analytics

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.

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

In Xcode, select Product > Scheme > Edit scheme
Select Run from the left menu
Select the Arguments tab
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
[extra step] in android case we need to tell Capacitor to initialise the plugin:

on your MainActivity.java file add import com.getcapacitor.community.firebaseanalytics.FirebaseAnalytics; and then inside the init callback add(FirebaseAnalytics.class);

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

Update NPM package:

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

Update the plugin initialization in Android's MainActivity.java

Update the plugin import:

-import io.stewan.capacitor.analytics.AnalyticsPlugin;
+import com.getcapacitor.community.firebaseanalytics.FirebaseAnalytics;

Update the init() call to use the new plugin import:

// 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);
+ add(FirebaseAnalytics.class);
}});

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

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 💻