Firebase Setup for Push Notifications

Firebase is required for push notifications in Vyral. This guide will walk you through setting up Firebase for your social media platform.

Prerequisites

• A Google account
• Admin access to your Vyral installation
• Basic knowledge of JSON format

Step 1: Create a Firebase Project

1. Go to the Firebase Console
2. Click "Create a project"
3. Enter your project name (e.g., "vyral-app")
4. Choose whether to enable Google Analytics (recommended)
5. Select your Google Analytics account if enabled
6. Click "Create project"

Step 2: Enable Firebase Cloud Messaging (FCM)

1. In your Firebase project dashboard, go to Project Settings (gear icon)
2. Navigate to the "Cloud Messaging" tab
3. Under "Firebase Cloud Messaging API (V1)", make sure it's enabled
4. If not enabled, click "Enable" and follow the prompts

Step 3: Generate Service Account Key

1. In Firebase Console, go to Project Settings → "Service accounts" tab
2. Click "Generate new private key"
3. A dialog will appear with a warning - click "Generate key"
4. A JSON file will be downloaded to your computer
5. IMPORTANT: Keep this file secure and never share it publicly

The downloaded JSON will look like this:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "[email protected]",
  "client_id": "123456789",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-xxx%40your-project-id.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

Step 4: Configure Firebase in Vyral Admin

Method 1: Using Admin Panel (Recommended)

1. Log in to your Vyral admin panel
2. Navigate to "Settings" → "System Settings"
3. Click on the "Push Notifications" tab
4. Enable "Push Notifications" toggle
5. Enter your Firebase Project ID (from the JSON file)
6. Copy the entire contents of your service account JSON file
7. Paste it into the "Firebase Service Account Key (JSON)" field
8. Click "Test Configuration" to verify the setup
9. If successful, click "Save Settings"

Method 2: Using Environment Variables

If you prefer to use environment variables instead of storing in the database:

1. Place your service account JSON file on the server
2. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable:

   export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

3. Restart your Vyral backend service

Step 5: Configure Web App (for PWA notifications)

Add Firebase to Your Web App

1. In Firebase Console, go to Project Settings → "General" tab
2. Scroll down to "Your apps" section
3. Click the web icon (</>) to add a new web app
4. Enter an app nickname (e.g., "Vyral Web")
5. Check "Also set up Firebase Hosting for this app" if you want
6. Click "Register app"
7. Copy the Firebase configuration object

Update Frontend Configuration

Add the Firebase configuration to your frontend environment variables:

# Frontend .env.local
NEXT_PUBLIC_FIREBASE_API_KEY=your-api-key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project-id.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789
NEXT_PUBLIC_FIREBASE_APP_ID=1:123456789:web:abcdef

Step 6: Generate Web Push Certificates (Optional)

For web push notifications, you may want to generate VAPID keys:

1. In Firebase Console, go to Project Settings → "Cloud Messaging" tab
2. Scroll down to "Web configuration"
3. Click "Generate key pair" under "Web push certificates"
4. Copy the generated key pair
5. Add to your frontend configuration:

   NEXT_PUBLIC_FIREBASE_VAPID_KEY=your-vapid-key

Step 7: Test Push Notifications

Test from Admin Panel

1. Go to Admin Panel → "Push Notifications"
2. Make sure push notifications are enabled
3. The system will automatically send test notifications for:
   • New likes on posts
   • New replies/comments
   • New follows
   • Direct messages
   • Mentions

Test from Firebase Console

1. In Firebase Console, go to "Messaging"
2. Click "Send your first message"
3. Enter a notification title and text
4. Select your app under "Target"
5. Click "Review" and then "Publish"

Notification Types Supported

Vyral supports the following push notification types:

Advanced Configuration

Custom Notification Sounds

1. Add custom sound files to your web app's public/sounds/ directory
2. Update the Firebase service configuration in the backend
3. Modify the notification payload to include custom sounds

Topic-Based Notifications

Vyral uses Firebase topics for efficient notification delivery:

• User-specific topics: user_{userID} for individual notifications
• Community topics: community_{communityID} for community updates
• General topics: all_users for system-wide announcements

Push Notification Analytics

Firebase automatically provides analytics for push notifications:

1. Go to Firebase Console → "Analytics" → "Events"
2. Look for notification-related events
3. Monitor delivery rates and user engagement

Security Best Practices

1. Secure Service Account Key: Never commit your service account JSON to version control
2. Environment Variables: Use environment variables for sensitive configuration
3. Key Rotation: Regularly rotate your service account keys
4. Firestore Security Rules: Configure proper security rules if using Firestore
5. HTTPS Only: Ensure your web app is served over HTTPS for push notifications

Troubleshooting

Common Issues

1. "Permission denied": Check service account permissions
2. "Invalid project ID": Verify project ID matches Firebase console
3. "Authentication failed": Ensure service account JSON is valid
4. "No registration token": User needs to grant notification permission

Debug Steps

1. Check backend logs for Firebase initialization errors
2. Verify service account JSON format and validity
3. Test Firebase connection using the admin panel test feature
4. Check browser console for frontend Firebase errors
5. Verify user notification permissions are granted

Log Examples

Successful Firebase initialization:

Firebase service initialized successfully (using default credentials)

Push notification sent:

📱 Mobile push notifications sent. Success: 1, Failure: 0
🌐 Topic-based push notification sent successfully: projects/your-project-id/messages/0:123456
✅ Push notifications sent successfully (mobile: 1, topic: 1)

Environment Variables Reference

Backend

# Optional: Path to service account JSON file
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

# Alternative: Service account JSON as environment variable
FIREBASE_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'

Frontend

NEXT_PUBLIC_FIREBASE_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXX
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=123456789
NEXT_PUBLIC_FIREBASE_APP_ID=1:123456789:web:abcdefghijklmnop
NEXT_PUBLIC_FIREBASE_VAPID_KEY=BNxXXXXXXXXXXXXXXXXXXXXXXXXXXX

Support

If you encounter issues with Firebase setup:

1. Check the troubleshooting section above
2. Review Firebase Console logs
3. Test the configuration using the admin panel
4. Contact support with specific error messages and logs

Next Steps: After completing Firebase setup, configure SMTP Settings for email notifications or proceed to Storage Configuration for file uploads.