This is a full-stack Meteor application using React for the frontend and Cordova for mobile deployment. It integrates Firebase Cloud Messaging (FCM) to enable push notifications, using the @havesource/cordova-plugin-push
plugin for mobile platforms.
sequenceDiagram
participant User as User
participant PhoneApp as Phone App
participant MeteorServer as Meteor Server / Push Gateway
participant BashScript as Bash Script
User->>PhoneApp: Allow Push Notifications
PhoneApp->>MeteorServer: Register with FCM Token
BashScript->>MeteorServer: Send Push Notification via curl
MeteorServer->>PhoneApp: Forward Push Notification
PhoneApp->>User: Display Notification (Foreground/Background)
User-->>PhoneApp: Interact with Notification (Ok/Cancel)
PhoneApp-->>MeteorServer: Notify User Response (Ok/Cancel)
MeteorServer-->>BashScript: Return Response (Ok/Cancel)
The main interface of the application where users can interact with the authentication features.
Example of how push notifications appear on mobile devices.
git clone https://github.com/mieweb/mieweb_auth_app
cd mieweb_auth_app
Before setting up the application, ensure you have the following tools installed and properly configured:
- Node.js & npm - JavaScript runtime and package manager
- Meteor - Full-stack JavaScript platform (see Meteor Installation Docs)
- Android Studio - Including Android SDK and adb tools for Android development
- Xcode - Required for iOS builds (Mac only)
- Java JDK 17 - Java Development Kit version 17
- Java Runtime Environment (JRE) - See Java Install Docs
- Gradle - Build automation tool (see Gradle Installation Docs)
Configure the following environment variables in your ~/.zshrc
or ~/.bash_profile
:
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH=$JAVA_HOME/bin:$PATH
export ANDROID_HOME=/path/to/your/android/sdk
For development with live reload and debugging capabilities:
meteor npm run start-dev
What this command does:
- Creates a secure tunnel using the Magic Box tool
- Prompts for YubiKey authentication to generate a secure proxy URL
- Provides a publicly accessible URL for mobile device testing
- Enables live reload and debugging features
- Eliminates the need for manual port forwarding
For production deployment:
meteor npm run start
Production considerations:
- Starts the Meteor server in production mode
- Server must be accessible via your production domain or IP address
- No tunneling or proxy setup required
- Optimized for performance and security
Firebase Cloud Messaging (FCM) is essential for push notification functionality. Follow these steps to configure Firebase for your application.
-
Create Firebase Project
- Navigate to the Firebase Console
- Create a new project or select an existing one
- Note your project ID for later configuration
-
Enable Cloud Messaging
- In your Firebase project, navigate to the Cloud Messaging section
- Enable the Cloud Messaging API
- Configure your messaging settings as needed
-
Create Platform Applications
- Create both Android and iOS applications within your Firebase project
- Follow the setup wizard for each platform
- Download the required configuration files
Download the google-services.json
configuration file and place it in the correct directory structure.
File placement: The google-services.json
file should be placed in public/android/google-services.json
Download the GoogleService-Info.plist
configuration file for iOS integration.
File placement: The GoogleService-Info.plist
file should be placed in public/ios/GoogleService-Info.plist
Important Security Notice
Never download or manually handle the Firebase Admin SDK JSON file. Instead, use the Firebase Admin SDK secret string method for secure environment variable configuration.
Platform | Configuration File | Destination Path |
---|---|---|
Android | google-services.json |
public/android/google-services.json |
iOS | GoogleService-Info.plist |
public/ios/GoogleService-Info.plist |
Note: The mobile-config.js
file automatically handles the inclusion of these configuration files in your Cordova build process.
- Access your Firebase Console
- Navigate to Project Settings → Service Accounts
- Generate a new private key
- Copy the JSON content (this is your admin SDK secret)
For production servers:
export FIREBASE_SERVICE_ACCOUNT_JSON='{"type":"service_account","project_id":"your-project-id","private_key_id":"...","private_key":"-----BEGIN PRIVATE KEY-----\n..."}'
For development environment:
- Create a file:
server/private/firebase-admin-key.json
- Add the JSON content to this file
- Ensure this file is included in your
.gitignore
- Update the reference in your
firebase.js
configuration file
Important: Always use environment variables for production deployments to maintain security.
meteor add-platform android
meteor add cordova:@havesource/cordova-plugin-push@5.0.5
Ensure your Android device is connected via USB with Developer Options and USB Debugging enabled.
meteor npm run start android-device --mobile-server=https://<your-proxy-url-or-production-domain>
Ensure you have an Android emulator created and running through Android Studio.
meteor npm run start android
meteor add-platform ios
Connect your iOS device to your Mac. This command will open Xcode where you need to manually select your device and build.
meteor npm run start ios-device --mobile-server=https://<your-proxy-url-or-production-domain>
This command opens Xcode where you can select your preferred iOS simulator.
meteor npm run start ios
Generate a production-ready Android App Bundle (AAB) for Google Play Store distribution:
meteor build output/ --architecture os.linux.x86_64 --server=https://<your-production-domain>
Build output:
- The generated
.aab
file will be located in theoutput/
directory - This file is ready for upload to Google Play Console
- No additional tunneling tools are required for production builds
Use the provided shell script to send test push notifications. Configure the script with your server details:
PUSHGATEWAY="http://localhost:3000"
RELYINGPARTY="your-username"
Run the notification script:
./send-notification.sh
{"success":false,"error":"The registration token is not a valid FCM registration token"}
{"success":true,"action":"approve"}
{"success":true,"action":"reject"}
{"success":true,"action":"timeout"}
Response meanings:
success: false
- Invalid FCM token or configuration issueaction: approve
- User approved the notificationaction: reject
- User rejected the notificationaction: timeout
- Notification timed out without user interaction
Understanding the application architecture and file organization:
Path/File | Purpose | Description |
---|---|---|
client/main.jsx |
Frontend Logic | React UI components and push notification registration |
server/main.js |
Backend Logic | Meteor server implementation and push notification handling |
mobile-config.js |
Mobile Configuration | Cordova application metadata and mobile-specific settings |
public/android/ |
Android Assets | Android-specific configuration files and resources |
public/ios/ |
iOS Assets | iOS-specific configuration files and resources |
server/private/ |
Server Secrets | Private configuration files (excluded from version control) |
The project includes automated CI/CD pipelines:
- File:
.github/workflows/android-build.yml
- Purpose: Automated Android application building and testing
- Triggers: Push to main branch, pull requests
- File:
.github/workflows/build-server-on-release.yml
- Purpose: Automated server bundling for production releases
- Triggers: Release creation, tagged commits
Required GitHub Secrets:
FIREBASE_SERVICE_ACCOUNT_JSON
- Your Firebase Admin SDK secret for secure CI usage
Setup Instructions:
- Navigate to your GitHub repository settings
- Go to Secrets and Variables → Actions
- Add the required secrets with their respective values
- Ensure workflows have appropriate permissions
- Never commit Firebase Admin SDK JSON files to version control
- Use environment variables for all sensitive configuration
- Implement proper
.gitignore
and.meteorignore
rules - Regularly rotate Firebase service account keys
- Restrict Firebase project access to necessary team members only
- Implement proper authentication and authorization
- Use HTTPS for all production communications
- Regularly audit and update dependencies
- Keep development and production environments separated
- Use different Firebase projects for different environments
- Implement proper logging without exposing sensitive data
- Regular security audits of the codebase
Firebase Connection Issues:
- Verify configuration files are in correct locations
- Check Firebase project settings and API enablement
- Ensure environment variables are properly set
Mobile Build Issues:
- Verify all prerequisites are installed and properly configured
- Check platform-specific SDK versions
- Ensure proper signing certificates for iOS builds
Push Notification Issues:
- Verify FCM tokens are being properly generated and stored
- Check Firebase Cloud Messaging configuration
- Test with different notification payload formats
If you encounter issues or need assistance:
- Check the documentation - Review this README and official Meteor/Firebase documentation
- Search existing issues - Look through GitHub issues for similar problems
- Create a new issue - Provide detailed information about your problem
- Submit pull requests - Contribute improvements and fixes
We welcome contributions to improve this application. Please:
- Fork the repository
- Create a feature branch
- Follow existing code style and conventions
- Add appropriate tests and documentation
- Submit a pull request with a clear description