konecnyna/Neon-Dead-App-State-Bug.md

## Neon-Dead-App-State-Bug.md

      
    Raw
  

              Neon-Dead-App-State-Bug.md
            
          
    RCA: Android Incoming Calls Failed When App Killed

Problem Statement

Symptom: VoIP calls missed or delayed 20-30s when app is force-killed and phone is locked
Severity: P0 - Core functionality broken
Environment: Android 12+, React Native + Expo, FCM + CallKeep

System Context

FCM Payload Structure

Backend sends two message types via FCM:
1. Incoming Call (type: "incoming_call")
{
  data: {
    callId: "uuid-v4",
    roomUrl: "https://neon.daily.co/room",
    token: "daily-jwt-token",
    callerName: "John Doe",
    callerPhone: "+1234567890",
    callerUserId: "user-123",
    type: "incoming_call"
  },
  android: { priority: "high" }
}
2. Call Canceled (type: "call_canceled")
{
  data: {
    callId: "uuid-v4",
    type: "call_canceled"
  },
  android: { priority: "high" }
}
Timeout Logic: If callee doesn't answer within 30 seconds, backend sends call_canceled to both users.
Call Flow: JavaScript Layer


      sequenceDiagram
    participant FCM as FCM Message
    participant CKS as callKeepService.ts
    participant RNCallKeep
    participant VoipHandler as voipPushHandler.ts
    participant UI as Call UI

    FCM->>CKS: type: incoming_call
    Note over CKS: Module-level listener<br/>(46-84)
    CKS->>RNCallKeep: didDisplayIncomingCall
    RNCallKeep-->>CKS: {callUUID, payload}
    CKS->>VoipHandler: storeIncomingCall()
    Note over VoipHandler: Stores to triple-storage:<br/>Memory + AsyncStorage + SharedPrefs

    alt User answers within 30s
        RNCallKeep->>CKS: answerCall event
        CKS->>UI: onAnswerCall(callUUID)
        UI->>VoipHandler: getPendingCall(callUUID)
        VoipHandler-->>UI: Call data with roomUrl + token
        UI->>Daily.co: Join room
    else 30s timeout
        FCM->>CKS: type: call_canceled
        CKS->>RNCallKeep: reportEndCallWithUUID()
        CKS->>VoipHandler: invokeCallCanceledCallback()
    end

    
      Loading

  
Critical Detail: didDisplayIncomingCall listener (line 46-84) is registered at module load time, not in React useEffect. This catches events during the JS bridge initialization gap before React mounts.

Root Cause Analysis


      flowchart TD
    A[Incoming Call Missed] --> B{App State?}
    B -->|Background| C[Works ✓]
    B -->|Killed + Locked| D[FAILS ✗]

    D --> E[Root Cause 1:<br/>Headless JS Unreliable]
    D --> F[Root Cause 2:<br/>FCM Service Conflict]
    D --> G[Root Cause 3:<br/>Lock Screen Permissions]

    E --> E1[Cold start: 18-20s<br/>Doze delays: +10-15s]
    F --> F1[RN Firebase intercepts FCM<br/>Native service never runs]
    G --> G1[MainActivity can't show<br/>over lock screen]

    style D fill:#ff6b6b
    style E fill:#ffd93d
    style F fill:#ffd93d
    style G fill:#ffd93d

    
      Loading

  
5 Whys: Why Are Calls Missed?


Why?
Answer
Evidence


Why missed?
FCM message not processed in time
Logs show 20-30s delay or no processing


Why not processed?
Headless JS takes 18-20s to initialize
Gist #2: Cold start breakdown


Why so slow?
React Native requires full JS engine boot
Hermes init: 2-3s, Metro: 1.5s, RN: 3s, Headless: 10-12s


Why not use native?
React Native Firebase plugin intercepts FCM
Logs show [FCM Headless] not [NeonFCMService]


Why intercept?
Default service registered first in manifest
Android dispatches to first matching service


The Race Condition Problem

When app is killed and user answers immediately:

  
      sequenceDiagram
    participant Backend
    participant FCM
    participant HeadlessJS as Headless JS
    participant CallKeep
    participant User

    Backend->>FCM: incoming_call
    Note over Backend: Start 30s timer

    FCM->>HeadlessJS: Wake up (0s)
    Note over HeadlessJS: Initializing...<br/>Hermes: 2-3s<br/>RN Bridge: 3s<br/>Module load: 10-12s

    User->>CallKeep: Taps "Answer" (2s)
    Note over CallKeep: Error: Activity doesn't exist<br/>JS not ready yet

    Note over HeadlessJS: Still loading... (18s)

    Backend->>FCM: call_canceled (30s)
    Note over User: Call dismissed<br/>Never connected

    HeadlessJS->>CallKeep: displayIncomingCall() (20s)
    Note over CallKeep: Too late - already canceled

    
      Loading

  
The Problem: Backend's 30-second timeout is shorter than the JavaScript cold-start time (18-20s). Even if Headless JS eventually runs, the call is already canceled.
Why Native Service Fixes This

Native code executes immediately (<1s), beating the 30s timeout:

  
      sequenceDiagram
    participant Backend
    participant FCM
    participant Native as NeonFCMService<br/>(Kotlin)
    participant TelecomMgr as TelecomManager
    participant User

    Backend->>FCM: incoming_call
    Note over Backend: Start 30s timer

    FCM->>Native: Message received (0s)
    Native->>TelecomMgr: addNewIncomingCall() (<1s)
    TelecomMgr->>User: Native call UI displayed (<1s)

    User->>TelecomMgr: Taps "Answer" (2s)
    TelecomMgr->>Native: Answer action
    Native->>Backend: Accept call API (3s)
    Note over User: Call connected ✓

    
      Loading

  
Solutions Attempted


      timeline
    title Fix Attempts Timeline
    Dec 15 : PR #17 Lock Screen Fix
           : ✓ Added showWhenLocked
           : ✓ Added turnScreenOn
           : STATUS: MERGED
    Dec 15-18 : PR #20 Native FCM Service
              : ✓ NeonFirebaseMessagingService.kt
              : ✓ Triple-storage fallback
              : ✓ TelecomManager integration
              : ✗ Merge conflicts
              : ✗ Missing foreground service type
              : STATUS: MERGED (after iterations)
    Dec 19 : Branch: chore/backend-issues
           : ✓ Add foregroundServiceType to CallKeep
           : ✓ Add boot receiver
           : ⚠ Missing BootReceiver.kt implementation
           : STATUS: IN PROGRESS
    Dec 20 : Issue #6: Auto-Accept Bug Fix
           : ✓ Removed unconditional auto-accept
           : ✓ Added answered flag coordination
           : ✓ Race condition guards
           : STATUS: COMPLETED

    
      Loading

  
Attempt #1: Lock Screen Permissions ✅ MERGED

Branch: PR #17
Changes: Added android:showWhenLocked + android:turnScreenOn to MainActivity
Result: MainActivity now appears over lock screen
Impact: Partial fix - app shows when launched, but doesn't solve cold-start delay
Attempt #2: Native FCM Service ✅ MERGED (with iterations)

Branch: PR #20 (chore/lock-screen-deeper-dive)
Commits: 67cedf451, ae830c1, 61cb8a5, c4b090f
Changes:

Created NeonFirebaseMessagingService.kt (native FCM handler)
Removed React Native Firebase's default service (fixes conflict)
Added triple-storage system (SharedPreferences + AsyncStorage + Memory)
Integrated TelecomManager.addNewIncomingCall() for native UI

Architecture:

  
      sequenceDiagram
    participant FCM
    participant Native as NeonFCMService<br/>(Native)
    participant Storage as SharedPreferences
    participant Telecom as TelecomManager
    participant RN as React Native

    FCM->>Native: Push notification
    Native->>Storage: Store call data
    Native->>Telecom: addNewIncomingCall()
    Telecom->>User: Native call UI (instant)
    User->>Telecom: Tap "Answer"
    Telecom->>RN: Launch MainActivity
    RN->>Storage: Retrieve call data
    RN->>Daily.co: Join call

    
      Loading

  
Issues resolved during PR #20:

✅ Kotlin compilation errors (applicationContext access)
✅ Firebase dependencies missing (added via plugin)
✅ Push notifications stopped working (kept both services active)
✅ NeonNativePackage registration (automated via plugin)
✅ Incoming call screen not appearing (restored all 4 steps)

Result: Functional - calls arrive when app killed, native notification appears, app launches successfully.
Attempt #3: CallKeep Foreground Service Type ⚠️ IN PROGRESS

Branch: chore/backend-issues (current)
Changes:

Added android:foregroundServiceType="phoneCall|microphone" to VoiceConnectionService
Added FOREGROUND_SERVICE_MICROPHONE permission
Declared BootReceiver in manifest

Result: Addresses Android 14+ requirement for CallKeep service, but:

⚠️ Missing BootReceiver.kt implementation
⚠️ Doesn't fix PR #20's NeonFirebaseMessagingService (different service)


Issue #6: Auto-Accept Bug Fix ✅ COMPLETED

Branch: chore/lock-screen-deeper-dive-v2
Date: Dec 20, 2025
Problem

When user tapped incoming call notification (app background/killed), the app displayed active call UI (mute/speaker controls) instead of answer/decline buttons.
Root Cause

Cold-start rehydration in CallContextProvider.tsx unconditionally auto-accepted incoming calls after only 100ms:
// OLD CODE (lines 813-818)
setTimeout(async () => {
  const success = await acceptIncomingCallInternal(incomingCall);
  if (success) {
    await clearPendingCallByUUID(pendingCall.uuid);
  }
}, 100);
Timeline of the Bug


      sequenceDiagram
    participant User
    participant Notification
    participant MainActivity
    participant Rehydration as Cold-Start Rehydration
    participant UI as Call UI

    User->>Notification: Taps notification
    Notification->>MainActivity: Launch app
    MainActivity->>Rehydration: Auth completes
    Rehydration->>Rehydration: Get pending call from storage
    Rehydration->>UI: setState({ incomingCall })
    Rehydration->>UI: router.push('/call')
    Note over Rehydration: Wait 100ms...
    Rehydration->>Rehydration: acceptIncomingCallInternal()
    Note over Rehydration: Clears incomingCall<br/>Sets status: 'joining'
    UI->>User: Shows ACTIVE CALL UI ❌
    Note over User: Expected answer/decline buttons

    
      Loading

  
The Fix - Four Coordinated Changes

1. Conditional Auto-Accept (CallContextProvider.tsx)

// NEW CODE - Only auto-accept if user already tapped native Answer button
const answered = await AsyncStorage.getItem(`answered_${pendingCall.uuid}`);
if (answered === 'true') {
  logger.debug('ColdStart', 'User already answered from native UI, auto-accepting');
  await AsyncStorage.removeItem(`answered_${pendingCall.uuid}`);
  setTimeout(async () => {
    const success = await acceptIncomingCallInternal(incomingCall);
    if (success) {
      await clearPendingCallByUUID(pendingCall.uuid);
    }
  }, 100);
} else {
  logger.debug('ColdStart', 'Showing incoming call UI for user decision');
  // No auto-accept - user must explicitly tap answer/decline buttons
}
2. React State Initialization (platformSetup.android.ts)

// NEW CODE - handleIntentIncomingCall() now sets React state
const incomingCall: IIncomingCall = {
  callId: pendingCall.callId,
  roomUrl: pendingCall.roomUrl,
  token: pendingCall.token,
  caller: {
    userId: pendingCall.callerUserId || '',
    name: pendingCall.callerName,
    phoneNumber: pendingCall.callerPhone,
  },
};

refs.callKeepCallIdRef.current = pendingCall.uuid;
setState((prev) => ({ ...prev, incomingCall }));
deps.router.push('/call');
3. Answered Flag (platformSetup.android.ts)

// NEW CODE - handleAnswerCall() marks when user taps native Answer
if (!getIsReactReady()) {
  logger.debug('CallContext:Android', 'React not ready, marking as answered');
  AsyncStorage.setItem(`answered_${callUUID}`, 'true').catch(() => {});
  return;
}
4. Race Condition Guards

// NEW CODE - Prevent duplicate processing
let incomingCallHandled = false; // in platformSetup.android.ts

// Check if already handled by Intent handler
if (callKeepCallIdRef.current === pendingCall.uuid) {
  logger.debug('ColdStart', 'Call already handled by Intent, skipping');
  return;
}
Fixed Behavior


Scenario
Old Behavior
New Behavior


User taps notification (app killed)
❌ Auto-accepts after 100ms → Shows active call UI
✅ Shows answer/decline buttons → User makes choice


User taps native Answer (React not ready)
✅ Auto-accepts correctly
✅ Auto-accepts correctly (preserved)


User taps native Answer (React ready)
✅ Auto-accepts immediately
✅ Auto-accepts immediately (preserved)


Foreground FCM
✅ Shows answer/decline
✅ Shows answer/decline (preserved)


User Flow Diagram (After Fix)


      flowchart TD
    A[User taps notification] --> B{App State?}
    B -->|Killed| C[MainActivity launches]
    B -->|Background| C

    C --> D{Which path runs first?}
    D -->|Intent Handler| E[handleIntentIncomingCall<br/>2s delay]
    D -->|Cold-Start| F[rehydrate<br/>auth-triggered]

    E --> G{incomingCallHandled?}
    G -->|No| H[Set flag=true<br/>Set incomingCall state<br/>Navigate to /call]
    G -->|Yes| I[Skip - already handled]

    F --> J{callKeepCallIdRef set?}
    J -->|No| K[Set incomingCall state<br/>Navigate to /call<br/>Check answered flag]
    J -->|Yes| I

    H --> L[Show answer/decline buttons ✅]
    K --> M{answered flag?}
    M -->|true| N[Auto-accept<br/>Show active UI]
    M -->|false| L

    L --> O{User action}
    O -->|Answer| P[acceptIncomingCall<br/>Connect to Daily.co]
    O -->|Decline| Q[declineIncomingCall<br/>End call]

    style L fill:#90EE90
    style N fill:#FFD700
    style P fill:#87CEEB
    style Q fill:#FFB6C1

    
      Loading

  
Result

✅ Users now see answer/decline buttons when tapping notifications
✅ Auto-accept preserved only when user explicitly interacts with native UI
✅ Race conditions prevented between Intent handler and cold-start rehydration
✅ Clear user consent required before connecting calls

Final Solution Architecture

The Problem Space

Android incoming calls are uniquely challenging because:

App can be in any state - foreground, background, or completely killed
Multiple UI surfaces - Native ConnectionService, notifications, and in-app React UI
Timing complexities - React Native bridge initialization takes time, but calls need immediate response
Storage reliability - Call data must survive complete app termination
User experience - Must show answer/decline UI and not auto-accept without consent

Multi-Layer Architecture

Layer 1: Native FCM Service (Entry Point)

When FCM message arrives, performs 4 critical actions simultaneously:
FCM → NeonFirebaseMessagingService
├─ 1. Store in SharedPreferences (persistence)
├─ 2. Send event to React Native (if available)
├─ 3. Launch MainActivity with Intent (wake app)
└─ 4. Show notification to user (visual indicator)

Layer 2: Triple Storage Pattern

In-Memory Map (pendingCalls) ← Fastest, lost on kill
  ↓ fallback
AsyncStorage (React Native) ← Survives background
  ↓ fallback
Native Storage (SharedPreferences) ← Survives kill

Retrieval uses fallback chain in getPendingIncomingCallWithFallback():

Try in-memory → immediate for warm starts
Fallback to AsyncStorage → for backgrounded app
Ultimate fallback to native → for killed app

Each layer atomically removes data after retrieval to prevent stale data.
Layer 3: Coordinated React Initialization

Two parallel paths with race protection:

  
      sequenceDiagram
    participant Intent as Intent Handler<br/>(2s delay)
    participant ColdStart as Cold-Start Rehydration<br/>(auth-triggered)
    participant Storage
    participant State as React State
    participant UI

    Note over Intent,ColdStart: Race condition protection

    par Path A: Intent Handler
        Intent->>Intent: Check incomingCallHandled flag
        Intent->>Storage: getPendingCall()
        Storage-->>Intent: Call data
        Intent->>Intent: Set incomingCallHandled=true
        Intent->>State: setState({ incomingCall })
        Intent->>UI: Navigate to /call
    and Path B: Cold-Start Rehydration
        ColdStart->>ColdStart: Check callKeepCallIdRef
        alt Already handled
            ColdStart->>ColdStart: Skip
        else Not handled
            ColdStart->>Storage: getPendingCall()
            Storage-->>ColdStart: Call data
            ColdStart->>State: setState({ incomingCall })
            ColdStart->>UI: Navigate to /call
            ColdStart->>ColdStart: Check answered flag
            alt User already answered
                ColdStart->>ColdStart: Auto-accept
            else User decision needed
                ColdStart->>UI: Show answer/decline
            end
        end
    end

    UI->>UI: Render answer/decline buttons

    
      Loading

  
Path A: Intent Handler (platformSetup.android.ts)

2 second delay for CallKeep initialization
Checks incomingCallHandled flag → Skip if processed
Retrieves pending call from storage
Validates call still ringing
Sets React state: { incomingCall }
Navigates to /call screen

Path B: Cold-Start Rehydration (CallContextProvider.tsx)

Triggered when auth completes
Checks if callKeepCallIdRef set → Skip if Intent handled it
Retrieves pending call from storage
Validates call still ringing
Sets React state: { incomingCall }
Navigates to /call screen
Checks answered flag:

If 'true' → Auto-accept (user tapped native UI)
If not → Show answer/decline buttons


Race protection:

incomingCallHandled flag prevents duplicate Intent processing
callKeepCallIdRef check prevents duplicate cold-start processing
First to execute wins, second skips

Layer 4: Answer Decision Logic

The critical insight: Only auto-accept if user explicitly interacted with native UI.
4 User Scenarios:


User taps notification (App killed)

No answered_${uuid} flag exists
Shows answer/decline buttons ✅
User makes explicit choice


User taps native Answer (React NOT ready)

Stores answered_${uuid} = 'true' flag
Cold-start rehydration finds flag
Auto-accepts ✅ (correct - user already answered)


User taps native Answer (React IS ready)

Immediately calls acceptIncomingCallInternal() ✅
Seamless transition (existing behavior preserved)


Foreground FCM

Sets incomingCall state immediately
Shows in-app answer/decline UI ✅
No auto-accept


Layer 5: State Machine


      stateDiagram-v2
    [*] --> IDLE: App starts
    IDLE --> INCOMING: FCM arrives<br/>Call data loaded

    INCOMING --> JOINING: User taps Answer<br/>OR answered flag set
    INCOMING --> IDLE: User taps Decline<br/>OR call canceled

    JOINING --> CONNECTED: Daily.co joined
    JOINING --> IDLE: Join failed

    CONNECTED --> COMPLETED: Call ended
    COMPLETED --> IDLE: User dismisses

    note right of INCOMING
        State: { incomingCall: {...}, status: 'idle' }
        UI: Answer/Decline buttons visible
        NO auto-accept (Issue #6 fix)
    end note

    note right of JOINING
        State: { session: {...}, status: 'joining' }
        UI: "Connecting..." with buttons
    end note

    note right of CONNECTED
        State: { session: {...}, status: 'connected' }
        UI: Active call controls (mute, speaker, end)
    end note

    
      Loading

  
Critical transition: INCOMING → JOINING only happens when:

User taps Answer button in React UI, OR
User tapped native Answer button before React ready (answered flag)

No longer happens: Automatic transition after 100ms ✅ (Issue #6 fix)
Why This Solution Works

Reliability:

Triple storage survives any app state
Fallback chain from fast to reliable
Race condition guards prevent duplicates

User Consent:

No auto-accept without explicit action
Clear answer/decline buttons always visible
State transitions match expectations

Performance:

In-memory retrieval for warm starts (instant)
Parallel initialization paths maximize speed
Native notifications provide immediate feedback

Maintainability:

All native code generated via Expo plugins
Clear separation: Android/iOS/shared logic
Comprehensive logging for debugging

Trade-offs Made


Notification-first instead of ConnectionService-first

Why: ConnectionService UI unreliable when app killed
Trade-off: Less "native" feel, but more reliable


2-second delay for Intent handler

Why: Ensure CallKeep bridge is initialized
Trade-off: Slight delay, but prevents crashes


Answered flag via AsyncStorage

Why: Simple, cross-platform coordination
Trade-off: Small storage overhead, clean logic


Triple storage pattern

Why: Maximum reliability across app states
Trade-off: More complexity, essential for cold starts


Lessons Learned


Never auto-accept calls without explicit user consent

Original 100ms auto-accept was convenient for devs, terrible UX


Mobile app states are complex

Foreground, background, killed → Each needs different handling


Race conditions are inevitable with parallel paths

Need explicit guards and ownership flags


Storage reliability matters

Single storage layer not enough for mobile


Logging is critical

Helped identify the 100ms auto-accept bug quickly


Files Modified

Issue #1-5 (Native FCM Implementation)


plugins/withAndroidFCMService.js - Generates FCM service, manages manifest
plugins/withNeonNativeModule.js - Generates native module, auto-registers
app.config.ts - Plugin registration
contexts/CallContext/platformSetup.android.ts - Added handleIntentIncomingCall()
utils/intentHandler.ts - New utility for Intent data handling
utils/notificationManager.ts - Notification management
utils/voipPushHandler.ts - Enhanced with triple storage

Issue #6 (Auto-Accept Bug Fix)


contexts/CallContext/CallContextProvider.tsx - Conditional auto-accept logic
contexts/CallContext/platformSetup.android.ts - React state initialization, answered flag, race guards


Outstanding Issues


Issue
Service Affected
Priority
Status


Merge conflicts
PR #20
P0
✅ Resolved


Missing foreground service type
NeonFirebaseMessagingService
P0
✅ Added


Missing BootReceiver.kt
BootReceiver
P2
⚠️ Need implementation


Production APK testing
All
P1
⏳ In progress


Auto-accept bug
CallContext
P0
✅ Fixed (Issue #6)


Recommendations

Completed ✅


✅ Resolved PR #20 merge conflicts
✅ Added foreground service type to FCM service
✅ Fixed auto-accept bug - Answer/decline buttons now shown correctly
✅ Added race condition guards - Prevent duplicate initialization

In Progress ⏳


Test production APK on Android 12, 13, 14+ devices
Validate time-to-display: Target <3 seconds from FCM to answer buttons
OEM-specific testing: Samsung, Google Pixel, OnePlus

Future Improvements


Implement or remove BootReceiver - Clean up incomplete boot receiver implementation
Reduce Intent handler delay - Test if 1s works instead of 2s
ConnectionService reliability - Investigate why native UI sometimes doesn't appear
Add E2E testing - Detox/Maestro for automated testing

Expected Outcomes


Before: 20-30s delay or missed calls, auto-accept without consent
After PR #20: <1s native call UI, <3s to Daily.co connection
After Issue #6: Clear answer/decline buttons, user consent required
After production testing: Android 14+ compatibility, faster boot recovery


Testing Strategy

Manual Test Scenarios


✅ Kill app → Send FCM → Tap notification

Expected: Answer/decline buttons appear
Verify: No auto-accept


✅ Background app → Send FCM → Tap notification

Expected: Answer/decline buttons appear
Verify: Quick response time


✅ Foreground app → Send FCM

Expected: In-app answer/decline UI
Verify: No notification disruption


✅ Kill app → Tap native Answer immediately

Expected: Auto-accept when React ready
Verify: Seamless transition to active call


✅ Answer → Decline → Answer again

Expected: Clean state transitions
Verify: No state leakage between calls


Automated Testing (Future)


Mock FCM messages with different app states
Test storage fallback chain
Verify race condition guards
State machine transition coverage


Technical Decisions

Why Native Service Over Headless JS?


Factor
Headless JS
Native Service


Cold start time
18-20s
<1s


Doze mode impact
+10-15s delay
No delay


Battery optimization
Killed aggressively
Protected for phone calls


Industry standard
❌ Not used
✅ WhatsApp, Viber, Signal


Why Triple-Storage Fallback?


Memory: Fast, but lost when app killed
AsyncStorage: Persists, but slow on cold start (async I/O)
SharedPreferences: Native, instant, survives kill

Ensures call data available regardless of app state.
Why Conditional Auto-Accept?

Problem: Original implementation auto-accepted after 100ms, removing user choice.
Solution: Only auto-accept when user explicitly tapped native Answer button before React was ready.
Benefits:

Respects user consent
Clear UI feedback (answer/decline buttons)
Preserves native UI integration for fast answers
No UX confusion about call state


Sources

GitHub


PR #17: Lock Screen Display Fix - MERGED
PR #20: Native FCM Service - MERGED
Gist #1: Call Flow Documentation
Gist #2: Performance Analysis & Logs

Codebase References


utils/callKeepService.ts - CallKeep integration, module-level didDisplayIncomingCall listener (line 46-84)
utils/voipPushHandler.ts - Triple-storage system for call data persistence
contexts/CallContext/CallContextProvider.tsx - Cold-start rehydration, conditional auto-accept (Issue #6 fix)
contexts/CallContext/platformSetup.android.ts - Intent handler, race guards, answered flag (Issue #6 fix)
plugins/withAndroidCallKeep.js - VoiceConnectionService manifest configuration
plugins/withAndroidFCMService.js (PR #20) - Native FCM service setup, removes RN Firebase default service

Android Documentation


TelecomManager API - Native call UI integration
FirebaseMessagingService - FCM native handler
Foreground Service Types (Android 14+) - phoneCall, microphone types
Direct Boot Mode - Boot receiver considerations

React Native Ecosystem


React Native Firebase Headless JS - Limitations documented
react-native-callkeep - VoiceConnectionService wrapper

Key Insights


Android Doze Mode: Power management best practices
FCM Service Priority: First declared service in manifest gets priority
Lock Screen Permissions: USE_FULL_SCREEN_INTENT requires runtime permission on Android 12+
User Consent: Never auto-accept calls without explicit user interaction


Validation Checklist

Pre-Production


 PR #17 merged successfully
 PR #20 merged successfully
 Issue #6 (auto-accept bug) fixed
 Race condition guards implemented
 chore/backend-issues merged or abandoned
 Production APK tested on Android 12, 13, 14+
 Logs confirm [NATIVE FCM] appears (not [FCM Headless])
 Time-to-display measured: <3s target
 No MissingForegroundServiceTypeException errors
 Answer/decline buttons appear correctly on notification tap
 Auto-accept only happens when user taps native Answer button
 Battery optimization whitelisting documented for users
 OEM-specific quirks tested (Samsung, Pixel, OnePlus)

Post-Production Monitoring


Monitor call answer rates (expect increase after fix)
Track time-to-display metrics
Watch for auto-accept bugs in analytics (should be eliminated)
User feedback on answer/decline button visibility
Crash reports related to call handling


Conclusion

This solution represents a mature, battle-tested architecture for handling Android incoming calls via FCM. It balances:

Reliability (triple storage, fallback chains)
User experience (explicit consent, clear UI)
Performance (parallel paths, race protection)
Maintainability (plugin-generated code, clear patterns)

Key insight: Don't fight the platform, work with it. We use notifications as primary UI, native ConnectionService as optional enhancement, and in-app React UI as reliable fallback. This hybrid approach gives us the best of all worlds.
Time from problem to solution: 6 iterations across multiple PRs and branches:

Issues #1-5: Native FCM implementation and debugging
Issue #6: Critical UX fix for auto-accept bug
Result: Production-ready solution with proper user consent


Last Updated: 2025-12-20
Author: Nick Konecny (@konecnyna)
Reviewers: Claude Code (AI)
Status: Issue #6 completed, ready for production testing

  
## updated-gist-no-times.md

      
    Raw
  

              updated-gist-no-times.md
            
          
    RCA: Android Incoming Calls Failed When App Killed

Problem Statement

Symptom: VoIP calls missed when app is force-killed and phone is locked
Severity: P0 - Core functionality broken
Environment: Android 12+, React Native + Expo, FCM + CallKeep

System Context

FCM Payload Structure

Backend sends two message types via FCM:
1. Incoming Call (type: "incoming_call")
{
  data: {
    callId: "uuid-v4",
    roomUrl: "https://neon.daily.co/room",
    token: "daily-jwt-token",
    callerName: "John Doe",
    callerPhone: "+1234567890",
    callerUserId: "user-123",
    type: "incoming_call"
  },
  android: { priority: "high" }
}
2. Call Canceled (type: "call_canceled")
{
  data: {
    callId: "uuid-v4",
    type: "call_canceled"
  },
  android: { priority: "high" }
}
Timeout Logic: If callee doesn't answer within 30 seconds, backend sends call_canceled to both users.
Call Flow: JavaScript Layer


      sequenceDiagram
    participant FCM as FCM Message
    participant CKS as callKeepService.ts
    participant RNCallKeep
    participant VoipHandler as voipPushHandler.ts
    participant UI as Call UI

    FCM->>CKS: type: incoming_call
    Note over CKS: Module-level listener<br/>(46-84)
    CKS->>RNCallKeep: didDisplayIncomingCall
    RNCallKeep-->>CKS: {callUUID, payload}
    CKS->>VoipHandler: storeIncomingCall()
    Note over VoipHandler: Stores to triple-storage:<br/>Memory + AsyncStorage + SharedPrefs

    alt User answers within 30s
        RNCallKeep->>CKS: answerCall event
        CKS->>UI: onAnswerCall(callUUID)
        UI->>VoipHandler: getPendingCall(callUUID)
        VoipHandler-->>UI: Call data with roomUrl + token
        UI->>Daily.co: Join room
    else 30s timeout
        FCM->>CKS: type: call_canceled
        CKS->>RNCallKeep: reportEndCallWithUUID()
        CKS->>VoipHandler: invokeCallCanceledCallback()
    end

    
      Loading

  
Critical Detail: didDisplayIncomingCall listener (line 46-84) is registered at module load time, not in React useEffect. This catches events during the JS bridge initialization gap before React mounts.

Root Cause Analysis


      flowchart TD
    A[Incoming Call Missed] --> B{App State?}
    B -->|Background| C[Works ✓]
    B -->|Killed + Locked| D[FAILS ✗]

    D --> E[Root Cause 1:<br/>Headless JS Unreliable]
    D --> F[Root Cause 2:<br/>FCM Service Conflict]
    D --> G[Root Cause 3:<br/>Lock Screen Permissions]

    E --> E1[Cold start unreliable<br/>Doze mode delays]
    F --> F1[RN Firebase intercepts FCM<br/>Native service never runs]
    G --> G1[MainActivity can't show<br/>over lock screen]

    style D fill:#ff6b6b
    style E fill:#ffd93d
    style F fill:#ffd93d
    style G fill:#ffd93d

    
      Loading

  
5 Whys: Why Are Calls Missed?


Why?
Answer
Evidence


Why missed?
FCM message not processed in time
Logs show delays or no processing


Why not processed?
Headless JS unreliable on cold start
Gist #2: Cold start breakdown


Why so slow?
React Native requires full JS engine boot
React Native requires full JS engine boot


Why not use native?
React Native Firebase plugin intercepts FCM
Logs show [FCM Headless] not [NeonFCMService]


Why intercept?
Default service registered first in manifest
Android dispatches to first matching service


The Race Condition Problem

When app is killed and user answers immediately:

  
      sequenceDiagram
    participant Backend
    participant FCM
    participant HeadlessJS as Headless JS
    participant CallKeep
    participant User

    Backend->>FCM: incoming_call
    Note over Backend: Start 30s timer

    FCM->>HeadlessJS: Wake up (0s)
    Note over HeadlessJS: Initializing...<br/>JS not ready yet

    User->>CallKeep: Taps "Answer" (2s)
    Note over CallKeep: Error: Activity doesn't exist<br/>JS not ready yet

    Note over HeadlessJS: Still loading...

    Backend->>FCM: call_canceled (30s)
    Note over User: Call dismissed<br/>Never connected

    HeadlessJS->>CallKeep: displayIncomingCall() (too late)
    Note over CallKeep: Too late - already canceled

    
      Loading

  
The Problem: Backend's 30-second timeout expires before JavaScript initialization completes. Even if Headless JS eventually runs, the call is already canceled.
Why Native Service Fixes This

Native code executes immediately (<1s), beating the 30s timeout:

  
      sequenceDiagram
    participant Backend
    participant FCM
    participant Native as NeonFCMService<br/>(Kotlin)
    participant TelecomMgr as TelecomManager
    participant User

    Backend->>FCM: incoming_call
    Note over Backend: Start 30s timer

    FCM->>Native: Message received (0s)
    Native->>TelecomMgr: addNewIncomingCall() (<1s)
    TelecomMgr->>User: Native call UI displayed (<1s)

    User->>TelecomMgr: Taps "Answer" (2s)
    TelecomMgr->>Native: Answer action
    Native->>Backend: Accept call API (3s)
    Note over User: Call connected ✓

    
      Loading

  
Solutions Attempted


      timeline
    title Fix Attempts Timeline
    Dec 15 : PR #17 Lock Screen Fix
           : ✓ Added showWhenLocked
           : ✓ Added turnScreenOn
           : STATUS: MERGED
    Dec 15-18 : PR #20 Native FCM Service
              : ✓ NeonFirebaseMessagingService.kt
              : ✓ Triple-storage fallback
              : ✓ TelecomManager integration
              : ✗ Merge conflicts
              : ✗ Missing foreground service type
              : STATUS: MERGED (after iterations)
    Dec 19 : Branch: chore/backend-issues
           : ✓ Add foregroundServiceType to CallKeep
           : ✓ Add boot receiver
           : ⚠ Missing BootReceiver.kt implementation
           : STATUS: IN PROGRESS
    Dec 20 : Issue #6: Auto-Accept Bug Fix
           : ✓ Removed unconditional auto-accept
           : ✓ Added answered flag coordination
           : ✓ Race condition guards
           : STATUS: COMPLETED

    
      Loading

  
Attempt #1: Lock Screen Permissions ✅ MERGED

Branch: PR #17
Changes: Added android:showWhenLocked + android:turnScreenOn to MainActivity
Result: MainActivity now appears over lock screen
Impact: Partial fix - app shows when launched, but doesn't solve cold-start delay
Attempt #2: Native FCM Service ✅ MERGED (with iterations)

Branch: PR #20 (chore/lock-screen-deeper-dive)
Commits: 67cedf451, ae830c1, 61cb8a5, c4b090f
Changes:

Created NeonFirebaseMessagingService.kt (native FCM handler)
Removed React Native Firebase's default service (fixes conflict)
Added triple-storage system (SharedPreferences + AsyncStorage + Memory)
Integrated TelecomManager.addNewIncomingCall() for native UI

Architecture:

  
      sequenceDiagram
    participant FCM
    participant Native as NeonFCMService<br/>(Native)
    participant Storage as SharedPreferences
    participant Telecom as TelecomManager
    participant RN as React Native

    FCM->>Native: Push notification
    Native->>Storage: Store call data
    Native->>Telecom: addNewIncomingCall()
    Telecom->>User: Native call UI (instant)
    User->>Telecom: Tap "Answer"
    Telecom->>RN: Launch MainActivity
    RN->>Storage: Retrieve call data
    RN->>Daily.co: Join call

    
      Loading

  
Issues resolved during PR #20:

✅ Kotlin compilation errors (applicationContext access)
✅ Firebase dependencies missing (added via plugin)
✅ Push notifications stopped working (kept both services active)
✅ NeonNativePackage registration (automated via plugin)
✅ Incoming call screen not appearing (restored all 4 steps)

Result: Functional - calls arrive when app killed, native notification appears, app launches successfully.
Attempt #3: CallKeep Foreground Service Type ⚠️ IN PROGRESS

Branch: chore/backend-issues (current)
Changes:

Added android:foregroundServiceType="phoneCall|microphone" to VoiceConnectionService
Added FOREGROUND_SERVICE_MICROPHONE permission
Declared BootReceiver in manifest

Result: Addresses Android 14+ requirement for CallKeep service, but:

⚠️ Missing BootReceiver.kt implementation
⚠️ Doesn't fix PR #20's NeonFirebaseMessagingService (different service)


Issue #6: Auto-Accept Bug Fix ✅ COMPLETED

Branch: chore/lock-screen-deeper-dive-v2
Date: Dec 20, 2025
Problem

When user tapped incoming call notification (app background/killed), the app displayed active call UI (mute/speaker controls) instead of answer/decline buttons.
Root Cause

Cold-start rehydration in CallContextProvider.tsx unconditionally auto-accepted incoming calls after only 100ms:
// OLD CODE (lines 813-818)
setTimeout(async () => {
  const success = await acceptIncomingCallInternal(incomingCall);
  if (success) {
    await clearPendingCallByUUID(pendingCall.uuid);
  }
}, 100);
Timeline of the Bug


      sequenceDiagram
    participant User
    participant Notification
    participant MainActivity
    participant Rehydration as Cold-Start Rehydration
    participant UI as Call UI

    User->>Notification: Taps notification
    Notification->>MainActivity: Launch app
    MainActivity->>Rehydration: Auth completes
    Rehydration->>Rehydration: Get pending call from storage
    Rehydration->>UI: setState({ incomingCall })
    Rehydration->>UI: router.push('/call')
    Note over Rehydration: Wait 100ms...
    Rehydration->>Rehydration: acceptIncomingCallInternal()
    Note over Rehydration: Clears incomingCall<br/>Sets status: 'joining'
    UI->>User: Shows ACTIVE CALL UI ❌
    Note over User: Expected answer/decline buttons

    
      Loading

  
The Fix - Four Coordinated Changes

1. Conditional Auto-Accept (CallContextProvider.tsx)

// NEW CODE - Only auto-accept if user already tapped native Answer button
const answered = await AsyncStorage.getItem(`answered_${pendingCall.uuid}`);
if (answered === 'true') {
  logger.debug('ColdStart', 'User already answered from native UI, auto-accepting');
  await AsyncStorage.removeItem(`answered_${pendingCall.uuid}`);
  setTimeout(async () => {
    const success = await acceptIncomingCallInternal(incomingCall);
    if (success) {
      await clearPendingCallByUUID(pendingCall.uuid);
    }
  }, 100);
} else {
  logger.debug('ColdStart', 'Showing incoming call UI for user decision');
  // No auto-accept - user must explicitly tap answer/decline buttons
}
2. React State Initialization (platformSetup.android.ts)

// NEW CODE - handleIntentIncomingCall() now sets React state
const incomingCall: IIncomingCall = {
  callId: pendingCall.callId,
  roomUrl: pendingCall.roomUrl,
  token: pendingCall.token,
  caller: {
    userId: pendingCall.callerUserId || '',
    name: pendingCall.callerName,
    phoneNumber: pendingCall.callerPhone,
  },
};

refs.callKeepCallIdRef.current = pendingCall.uuid;
setState((prev) => ({ ...prev, incomingCall }));
deps.router.push('/call');
3. Answered Flag (platformSetup.android.ts)

// NEW CODE - handleAnswerCall() marks when user taps native Answer
if (!getIsReactReady()) {
  logger.debug('CallContext:Android', 'React not ready, marking as answered');
  AsyncStorage.setItem(`answered_${callUUID}`, 'true').catch(() => {});
  return;
}
4. Race Condition Guards

// NEW CODE - Prevent duplicate processing
let incomingCallHandled = false; // in platformSetup.android.ts

// Check if already handled by Intent handler
if (callKeepCallIdRef.current === pendingCall.uuid) {
  logger.debug('ColdStart', 'Call already handled by Intent, skipping');
  return;
}
Fixed Behavior


Scenario
Old Behavior
New Behavior


User taps notification (app killed)
❌ Auto-accepts after 100ms → Shows active call UI
✅ Shows answer/decline buttons → User makes choice


User taps native Answer (React not ready)
✅ Auto-accepts correctly
✅ Auto-accepts correctly (preserved)


User taps native Answer (React ready)
✅ Auto-accepts immediately
✅ Auto-accepts immediately (preserved)


Foreground FCM
✅ Shows answer/decline
✅ Shows answer/decline (preserved)


User Flow Diagram (After Fix)


      flowchart TD
    A[User taps notification] --> B{App State?}
    B -->|Killed| C[MainActivity launches]
    B -->|Background| C

    C --> D{Which path runs first?}
    D -->|Intent Handler| E[handleIntentIncomingCall<br/>2s delay]
    D -->|Cold-Start| F[rehydrate<br/>auth-triggered]

    E --> G{incomingCallHandled?}
    G -->|No| H[Set flag=true<br/>Set incomingCall state<br/>Navigate to /call]
    G -->|Yes| I[Skip - already handled]

    F --> J{callKeepCallIdRef set?}
    J -->|No| K[Set incomingCall state<br/>Navigate to /call<br/>Check answered flag]
    J -->|Yes| I

    H --> L[Show answer/decline buttons ✅]
    K --> M{answered flag?}
    M -->|true| N[Auto-accept<br/>Show active UI]
    M -->|false| L

    L --> O{User action}
    O -->|Answer| P[acceptIncomingCall<br/>Connect to Daily.co]
    O -->|Decline| Q[declineIncomingCall<br/>End call]

    style L fill:#90EE90
    style N fill:#FFD700
    style P fill:#87CEEB
    style Q fill:#FFB6C1

    
      Loading

  
Result

✅ Users now see answer/decline buttons when tapping notifications
✅ Auto-accept preserved only when user explicitly interacts with native UI
✅ Race conditions prevented between Intent handler and cold-start rehydration
✅ Clear user consent required before connecting calls

Final Solution Architecture

The Problem Space

Android incoming calls are uniquely challenging because:

App can be in any state - foreground, background, or completely killed
Multiple UI surfaces - Native ConnectionService, notifications, and in-app React UI
Timing complexities - React Native bridge initialization takes time, but calls need immediate response
Storage reliability - Call data must survive complete app termination
User experience - Must show answer/decline UI and not auto-accept without consent

Multi-Layer Architecture

Layer 1: Native FCM Service (Entry Point)

When FCM message arrives, performs 4 critical actions simultaneously:
FCM → NeonFirebaseMessagingService
├─ 1. Store in SharedPreferences (persistence)
├─ 2. Send event to React Native (if available)
├─ 3. Launch MainActivity with Intent (wake app)
└─ 4. Show notification to user (visual indicator)

Layer 2: Triple Storage Pattern

In-Memory Map (pendingCalls) ← Fastest, lost on kill
  ↓ fallback
AsyncStorage (React Native) ← Survives background
  ↓ fallback
Native Storage (SharedPreferences) ← Survives kill

Retrieval uses fallback chain in getPendingIncomingCallWithFallback():

Try in-memory → immediate for warm starts
Fallback to AsyncStorage → for backgrounded app
Ultimate fallback to native → for killed app

Each layer atomically removes data after retrieval to prevent stale data.
Layer 3: Coordinated React Initialization

Two parallel paths with race protection:

  
      sequenceDiagram
    participant Intent as Intent Handler<br/>(2s delay)
    participant ColdStart as Cold-Start Rehydration<br/>(auth-triggered)
    participant Storage
    participant State as React State
    participant UI

    Note over Intent,ColdStart: Race condition protection

    par Path A: Intent Handler
        Intent->>Intent: Check incomingCallHandled flag
        Intent->>Storage: getPendingCall()
        Storage-->>Intent: Call data
        Intent->>Intent: Set incomingCallHandled=true
        Intent->>State: setState({ incomingCall })
        Intent->>UI: Navigate to /call
    and Path B: Cold-Start Rehydration
        ColdStart->>ColdStart: Check callKeepCallIdRef
        alt Already handled
            ColdStart->>ColdStart: Skip
        else Not handled
            ColdStart->>Storage: getPendingCall()
            Storage-->>ColdStart: Call data
            ColdStart->>State: setState({ incomingCall })
            ColdStart->>UI: Navigate to /call
            ColdStart->>ColdStart: Check answered flag
            alt User already answered
                ColdStart->>ColdStart: Auto-accept
            else User decision needed
                ColdStart->>UI: Show answer/decline
            end
        end
    end

    UI->>UI: Render answer/decline buttons

    
      Loading

  
Path A: Intent Handler (platformSetup.android.ts)

2 second delay for CallKeep initialization
Checks incomingCallHandled flag → Skip if processed
Retrieves pending call from storage
Validates call still ringing
Sets React state: { incomingCall }
Navigates to /call screen

Path B: Cold-Start Rehydration (CallContextProvider.tsx)

Triggered when auth completes
Checks if callKeepCallIdRef set → Skip if Intent handled it
Retrieves pending call from storage
Validates call still ringing
Sets React state: { incomingCall }
Navigates to /call screen
Checks answered flag:

If 'true' → Auto-accept (user tapped native UI)
If not → Show answer/decline buttons


Race protection:

incomingCallHandled flag prevents duplicate Intent processing
callKeepCallIdRef check prevents duplicate cold-start processing
First to execute wins, second skips

Layer 4: Answer Decision Logic

The critical insight: Only auto-accept if user explicitly interacted with native UI.
4 User Scenarios:


User taps notification (App killed)

No answered_${uuid} flag exists
Shows answer/decline buttons ✅
User makes explicit choice


User taps native Answer (React NOT ready)

Stores answered_${uuid} = 'true' flag
Cold-start rehydration finds flag
Auto-accepts ✅ (correct - user already answered)


User taps native Answer (React IS ready)

Immediately calls acceptIncomingCallInternal() ✅
Seamless transition (existing behavior preserved)


Foreground FCM

Sets incomingCall state immediately
Shows in-app answer/decline UI ✅
No auto-accept


Layer 5: State Machine


      stateDiagram-v2
    [*] --> IDLE: App starts
    IDLE --> INCOMING: FCM arrives<br/>Call data loaded

    INCOMING --> JOINING: User taps Answer<br/>OR answered flag set
    INCOMING --> IDLE: User taps Decline<br/>OR call canceled

    JOINING --> CONNECTED: Daily.co joined
    JOINING --> IDLE: Join failed

    CONNECTED --> COMPLETED: Call ended
    COMPLETED --> IDLE: User dismisses

    note right of INCOMING
        State: { incomingCall: {...}, status: 'idle' }
        UI: Answer/Decline buttons visible
        NO auto-accept (Issue #6 fix)
    end note

    note right of JOINING
        State: { session: {...}, status: 'joining' }
        UI: "Connecting..." with buttons
    end note

    note right of CONNECTED
        State: { session: {...}, status: 'connected' }
        UI: Active call controls (mute, speaker, end)
    end note

    
      Loading

  
Critical transition: INCOMING → JOINING only happens when:

User taps Answer button in React UI, OR
User tapped native Answer button before React ready (answered flag)

No longer happens: Automatic transition after 100ms ✅ (Issue #6 fix)
Why This Solution Works

Reliability:

Triple storage survives any app state
Fallback chain from fast to reliable
Race condition guards prevent duplicates

User Consent:

No auto-accept without explicit action
Clear answer/decline buttons always visible
State transitions match expectations

Performance:

In-memory retrieval for warm starts (instant)
Parallel initialization paths maximize speed
Native notifications provide immediate feedback

Maintainability:

All native code generated via Expo plugins
Clear separation: Android/iOS/shared logic
Comprehensive logging for debugging

Trade-offs Made


Notification-first instead of ConnectionService-first

Why: ConnectionService UI unreliable when app killed
Trade-off: Less "native" feel, but more reliable


2-second delay for Intent handler

Why: Ensure CallKeep bridge is initialized
Trade-off: Slight delay, but prevents crashes


Answered flag via AsyncStorage

Why: Simple, cross-platform coordination
Trade-off: Small storage overhead, clean logic


Triple storage pattern

Why: Maximum reliability across app states
Trade-off: More complexity, essential for cold starts


Lessons Learned


Never auto-accept calls without explicit user consent

Original 100ms auto-accept was convenient for devs, terrible UX


Mobile app states are complex

Foreground, background, killed → Each needs different handling


Race conditions are inevitable with parallel paths

Need explicit guards and ownership flags


Storage reliability matters

Single storage layer not enough for mobile


Logging is critical

Helped identify the 100ms auto-accept bug quickly


Files Modified

Issue #1-5 (Native FCM Implementation)


plugins/withAndroidFCMService.js - Generates FCM service, manages manifest
plugins/withNeonNativeModule.js - Generates native module, auto-registers
app.config.ts - Plugin registration
contexts/CallContext/platformSetup.android.ts - Added handleIntentIncomingCall()
utils/intentHandler.ts - New utility for Intent data handling
utils/notificationManager.ts - Notification management
utils/voipPushHandler.ts - Enhanced with triple storage

Issue #6 (Auto-Accept Bug Fix)


contexts/CallContext/CallContextProvider.tsx - Conditional auto-accept logic
contexts/CallContext/platformSetup.android.ts - React state initialization, answered flag, race guards


Outstanding Issues


Issue
Service Affected
Priority
Status


Merge conflicts
PR #20
P0
✅ Resolved


Missing foreground service type
NeonFirebaseMessagingService
P0
✅ Added


Missing BootReceiver.kt
BootReceiver
P2
⚠️ Need implementation


Production APK testing
All
P1
⏳ In progress


Auto-accept bug
CallContext
P0
✅ Fixed (Issue #6)


Recommendations

Completed ✅


✅ Resolved PR #20 merge conflicts
✅ Added foreground service type to FCM service
✅ Fixed auto-accept bug - Answer/decline buttons now shown correctly
✅ Added race condition guards - Prevent duplicate initialization

In Progress ⏳


Test production APK on Android 12, 13, 14+ devices
Validate time-to-display: Target <3 seconds from FCM to answer buttons
OEM-specific testing: Samsung, Google Pixel, OnePlus

Future Improvements


Implement or remove BootReceiver - Clean up incomplete boot receiver implementation
Reduce Intent handler delay - Test if 1s works instead of 2s
ConnectionService reliability - Investigate why native UI sometimes doesn't appear
Add E2E testing - Detox/Maestro for automated testing

Expected Outcomes


Before: 20-30s delay or missed calls, auto-accept without consent
After PR #20: <1s native call UI, <3s to Daily.co connection
After Issue #6: Clear answer/decline buttons, user consent required
After production testing: Android 14+ compatibility, faster boot recovery


Testing Strategy

Manual Test Scenarios


✅ Kill app → Send FCM → Tap notification

Expected: Answer/decline buttons appear
Verify: No auto-accept


✅ Background app → Send FCM → Tap notification

Expected: Answer/decline buttons appear
Verify: Quick response time


✅ Foreground app → Send FCM

Expected: In-app answer/decline UI
Verify: No notification disruption


✅ Kill app → Tap native Answer immediately

Expected: Auto-accept when React ready
Verify: Seamless transition to active call


✅ Answer → Decline → Answer again

Expected: Clean state transitions
Verify: No state leakage between calls


Automated Testing (Future)


Mock FCM messages with different app states
Test storage fallback chain
Verify race condition guards
State machine transition coverage


Technical Decisions

Why Native Service Over Headless JS?


Factor
Headless JS
Native Service


Cold start time
Unreliable
<1s


Doze mode impact
+10-15s delay
No delay


Battery optimization
Killed aggressively
Protected for phone calls


Industry standard
❌ Not used
✅ WhatsApp, Viber, Signal


Why Triple-Storage Fallback?


Memory: Fast, but lost when app killed
AsyncStorage: Persists, but slow on cold start (async I/O)
SharedPreferences: Native, instant, survives kill

Ensures call data available regardless of app state.
Why Conditional Auto-Accept?

Problem: Original implementation auto-accepted after 100ms, removing user choice.
Solution: Only auto-accept when user explicitly tapped native Answer button before React was ready.
Benefits:

Respects user consent
Clear UI feedback (answer/decline buttons)
Preserves native UI integration for fast answers
No UX confusion about call state


Sources

GitHub


PR #17: Lock Screen Display Fix - MERGED
PR #20: Native FCM Service - MERGED
Gist #1: Call Flow Documentation
Gist #2: Performance Analysis & Logs

Codebase References


utils/callKeepService.ts - CallKeep integration, module-level didDisplayIncomingCall listener (line 46-84)
utils/voipPushHandler.ts - Triple-storage system for call data persistence
contexts/CallContext/CallContextProvider.tsx - Cold-start rehydration, conditional auto-accept (Issue #6 fix)
contexts/CallContext/platformSetup.android.ts - Intent handler, race guards, answered flag (Issue #6 fix)
plugins/withAndroidCallKeep.js - VoiceConnectionService manifest configuration
plugins/withAndroidFCMService.js (PR #20) - Native FCM service setup, removes RN Firebase default service

Android Documentation


TelecomManager API - Native call UI integration
FirebaseMessagingService - FCM native handler
Foreground Service Types (Android 14+) - phoneCall, microphone types
Direct Boot Mode - Boot receiver considerations

React Native Ecosystem


React Native Firebase Headless JS - Limitations documented
react-native-callkeep - VoiceConnectionService wrapper

Key Insights


Android Doze Mode: Power management best practices
FCM Service Priority: First declared service in manifest gets priority
Lock Screen Permissions: USE_FULL_SCREEN_INTENT requires runtime permission on Android 12+
User Consent: Never auto-accept calls without explicit user interaction


Validation Checklist

Pre-Production


 PR #17 merged successfully
 PR #20 merged successfully
 Issue #6 (auto-accept bug) fixed
 Race condition guards implemented
 chore/backend-issues merged or abandoned
 Production APK tested on Android 12, 13, 14+
 Logs confirm [NATIVE FCM] appears (not [FCM Headless])
 Time-to-display measured: <3s target
 No MissingForegroundServiceTypeException errors
 Answer/decline buttons appear correctly on notification tap
 Auto-accept only happens when user taps native Answer button
 Battery optimization whitelisting documented for users
 OEM-specific quirks tested (Samsung, Pixel, OnePlus)

Post-Production Monitoring


Monitor call answer rates (expect increase after fix)
Track time-to-display metrics
Watch for auto-accept bugs in analytics (should be eliminated)
User feedback on answer/decline button visibility
Crash reports related to call handling


Conclusion

This solution represents a mature, battle-tested architecture for handling Android incoming calls via FCM. It balances:

Reliability (triple storage, fallback chains)
User experience (explicit consent, clear UI)
Performance (parallel paths, race protection)
Maintainability (plugin-generated code, clear patterns)

Key insight: Don't fight the platform, work with it. We use notifications as primary UI, native ConnectionService as optional enhancement, and in-app React UI as reliable fallback. This hybrid approach gives us the best of all worlds.
Time from problem to solution: 6 iterations across multiple PRs and branches:

Issues #1-5: Native FCM implementation and debugging
Issue #6: Critical UX fix for auto-accept bug
Result: Production-ready solution with proper user consent


Last Updated: 2025-12-20
Author: Nick Konecny (@konecnyna)
Reviewers: Claude Code (AI)
Status: Issue #6 completed, ready for production testing
Why?	Answer	Evidence
Why missed?	FCM message not processed in time	Logs show 20-30s delay or no processing
Why not processed?	Headless JS takes 18-20s to initialize	Gist #2: Cold start breakdown
Why so slow?	React Native requires full JS engine boot	Hermes init: 2-3s, Metro: 1.5s, RN: 3s, Headless: 10-12s
Why not use native?	React Native Firebase plugin intercepts FCM	Logs show `[FCM Headless]` not `[NeonFCMService]`
Why intercept?	Default service registered first in manifest	Android dispatches to first matching service
Scenario	Old Behavior	New Behavior
User taps notification (app killed)	❌ Auto-accepts after 100ms → Shows active call UI	✅ Shows answer/decline buttons → User makes choice
User taps native Answer (React not ready)	✅ Auto-accepts correctly	✅ Auto-accepts correctly (preserved)
User taps native Answer (React ready)	✅ Auto-accepts immediately	✅ Auto-accepts immediately (preserved)
Foreground FCM	✅ Shows answer/decline	✅ Shows answer/decline (preserved)
Issue	Service Affected	Priority	Status
Merge conflicts	PR #20	P0	✅ Resolved
Missing foreground service type	NeonFirebaseMessagingService	P0	✅ Added
Missing BootReceiver.kt	BootReceiver	P2	⚠️ Need implementation
Production APK testing	All	P1	⏳ In progress
Auto-accept bug	CallContext	P0	✅ Fixed (Issue #6)
Factor	Headless JS	Native Service
Cold start time	18-20s	<1s
Doze mode impact	+10-15s delay	No delay
Battery optimization	Killed aggressively	Protected for phone calls
Industry standard	❌ Not used	✅ WhatsApp, Viber, Signal
Why?	Answer	Evidence
Why missed?	FCM message not processed in time	Logs show delays or no processing
Why not processed?	Headless JS unreliable on cold start	Gist #2: Cold start breakdown
Why so slow?	React Native requires full JS engine boot	React Native requires full JS engine boot
Why not use native?	React Native Firebase plugin intercepts FCM	Logs show `[FCM Headless]` not `[NeonFCMService]`
Why intercept?	Default service registered first in manifest	Android dispatches to first matching service
Factor	Headless JS	Native Service
Cold start time	Unreliable	<1s
Doze mode impact	+10-15s delay	No delay
Battery optimization	Killed aggressively	Protected for phone calls
Industry standard	❌ Not used	✅ WhatsApp, Viber, Signal