firebase_fcm 0.0.2

A Flutter package to construct and dispatch Firebase Cloud Messaging (FCM) v1 notifications from Dart using Service Account OAuth2 credentials.

firebase_fcm

A lightweight, modern, and reliable Flutter package to easily dispatch Firebase Cloud Messaging (FCM) v1 notifications directly from Dart code using Google Cloud Service Account credentials.

No need to spin up a custom backend or Cloud Function just to test or trigger push notifications.

Features

• FCM v1 API Support: Adheres to the modern Google Firebase Cloud Messaging v1 HTTP standard.
• Auto OAuth2 Token Exchange: Seamlessly handles Service Account credentials exchange to retrieve authorization headers.
• Multi-Destination Delivery: Easily switch between targeting individual device registration tokens or broadcast topic paths.
• Custom Key-Value Payloads: Support for passing optional custom data maps alongside default notification bodies.
• Resource Leak Protection: Guarantees HTTP connections are properly closed at the native socket level using safe try-finally blocks.
• Input Assertions: Parameter validations to catch configuration issues before network requests are dispatched.

Getting started

1. Add dependency

In your pubspec.yaml:

dependencies:
  firebase_fcm:
    path: path_to_package # or use pub version once published

Run flutter pub get.

2. Obtain Service Account JSON

To send messages using this package, you need a Google Service Account credentials file:

1. Go to your Firebase Console.
2. Click the gear icon next to Project Overview and select Project settings.
3. Navigate to the Service accounts tab.
4. Click Generate new private key, then download the JSON file.
5. Store the JSON contents securely (do not commit this file to public version control!).

---

Usage

Import the package:

import 'package:firebase_fcm/firebase_fcm.dart';

Send to a Single Device Token

try {
  await sendFcmNotification(
    title: 'Hello from Flutter!',
    body: 'This notification was triggered directly from Dart.',
    token: 'USER_REGISTRATION_TOKEN_HERE',
    serviceAccountJson: myServiceAccountMap,
    isDebug: true, // prints access token exchange and API response codes in console
  );
} catch (e) {
  print('Failed to send FCM: $e');
}

Broadcast to a Topic

try {
  await sendFcmNotification(
    title: 'Announcing Update!',
    body: 'Subscribe to remain informed!',
    topicPath: 'news_updates',
    sendToTopic: true,
    serviceAccountJson: myServiceAccountMap,
  );
} catch (e) {
  print('Failed to broadcast: $e');
}

Send Custom Key-Value Data

await sendFcmNotification(
  title: 'New Chat Message',
  body: 'You have a message from seller.',
  token: 'TOKEN',
  serviceAccountJson: myServiceAccountMap,
  data: {
    'click_action': 'FLUTTER_NOTIFICATION_CLICK',
    'chatId': '12345',
    'type': 'chat',
  },
);

---

Example Project

An interactive example app showcasing all features (including credentials loading, token/topic toggles, and dynamic custom data key-values) is located in the /example directory. Run it to test your service account keys directly in a simulated UI dashboard.

License

This project is licensed under the MIT License - see the LICENSE file for details.