Capacitor FCM
@capacitor-community/fcm
Capacitor community plugin for enabling FCM capabilities
## Maintainers
| Maintainer | GitHub | Social |
| ------------ | --------------------------------------- | ----------------------------------------- |
| Stewan Silva | [stewones](https://github.com/stewones) | [@stewones](https://x.com/stewones) |
## Notice π
We're starting fresh under an official org. If you were using the previous npm package `capacitor-fcm`, please update your package.json to `@capacitor-community/fcm`. Check out [changelog](/CHANGELOG.md) for more info.
## Installation
Using npm:
```bash
npm install @capacitor-community/fcm
```
Using yarn:
```bash
yarn add @capacitor-community/fcm
```
Sync native files:
```bash
npx cap sync
```
> ### Notice
>
> This plugin is intended to be used combined with Capacitor API for [Push Notifications](https://capacitor.ionicframework.com/docs/apis/push-notifications). Capacitor only provides APN token whereas this plugin offers the possibility to work with FCM tokens and more.
## API
| method | info | platform |
| ------------------- | --------------------------------------------- | ----------- |
| `subscribeTo` | subscribe to fcm topic | ios/android |
| `unsubscribeFrom` | unsubscribe from fcm topic | ios/android |
| `getToken` | get fcm token to eventually use from a server | ios/android |
| `refreshToken` | refresh fcm token to get a new one | ios/android |
| `deleteInstance` | remove local fcm instance completely | ios/android |
| `setAutoInit` | enable the auto initialization of the library | ios/android |
| `isAutoInitEnabled` | check whether auto initialization is enabled | ios/android |
## Usage
```ts
import { FCM } from '@capacitor-community/fcm';
import { PushNotifications } from '@capacitor/push-notifications';
// external required step
// register for push
await PushNotifications.requestPermissions();
await PushNotifications.register();
// now you can subscribe to a specific topic
FCM.subscribeTo({ topic: 'test' })
.then(r => alert(`subscribed to topic`))
.catch(err => console.log(err));
// Unsubscribe from a specific topic
FCM.unsubscribeFrom({ topic: 'test' })
.then(() => alert(`unsubscribed from topic`))
.catch(err => console.log(err));
// Get FCM token instead of the APN one returned by Capacitor
FCM.getToken()
.then(r => alert(`Token ${r.token}`))
.catch(err => console.log(err));
// Delete the old FCM token and get a new one
FCM.refreshToken()
.then(r => alert(`Token ${r.token}`))
.catch(err => console.log(err));
// Remove FCM instance
FCM.deleteInstance()
.then(() => alert(`Token deleted`))
.catch(err => console.log(err));
// Enable the auto initialization of the library
FCM.setAutoInit({ enabled: true }).then(() => alert(`Auto init enabled`));
// Check the auto initialization status
FCM.isAutoInitEnabled().then(r => {
console.log('Auto init is ' + (r.enabled ? 'enabled' : 'disabled'));
});
```
## Add Google config files
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.
### Certificate
- apple
- create an app identifier (apple site)
- add push notifications
- add signing request (https://developer.apple.com/help/account/certificates/create-a-certificate-signing-request)
- generate an APN key and then note down the ID displayed. also download the p8 file (https://fluffy.es/p8-push-notification/)
- firebase
- add the downloaded p8 file to firebase settings with noted key ID and the account team ID
## iOS setup
- [Install homebrew](https://capacitorjs.com/docs/getting-started/environment-setup#homebrew) _(once)_
- `brew install cocoapods` _(once a time)_
- `ionic start my-cap-app --capacitor`
- `cd my-cap-app`
- `mkdir www && touch www/index.html`
- `npx cap add ios`
- `npm install --save @capacitor-community/fcm`
- `npx cap sync ios` _(always do sync after a plugin install)_
- `npx cap open ios`
* sign your app at xcode (general tab)
* enable remote notification capabilities
* add `GoogleService-Info.plist` to the app folder in xcode
```
// (optional) turn off `swizzling` in the `info.plist`
FirebaseAppDelegateProxyEnabled
NO
```
> 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.
### Prevent auto initialization
If you need to implement opt-in behavior, you can disable the auto initialization of the library by following the [Firebase docs](https://firebase.google.com/docs/cloud-messaging/ios/client#prevent_auto_initialization).
### SPM setup (iOS 15.0+)
__First ensure all your dependencies are compatible with SPM. Otherwise, stick to the Cocoapods installation steps.__
You can also install the plugin using Swift Package Manager (SPM) instead of CocoaPods.
To do so, you don't need to install CocoaPods (steps 1 & 2), but you'll need to configure capacitor to use SPM:
* to add iOS target: `npx cap add ios --packagemanager SPM`
* to migrate an existing target: `npx cap spm-migration-assistant` (with capacitor 7.4.0+).
You can find more info in the official [capacitor docs](https://capacitorjs.com/docs/ios/spm).
## Android setup
- `ionic start my-cap-app --capacitor`
- `cd my-cap-app`
- `mkdir www && touch www/index.html`
- `npx cap add android`
- `npm install --save @capacitor-community/fcm`
- `npx cap sync android` _(always do sync after a plugin 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`.
> 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.
### Variables
This plugin will use the following project variables (defined in your app's `variables.gradle` file):
- `$firebaseMessagingVersion` version of `com.google.firebase:firebase-messaging` (default: `25.0.1`)
### Prevent auto initialization
If you need to implement opt-in behavior, you can disable the auto initialization of the library by following the [Firebase docs](https://firebase.google.com/docs/cloud-messaging/android/client#prevent-auto-init).
## Example
- https://github.com/capacitor-community/fcm/tree/master/example
## License
MIT
## Contributors β¨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
