Flutter FCM Wrapper
A wrapper package for FCM REST API inspired by PyFCM
🧭 Getting started
➕ Installation
Add Flutter FCM Wrapper to your pubspec.yaml
:
dependencies:
flutter_fcm_wrapper: <latest_version>
🔑 API Token
Get your API key from your Firebase Console console.firebase.google.com/u/0/
- Go to your Firebase Project
- Go to project setting
- Go to cloud messaging
- Obtain your server key
🍎 iOS Set Up
If you are sending message to Apple client app you will need to add your APNS key to your Firebase. Read more at Set up a Firebase Cloud Messaging client app on Apple platforms
📤 Usage
🚧 Construct Flutter FCM Wrapper instance
import 'package:flutter_fcm_wrapper/flutter_fcm_wrapper.dart';
FlutterFCMWrapper flutterFCMWrapper = const FlutterFCMWrapper(
apiKey: "Your Own API Key",
enableLog: true,
enableServerRespondLog: true,
);
📄 Sending Topic Message
String result = await flutterFCMWrapper.sendTopicMessage(
topicName: "example",
title: "Example",
body: "Topic message send using Flutter FCM Wrapper",
androidChannelID: "example",
clickAction: "FLUTTER_NOTIFICATION_CLICK"
);
🪙 Sending Token Message
Map<String, dynamic> result = await
flutterFCMWrapper.sendMessageByTokenID(userRegistrationTokens: [user's token],
title: "Example",
body: "Token message send using Flutter FCM Wrapper",
androidChannelID: "example",
clickAction: "FLUTTER_NOTIFICATION_CLICK"
);
🪝 Catching Exception
try {
String result = await flutterFCMWrapper.sendTopicMessage(
topicName: "example",
title: "Example",
body: "Topic message send using Flutter FCM Wrapper",
androidChannelID: "example",
clickAction: "FLUTTER_NOTIFICATION_CLICK"
);
} on FlutterFCMWrapperInvalidDataException catch (e) {
//TODO:: Handle the error here
} on FlutterFCMWrapperRespondException catch (e) {
//TODO:: Handle the error here
}
📱 Example App
Example app includes other packages such as flutter_local_notifications and firebase_messaging, but it's not required as its being used to show the notification on the device and also to obtain user's registration token.
User is also required to set up their firebase for their project and insert their own FCM API in order for the example app to run expectedly
📑 Reference
🔔 Flutter FCM Wrapper
Type | Default Value | Nullable | Description | |
---|---|---|---|---|
apiKey | String |
- | ✅ | API Key obtained from firebase console to authenticate sender's identity |
enableLog | bool |
false |
❌ | Enable to log error thrown and message delivery status |
enableServerRespondLog | bool |
false |
❌ | Enable to log raw header and body respond from the server |
📄 Topic Message
Type | Default Value | Nullable | Description | |
---|---|---|---|---|
topicName | String |
- | ✅ | The topic you wants to send this message to |
condition | String |
- | ✅ | Logic expression that determine which topic you want to send this message to |
⚠️ Warning
- FlutterFCMWrapperInvalidDataException will be thrown if
topicName
andcondition
is being provided at the same time - FlutterFCMWrapperInvalidDataException will be thrown if
topicName
andcondition
is not being provided at the same time
🪙 Token Message
Type | Default Value | Nullable | Description | |
---|---|---|---|---|
userRegistrationTokens | List<String> |
- | ❌ | List of user's registration tokens that you want to send this message to |
⚠️ Warning
- FlutterFCMWrapperInvalidDataException will be thrown if
userRegistrationTokens
is empty - FlutterFCMWrapperInvalidDataException will be thrown if
userRegistrationTokens
length is more than 1000
📝 Parameters
Type | Default Value | Nullable | Description | |
---|---|---|---|---|
title | String |
- | ✅ | Title of the notification |
body | String |
- | ✅ | Body of the notification |
titleLocKey | String |
- | ✅ | Key used to localize the title |
titleLocArgs | List<Map<String, String>> |
- | ✅ | Used as format specifiers for the titleLocKey |
bodyLocKey | String |
- | ✅ | Key used to localize the body |
bodyLocArgs | List<Map<String, String>> |
- | ✅ | Used as format specifiers for the bodyLocKey |
subtitle | String |
- | ✅ | Subtitle of the notification |
sound | String |
- | ✅ | The sound to be play when the notification is received |
icon | String |
- | ✅ | Icon of the notification |
tag | String |
- | ✅ | Use to replace the existing notification shown, if not specified new notification will be created for each request |
color | String |
- | ✅ | The notification's icon color |
imageUrl | String |
- | ✅ | An Url which will be download and displayed on the notification |
badge | int |
- | ✅ | Badge count for launchers |
clickAction | String |
- | ✅ | The action that happen when user click on the notification |
androidChannelID | String |
- | ✅ | Android notification's channel id |
isDataMessage | bool |
false |
❌ | If set to true, the notification send won't be shown or have any sound |
⚠️ Warning
- FlutterFCMWrapperInvalidDataException will be thrown if
title
andtitleLocKey
is provided at the same time - FlutterFCMWrapperInvalidDataException will be thrown if
body
andbodyLocKey
is provided at the same time - FlutterFCMWrapperInvalidDataException will be thrown if other parameters is provided and
isDataMessage
is set to true at the same time
😵 Exceptions
Reason | Example Message | |
---|---|---|
FlutterFCMWrapperInvalidDataException | This error will be thrown if invalid parameters is provided | At least 1 registration token should be provided |
FlutterFCMWrapperRespondException | This error will be thrown if server responds error | Authentication error, invalid key might be provided |
🔗 Useful Links
🤝 Contributing
Feel free to open new pull request for contributions.
If it is a major or breaking changes it is recommended to open it as an issue to discuss it.
🐛 Bugs
If any bugs has been found feel free to open an issue to discuss it.
📃 License
MIT