How to fix messaging/payload-size-limit-exceeded: Exceeds 4096-byte limit in Firebase

// Example: Calculate payload size
const message = {
  token: 'your-fcm-token',
  notification: {
    title: 'Your Notification Title',
    body: 'Your notification body text here'
  },
  data: {
    // Your custom data fields
    userId: '12345',
    action: 'view_profile',
    timestamp: '2025-01-15T10:30:00Z',
    // ... other data fields
  }
};

// Calculate the serialized size
const payloadString = JSON.stringify(message);
const payloadSize = Buffer.byteLength(payloadString, 'utf8');
console.log('Current payload size: ' + payloadSize + ' bytes');
console.log('Limit: 4096 bytes');
console.log('Over by: ' + (payloadSize - 4096) + ' bytes');

// For Firebase Admin SDK, you can log the size before sending
const admin = require('firebase-admin');
console.log('Message size before sending:', payloadSize);

// BEFORE: Large payload with unnecessary fields
const largeMessage = {
  token: registrationToken,
  notification: { title: 'Alert', body: 'Something happened' },
  data: {
    userId: '12345',
    userName: 'John Doe',
    userEmail: '[email protected]',
    userAvatar: 'https://example.com/avatar.jpg',
    action: 'view_profile',
    timestamp: '2025-01-15T10:30:00.000Z',
    sessionId: 'abc123def456',
    deviceInfo: 'iPhone14,2 iOS 17.2',
    debug: true,
    source: 'mobile_app_v2.1.0'
  }
};

// AFTER: Optimized payload with only essential data
const optimizedMessage = {
  token: registrationToken,
  notification: { title: 'Alert', body: 'Something happened' },
  data: {
    userId: '12345',        // Keep only what's needed client-side
    action: 'view_profile'   // Essential action identifier
  }
};

// Calculate savings
const beforeSize = Buffer.byteLength(JSON.stringify(largeMessage), 'utf8');
const afterSize = Buffer.byteLength(JSON.stringify(optimizedMessage), 'utf8');
console.log('Reduced from ' + beforeSize + ' to ' + afterSize + ' bytes (' + Math.round((beforeSize - afterSize) / beforeSize * 100) + '% reduction)');

// BEFORE: Verbose format
const verboseData = {
  user_identification_number: '12345',
  action_type: 'profile_view',
  notification_timestamp: '2025-01-15T10:30:00.000Z',
  additional_metadata: {
    platform: 'ios',
    version: '2.1.0',
    build_number: '45'
  }
};

// AFTER: Optimized format
const optimizedData = {
  uid: '12345',           // Shorter key
  act: 'pv',              // Abbreviated action code
  ts: 1736929800000,      // Unix timestamp (number, not string)
  m: {                    // Nested metadata with short keys
    p: 'ios',
    v: '2.1.0',
    b: '45'
  }
};

// Use numbers instead of strings where possible
const dataWithNumbers = {
  userId: 12345,          // Number instead of string
  score: 95.5,            // Number for numeric values
  isActive: true,         // Boolean instead of string 'true'
  tags: ['urgent', 'user'] // Array of short strings
};

// Avoid base64 in data payload - use URLs instead
// BAD: data: { image: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...' }
// GOOD: data: { imageUrl: 'https://cdn.example.com/image.png' }

// Strategy 1: Split data across multiple messages
async function sendSplitNotification(userId, largeData) {
  const token = await getFCMToken(userId);

  // First message: Basic notification
  const notificationMsg = {
    token: token,
    notification: {
      title: 'Data Available',
      body: 'Your data is ready to download'
    },
    data: {
      type: 'data_available',
      dataId: largeData.id
    }
  };

  await admin.messaging().send(notificationMsg);

  // Second message: Additional data (if needed)
  const dataMsg = {
    token: token,
    data: {
      type: 'data_payload',
      dataId: largeData.id,
      chunk: JSON.stringify(largeData.chunk1)
    }
  };

  await admin.messaging().send(dataMsg);
}

// Strategy 2: Use deep links with server-side data
const messageWithDeepLink = {
  token: registrationToken,
  notification: {
    title: 'View Report',
    body: 'Your monthly report is ready'
  },
  data: {
    deepLink: 'myapp://reports/12345',
    // No large data - app fetches from server using the ID
  }
};

// Strategy 3: Use FCM topics for broadcast data
// Send large data once to a topic, then notify users
async function broadcastLargeData(data) {
  // Store data on your server
  const dataId = await storeDataOnServer(data);

  // Send lightweight notification
  const message = {
    topic: 'data_update',
    data: {
      dataId: dataId,
      type: 'new_data'
    }
  };

  await admin.messaging().send(message);
}

// Android: Use collapse_key for similar messages
const androidMessage = {
  token: registrationToken,
  android: {
    collapse_key: 'daily_notification', // Collapse similar messages
    priority: 'high',
    ttl: 3600, // 1 hour
    notification: {
      title: 'Daily Update',
      body: 'Your daily summary is ready',
      icon: 'ic_notification',
      color: '#FF5722'
    }
  },
  data: {
    // Minimal data - Android can store some in notification itself
    updateId: '123'
  }
};

// iOS: Use mutable-content for on-device processing
const iosMessage = {
  token: registrationToken,
  apns: {
    payload: {
      aps: {
        alert: {
          title: 'Update Available',
          body: 'New content is ready'
        },
        'mutable-content': 1, // Allow notification service extension
        sound: 'default'
      }
    },
    headers: {
      'apns-priority': '10'
    }
  },
  data: {
    // iOS Notification Service Extension can fetch additional data
    fetchUrl: 'https://api.example.com/notification/123'
  }
};

// Web: Use actions instead of large data
const webMessage = {
  token: registrationToken,
  webpush: {
    notification: {
      title: 'Action Required',
      body: 'Please review this item',
      icon: '/icon.png',
      actions: [
        {
          action: 'approve',
          title: 'Approve'
        },
        {
          action: 'reject',
          title: 'Reject'
        }
      ]
    }
  },
  data: {
    // Web can use service worker to fetch additional data
    itemId: '123'
  }
};

// Validation middleware for all FCM messages
function validateFCMPayload(message) {
  const payloadString = JSON.stringify(message);
  const size = Buffer.byteLength(payloadString, 'utf8');

  if (size > 4096) {
    throw new Error('FCM payload size ' + size + ' bytes exceeds 4096-byte limit');
  }

  // Additional validation
  const data = message.data || {};
  const dataKeys = Object.keys(data);

  // Warn about common issues
  if (size > 3500) {
    console.warn('Warning: Payload size ' + size + ' bytes is close to 4096 limit');
  }

  if (dataKeys.length > 20) {
    console.warn('Consider reducing number of data fields');
  }

  return true;
}

// Usage in your sending logic
async function sendNotification(message) {
  try {
    // Validate before sending
    validateFCMPayload(message);

    // Send the message
    const response = await admin.messaging().send(message);
    console.log('Successfully sent message:', response);
    return response;
  } catch (error) {
    console.error('Failed to send notification:', error.message);

    // Log payload size for debugging
    const size = Buffer.byteLength(JSON.stringify(message), 'utf8');
    console.error('Payload size was: ' + size + ' bytes');

    throw error;
  }
}

// Automated testing for payload size
describe('FCM Payload Size Tests', () => {
  test('notification payload should be under 4096 bytes', () => {
    const message = createTestMessage();
    const size = Buffer.byteLength(JSON.stringify(message), 'utf8');
    expect(size).toBeLessThan(4096);
  });

  test('data-only payload should be under 4096 bytes', () => {
    const dataMessage = { token: 'test', data: createLargeData() };
    const size = Buffer.byteLength(JSON.stringify(dataMessage), 'utf8');
    expect(size).toBeLessThan(4096);
  });
});