sojorn/ANDROID_FCM_TROUBLESHOOTING.md

Android FCM Notifications - Troubleshooting Guide

Issue: Chat notifications work on Web but not Android

Current Status

• ✅ Web notifications working
• ✅ Android has google-services.json configured
• ✅ Android has FCM plugin in build.gradle.kts
• ✅ Android has notification permissions in AndroidManifest.xml
• ❓ Android FCM token registration status unknown

---

Diagnostic Steps

Step 1: Check Android Logs for FCM Token

Run the Android app with logging:

cd c:\Webs\Sojorn
.\run_dev.ps1

In Android Studio or terminal, check logcat:

adb logcat | findstr "FCM"

Look for these log messages:

[FCM] Initializing for platform: android
[FCM] Permission status: AuthorizationStatus.authorized
[FCM] Requesting token...
[FCM] Token registered (android): eXaMpLe...
[FCM] Syncing token with backend...
[FCM] Token synced with Go Backend successfully
[FCM] Initialization complete

Step 2: Check for Common Errors

Error: "Token is null after getToken()"

Cause: Firebase not properly initialized or google-services.json mismatch

Fix:

1. Verify google-services.json package name matches:

   "package_name": "com.gosojorn.app"
   

2. Check build.gradle.kts has:

   applicationId = "com.gosojorn.app"
   

3. Rebuild: flutter clean && flutter pub get && flutter run

Error: "Permission denied"

Cause: User denied notification permission or Android 13+ permission not requested

Fix:

1. Check AndroidManifest.xml has:

   <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
   

2. On Android 13+, permission must be requested at runtime
3. Uninstall and reinstall app to re-trigger permission prompt

Error: "Failed to initialize notifications"

Cause: Firebase plugin not properly initialized

Fix:

1. Check android/build.gradle (project level) has:

   dependencies {
       classpath 'com.google.gms:google-services:4.4.0'
   }
   

2. Check android/app/build.gradle.kts has:

   plugins {
       id("com.google.gms.google-services")
   }
   

---

Step 3: Verify Backend Receives Token

Check Database for Android Tokens

SSH to server:

ssh -i "C:\Users\Patrick\.ssh\mpls.pem" patrick@194.238.28.122

Query database:

sudo -u postgres psql sojorn

-- Check for Android tokens
SELECT 
    user_id, 
    platform, 
    LEFT(fcm_token, 30) as token_preview, 
    created_at 
FROM public.fcm_tokens 
WHERE platform = 'android'
ORDER BY created_at DESC 
LIMIT 5;

Expected output:

user_id                              | platform | token_preview                  | created_at
-------------------------------------+----------+--------------------------------+-------------------
5568b545-5215-4734-875f-84b3106cd170 | android  | eXaMpLe_android_token_here...  | 2026-01-29 06:00

If no Android tokens:

• Token registration failed
• Token sync to backend failed
• Check Android logs for errors

---

Step 4: Test Push Notification Manually

Send Test Notification from Server

# Get an Android FCM token from database
sudo -u postgres psql sojorn -c "SELECT fcm_token FROM public.fcm_tokens WHERE platform = 'android' LIMIT 1;"

The Go backend automatically sends notifications when:

• Someone sends you a chat message
• Someone follows you
• Someone accepts your follow request

Test by sending a chat message:

1. Open app on Android device
2. Have another user (or web browser) send you a message
3. Check Android logs for: [FCM] Foreground message received

---

Step 5: Check Notification Channel (Android 8+)

Android 8+ requires notification channels. Check strings.xml:

File: android/app/src/main/res/values/strings.xml

<resources>
    <string name="default_notification_channel_id">chat_messages</string>
    <string name="default_notification_channel_name">Chat messages</string>
</resources>

Referenced in AndroidManifest.xml:

<meta-data
    android:name="com.google.firebase.messaging.default_notification_channel_id"
    android:value="@string/default_notification_channel_id" />

---

Common Issues & Solutions

Issue 1: "google-services.json not found"

Symptoms:

• Build fails with "File google-services.json is missing"
• FCM token is null

Solution:

# Verify file exists
ls sojorn_app/android/app/google-services.json

# If missing, download from Firebase Console:
# https://console.firebase.google.com/project/sojorn-a7a78/settings/general
# Click "Add app" > Android > Download google-services.json

Issue 2: Package name mismatch

Symptoms:

• FCM token is null
• No errors in logs

Solution: Verify all package names match:

1. google-services.json: "package_name": "com.gosojorn.app"
2. build.gradle.kts: applicationId = "com.gosojorn.app"
3. AndroidManifest.xml: <manifest xmlns:android="..."> (no package attribute needed)

Issue 3: Notification permission not granted

Symptoms:

• Log shows: [FCM] Permission status: AuthorizationStatus.denied
• No token generated

Solution:

# Uninstall app
adb uninstall com.gosojorn.app

# Reinstall and allow notification permission when prompted
flutter run

Issue 4: Token generated but not synced to backend

Symptoms:

• Log shows: [FCM] Token registered (android): ...
• Log shows: [FCM] Sync failed: ...
• No token in database

Solution: Check API endpoint exists:

# On server
sudo journalctl -u sojorn-api -f | grep "notifications/device"

Verify Go backend has the endpoint:

// Should be in cmd/api/main.go
authorized.POST("/notifications/device", settingsHandler.RegisterFCMToken)

---

Comparison: Web vs Android

Web (Working ✅)

• Uses VAPID key for authentication
• Service worker handles background messages
• Token format: d2n2ELGKel7yzPL3wZLGSe:APA91b...

Android (Troubleshooting ❓)

• Uses google-services.json for authentication
• Native Android handles background messages
• Token format: Different from web, longer
• Requires runtime permission on Android 13+

---

Debug Checklist

Run through this checklist:

• google-services.json exists in android/app/
• Package name matches in all files
• build.gradle.kts has google-services plugin
• AndroidManifest.xml has POST_NOTIFICATIONS permission
• App has notification permission granted
• Android logs show FCM initialization
• Android logs show token generated
• Token appears in database fcm_tokens table
• Backend logs show notification being sent
• Android logs show notification received

---

Next Steps

1. Run the app with enhanced logging:

   cd c:\Webs\Sojorn
   .\run_dev.ps1
   

2. Monitor Android logs:

   adb logcat | findstr "FCM"
   

3. Look for the specific log messages:

   • [FCM] Initializing for platform: android
   • [FCM] Token registered (android): ...
   • [FCM] Token synced with Go Backend successfully

4. If token is null:

   • Check google-services.json is correct
   • Verify package name matches
   • Rebuild: flutter clean && flutter pub get && flutter run

5. If token generated but notifications not received:

   • Check database has the token
   • Send a test message
   • Check backend logs for push notification being sent
   • Verify Android device has internet connection

---

Files to Check

Android Configuration

• sojorn_app/android/app/google-services.json - Firebase config
• sojorn_app/android/app/build.gradle.kts - Build configuration
• sojorn_app/android/app/src/main/AndroidManifest.xml - Permissions
• sojorn_app/android/app/src/main/res/values/strings.xml - Notification channel

Flutter Code

• sojorn_app/lib/services/notification_service.dart - FCM initialization (now with enhanced logging)
• sojorn_app/lib/main.dart - App initialization

Backend

• go-backend/internal/services/push_service.go - Push notification sender
• go-backend/internal/handlers/settings_handler.go - FCM token registration endpoint

---

Quick Commands

# Check Android logs
adb logcat | findstr "FCM"

# Check if app is installed
adb shell pm list packages | findstr gosojorn

# Uninstall app
adb uninstall com.gosojorn.app

# Check notification settings
adb shell dumpsys notification | findstr gosojorn

# Check database for tokens
ssh -i "C:\Users\Patrick\.ssh\mpls.pem" patrick@194.238.28.122
sudo -u postgres psql sojorn -c "SELECT platform, COUNT(*) FROM fcm_tokens GROUP BY platform;"

---

Expected Behavior

When working correctly:

1. App starts → [FCM] Initializing for platform: android
2. Permission requested → User grants → [FCM] Permission status: AuthorizationStatus.authorized
3. Token generated → [FCM] Token registered (android): eXaMpLe...
4. Token synced → [FCM] Token synced with Go Backend successfully
5. Message sent → Backend sends push → [FCM] Foreground message received
6. Notification appears in Android notification tray

---

Contact & Support

If issues persist after following this guide:

1. Share Android logcat output (filtered for FCM)
2. Share database query results for fcm_tokens table
3. Share backend logs when sending notification
4. Verify Firebase Console shows Android app is active