firebase-cloud-messenger

KO | EN

gitlite — search

#python #react #ai #llm #android #rust #linux #docker #nodejs #windows #kubernetes #awesome-list #security #openai

firebase-cloud-messenger

(★ 11)

An open-source Flutter application designed to streamline FCM testing using the modern HTTP v1 API. It simplifies OAuth 2.0 authentication via Service Account (.json), manages device tokens, and allows real-time payload debugging on macOS, Windows, and Mobile.

firebase-cloud-messenger 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Firebase Cloud Messager

> 📥 **Downloads**
>
> Download the latest pre-built desktop installers from the project's Releases page. Choose the package that matches your platform:
>
> - **macOS** — [Download macOS ZIP](https://github.com/az-coder-123/firebase-cloud-messenger/blob/main/release/macos/fcmessager.zip)
> - **Windows** — [Download Windows ZIP](https://github.com/az-coder-123/firebase-cloud-messenger/blob/main/release/windows/fcmessager.zip)
>
> If installers are not available, build from source: `flutter build macos` or `flutter build windows`.

A professional cross-platform Flutter application for testing Firebase Cloud Messaging (FCM) push notifications using the **HTTP v1 API**. Optimized for desktop platforms (macOS, Windows, Linux) with full support for device tokens and topic messaging.

## Overview

Firebase Cloud Messager is a developer tool that replaces the deprecated Legacy FCM API with a modern HTTP v1 implementation. It provides an intuitive interface for developers to:

- Import and manage Firebase service accounts
- Compose and send FCM messages with full payload control
- Manage device tokens (address book)
- Send messages to topics for broadcast messaging
- Track message history and responses
- Debug with raw JSON request/response inspection

## Features

### 🔐 Service Account Management
- Import Firebase `service-account.json` via drag & drop or file picker
- Automatic OAuth 2.0 token generation using `googleapis_auth`
- Secure credential handling with validation
- Save and manage multiple service accounts locally
- Quick account switching capability

### 📱 Device Token Management (Address Book)
- Add, edit, and delete device tokens
- Organize tokens with custom device names
- Search and filter functionality
- Quick token selection when composing messages
- Platform identification for debugging

### ✉️ Message Composer (Device Token)
**Notification Payload:**
- Title, Body, and Image URL
- Full Material 3 UI with real-time preview

**Data Payload:**
- Dynamic key-value pairs for background message handling
- Add/remove fields on the fly

**Platform-Specific Options:**
- **Android:** Channel ID, Priority, Notification settings
- **iOS:** Badge number, Sound configuration

### 📢 Topic Messaging
- Send messages to multiple devices via topics
- Topic-based message composition
- Simplified payload configuration for topic broadcasts
- Topic history tracking and resend capability

### 📊 Message History
- Auto-save all sent messages (success and failures)
- Detailed view with full request/response
- Re-send or edit messages from history
- Filter by success/failure status
- Clear history functionality

### 🎨 Adaptive UI
- **Desktop:** Optimized split-view layout with sidebar navigation
- Full Material 3 support with adaptive theming
- Light and dark theme support
- Responsive design for different window sizes
- Professional UI components with proper spacing and typography

**Developer Features:**
- Raw JSON request/response preview
- Message ID and status code display
- Comprehensive error reporting
- OAuth 2.0 token inspection and debug info

### 📸 Screenshots

Here are some screenshots of the application in action.

#### Compose Message
![Compose Message](https://raw.githubusercontent.com/az-coder-123/firebase-cloud-messenger/main/screenshots/01-compose-message.png)
A view of the message composer where you can build Notification and Data payloads with a real-time preview.

#### Send to Topic
![Send to Topic](https://raw.githubusercontent.com/az-coder-123/firebase-cloud-messenger/main/screenshots/02-send-to-topic.png)
Send messages to topics with topic selector, targeting options, and advanced settings.

#### Device Tokens (Address Book)
![Device Tokens](https://raw.githubusercontent.com/az-coder-123/firebase-cloud-messenger/main/screenshots/03-device-tokens.png)
Manage your device tokens: add, edit, and quickly select tokens when composing messages.

#### Message History
![History](https://raw.githubusercontent.com/az-coder-123/firebase-cloud-messenger/main/screenshots/04-history.png)
Inspect sent messages with status, message IDs, and full raw request/response payload for debugging.

#### Settings & Service Account
![Settings](https://raw.githubusercontent.com/az-coder-123/firebase-cloud-messenger/main/screenshots/05-settings.png)
Import and manage `service-account.json`, view authentication status, and manage multiple accounts.

## Tech Stack

| Category | Technology | Version |
|----------|-----------|---------|
| **Framework** | Flutter | 3.10.7+ |
| **Dart** | SDK | 3.10.7+ |
| **State Management** | flutter_riverpod | ^2.6.1 |
| **Networking** | dio | ^5.8.0+1 |
| **Authentication** | googleapis_auth | ^1.6.0 |
| **Local Storage** | hive, hive_flutter | ^2.2.3, ^1.1.0 |
| **File Operations** | file_picker, desktop_drop | ^10.1.6, ^0.5.0 |
| **Window Management** | window_manager | ^0.4.0 |
| **Utilities** | equatable, uuid, intl, path_provider | ^2.0.7, ^4.5.1, ^0.20.2, ^2.1.5 |
| **UI** | Material 3 | Built-in |

## Project Structure

```
lib/
├── main.dart                          # App entry point & initialization
├── app.dart                           # Root app widget & theme configuration
├── core/
│   ├── constants/
│   │   ├── api_constants.dart         # FCM API endpoints & headers
│   │   └── app_constants.dart         # UI constants & app config
│   ├── errors/
│   │   └── exceptions.dart            # Custom exception classes
│   └── utils/
│       └── file_utils.dart            # File I/O utilities
├── data/
│   ├── models/                        # Data models & entities
│   │   ├── service_account.dart       # Firebase service account from JSON
│   │   ├── saved_service_account.dart # Persisted account metadata
│   │   ├── fcm_message.dart           # Device message payload structure
│   │   ├── fcm_topic.dart             # Topic message payload structure
│   │   ├── device_token.dart          # Device token with metadata
│   │   └── message_history.dart       # Message send history entry
│   └── services/                      # Repository & business logic
│       ├── fcm_auth_service.dart      # OAuth 2.0 token management
│       ├── fcm_message_service.dart   # HTTP v1 API messaging
│       ├── device_tokens_repository.dart
│       ├── service_account_repository.dart
│       ├── history_repository.dart
│       └── topics_repository.dart
└── presentation/
    ├── providers/                     # Riverpod state providers
    │   ├── auth_provider.dart
    │   ├── app_startup_provider.dart
    │   ├── current_account_provider.dart
    │   ├── device_tokens_provider.dart
    │   ├── fcm_provider.dart
    │   ├── saved_accounts_provider.dart
    │   ├── saved_history_provider.dart
    │   ├── saved_topics_provider.dart
    │   └── topic_message_provider.dart
    ├── screens/                       # UI screens
    │   ├── home_screen.dart
    │   ├── compose_screen.dart        # Device token messaging UI
    │   ├── topic_compose_screen.dart  # Topic messaging UI
    │   ├── history_screen.dart
    │   ├── tokens_screen.dart
    │   ├── settings_screen.dart
    │   └── saved_accounts_dialog.dart
    └── widgets/
        └── account_quick_actions.dart
```

## Getting Started

### Prerequisites

- Flutter SDK: 3.10.7 or higher
- Dart SDK: 3.10.7 or higher (included with Flutter)
- Firebase project with service account credentials
- Desktop development environment (macOS, Windows, or Linux)

### Installation

1. **Clone the repository:**
   ```bash
   # HTTPS
   git clone https://github.com/az-coder-123/firebase-cloud-messenger.git

# OR (SSH)
   git clone git@github.com:az-coder-123/firebase-cloud-messenger.git

cd firebase-cloud-messenger
   ```

2. **Install dependencies:**
   ```bash
   flutter pub get
   ```

3. **Get Flutter devices:**
   ```bash
   flutter devices
   ```

4. **Run the application:**
   ```bash
   # macOS (recommended)
   flutter run -d macos

# Windows
   flutter run -d windows

# Linux
   flutter run -d linux
   ```

### Getting Your Service Account

1. Go to [Firebase Console](https://console.firebase.google.com)
2. Select your project
3. Navigate to **Project Settings > Service Accounts**
4. Click **Generate New Private Key**
5. Save the JSON file
6. Import the file using the Settings screen in the app

## Usage

### 1. Configure Service Account
- Open **Settings** tab
- Click the drop zone or browse to select your `service-account.json`
- The app will validate the credentials and extract project information
- Optionally save the account for future sessions

### 2. Manage Device Tokens (Address Book)
- Navigate to **Tokens** tab
- Click **Add** to register a new device token
- Enter a device name for identification
- Paste the FCM registration token
- Save the device for quick access

### 3. Send Message to Device Token
- Go to **Compose** tab
- Select a device token from your saved list (Address Book)
- Configure notification payload:
  - Title and body text
  - Image URL (optional)
- Add custom data key-value pairs (optional)
- Set platform-specific options if needed
- Click **Send Message**
- View real-time response with message ID and status

### 4. Send Message to Topic
- Go to **Topic** tab
- Enter a topic name
- Configure notification and data payloads
- Click **Send to Topic**
- Messages will be delivered to all devices subscribed to the topic

### 5. View Message History
- Check **History** tab for all sent messages (devices and topics)
- Click on any message to view full details including:
  - Request JSON payload sent to FCM API
  - Response from Firebase (message ID, error details)
  - Timestamp and status
- Use history for debugging and re-sending messages

## Architecture

### Service Layer (Data)
The application uses clean architecture with clear separation of concerns:

**Core Services:**
- **FcmAuthService:** Handles OAuth 2.0 authentication using `googleapis_auth`
  - Loads service account credentials from JSON
  - Generates short-lived access tokens (1 hour)
  - Automatic token caching and refresh
  - Credential validation and error handling

- **FcmMessageService:** Manages FCM HTTP v1 API interactions
  - Constructs proper FCM message payloads for devices and topics
  - Sends messages via HTTPS to Firebase API
  - Handles errors with detailed error reporting
  - Parses and caches responses

**Repository Pattern:**
- **ServiceAccountRepository:** Manages service account persistence in Hive
- **DeviceTokensRepository:** CRUD operations for device tokens
- **HistoryRepository:** Stores and retrieves message send history
- **TopicsRepository:** Manages topic subscriptions and history

### State Management (Presentation)
Riverpod providers manage application state with reactive updates:

- `authProvider` - Service account authentication and token management
- `currentAccountProvider` - Currently selected service account
- `deviceTokensProvider` - Device tokens list with filtering
- `savedTopicsProvider` - Saved topics for quick access
- `fcmProvider` - FCM message sending state and history
- `topicMessageProvider` - Topic-based messaging state
- `savedAccountsProvider` - Persisted service accounts
- `appStartupProvider` - App initialization and startup logic

### Data Models
Equatable-based immutable models ensure type safety and equality:

- `ServiceAccount` - Firebase service account credentials from JSON
- `SavedServiceAccount` - Persisted account metadata with display info
- `FcmMessage` - Complete device message payload structure
- `FcmTopic` - Topic message payload and metadata
- `DeviceToken` - Device token with platform and display name
- `MessageHistory` - Message send history entry with request/response

## Supported Platforms

| Platform | Status | Notes |
|----------|--------|-------|
| **macOS** | ✅ Fully Supported | Optimized desktop experience, native window management |
| **Windows** | ✅ Fully Supported | Full desktop feature parity with macOS |
| **Linux** | ✅ Fully Supported | GTK integration, native window management |
| **iOS** | ⚠️ Partial* | UI functional but FCM testing limited without Firebase setup |
| **Android** | ⚠️ Partial* | UI functional but FCM testing limited without Firebase setup |
| **Web** | ❌ Not Recommended | Requires backend CORS proxy for OAuth 2.0, not intended for web |

*Mobile builds are possible but the application is designed and optimized for desktop platforms. Desktop platforms are the primary target for FCM message testing and development.

## FCM HTTP v1 API

This application uses the modern Firebase Cloud Messaging HTTP v1 API:

**Endpoint:** `https://fcm.googleapis.com/v1/projects/{project_id}/messages:send`

**Authentication:** OAuth 2.0 with service account credentials

**Message Format:**
```json
{
  "message": {
    "token": "device_registration_token",
    "notification": {
      "title": "Hello",
      "body": "This is a notification",
      "image": "https://example.com/image.png"
    },
    "data": {
      "key1": "value1",
      "key2": "value2"
    },
    "android": { },
    "apns": { },
    "webpush": { }
  }
}
```

For detailed API documentation, see [FCM REST API Reference](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages)

## Development

### Running Analysis
```bash
flutter analyze
```

### Running Tests
```bash
flutter test
```

### Building for Release
```bash
# macOS
flutter build macos

# Windows
flutter build windows

# Linux
flutter build linux
```

## Code Quality

This project adheres to the guidelines defined in `AGENTS.md`:

✅ **Clean Code Principles**
- Clear, readable code with proper naming conventions
- Single Responsibility Principle applied throughout
- Minimal code duplication with proper abstraction

✅ **Flutter & Dart Best Practices**
- Latest Dart patterns and null safety
- Proper use of async/await patterns
- Efficient widget rebuilds with Riverpod
- Type-safe implementations throughout

✅ **Stable Dependencies**
- Only actively maintained packages
- No deprecated APIs or patterns
- Latest stable versions verified

✅ **Analysis & Testing**
- `flutter analyze` passes with no issues
- Comprehensive error handling
- Widget tests included in test suite

## Troubleshooting

### Service Account Import Issues
- Ensure the JSON file is valid and from Firebase Console
- Check that the account has FCM permissions
- Verify the `private_key` is properly formatted (with `\n` characters)

### macOS Entitlement Errors
- **File Picker:** If you see an error mentioning `ENTITLEMENT_NOT_FOUND` when selecting a file on macOS, add the following entitlements to your macOS Runner entitlements (e.g., `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`):
  ```xml
  <key>com.apple.security.files.user-selected.read-only</key>
  <true/>
  <key>com.apple.security.files.user-selected.read-write</key>
  <true/>
  ```
  After updating entitlements, rebuild the app. This grants permission for user-selected open/save dialogs in sandboxed macOS builds.

- **Network Connection:** If you see errors like "Operation not permitted" or "Connection failed" when sending messages on macOS, the app is missing network entitlements. Add the following to the same entitlements files:
  ```xml
  <key>com.apple.security.network.client</key>
  <true/>
  ```
  This entitlement is required for outbound HTTPS connections to Google's OAuth2 servers (`oauth2.googleapis.com:443`). After updating entitlements, rebuild the app with `flutter run -d macos` or `flutter build macos`.

### Message Send Failures
- Check network connectivity
- Verify the device token is valid and active
- Ensure the target device has the app installed
- Check the response JSON for detailed error messages

### Token Refresh Issues
- Service account credentials may be revoked
- Re-import the service account file
- Check Firebase project quotas and limits

## Contributing

Follow the guidelines in `AGENTS.md` for code contributions:
- Write clear, maintainable code
- Follow Single Responsibility Principle
- Use type-safe patterns
- Run `flutter analyze` before committing
- Keep comments in English and professional

## License

This project is provided as-is for development and testing purposes.

## Resources

- [Firebase Cloud Messaging Documentation](https://firebase.google.com/docs/cloud-messaging)
- [FCM HTTP v1 API Reference](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages)
- [Flutter Documentation](https://flutter.dev/docs)
- [Riverpod Documentation](https://riverpod.dev)
- [googleapis_auth Package](https://pub.dev/packages/googleapis_auth)

---

**Version:** 1.0.0  
**Last Updated:** January 2026  
**Flutter Version:** 3.10.7+

firebase-cloud-messenger

firebase-cloud-messenger 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

firebase-cloud-messenger

firebase-cloud-messenger 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README