flutter_fcm_wrapper 0.0.1 flutter_fcm_wrapper: ^0.0.1 copied to clipboard
A Flutter wrapper package for FCM REST API to make it easier to send FCM from Flutter.
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 https://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] and [condition] is being provided at the same time
- [FlutterFCMWrapperInvalidDataException] will be thrown if [topicName] and [condition] 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] and [titleLocKey] is provided at the same time
- [FlutterFCMWrapperInvalidDataException] will be thrown if [body] and [bodyLocKey] 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