Skip to main content

Advanced Settings

This section explains powerful customization options for your push notifications. You can fine-tune how messages are delivered and displayed across platforms, and include additional data to support custom behavior in your app. Configure platform-specific features for Android and iOS — such as priority, visual appearance, and behavior — to ensure a consistent and optimized user experience.

Cross-Platform Settings​

Time to Live (TTL)​

The Time to Live (TTL) setting defines how long a push notification should be kept by the FCM servers if it cannot be delivered immediately. This is particularly useful for devices that are offline when you send the notification.

  • Set a specific duration (in seconds, minutes, hours, or days) after which the notification will expire if not delivered
  • When a TTL expires, FCM will no longer attempt to deliver the notification
  • A shorter TTL is better for time-sensitive content, while a longer TTL ensures eventual delivery

Firebase and thus SuperFCM support a TTL of up to 28 days. The default value is 3 days.

Collapse Key​

The collapse key is a string that identifies a group of messages that can be collapsed. When a device is offline, only the last message with the same collapse key is delivered when the device comes online again.

This is useful for:

  • Replacing outdated notifications with newer ones
  • Avoiding notification overload when a device reconnects after being offline
  • Sending only the most recent update of the same type of information

Example use cases:

  • Game Scores- Only show the latest score update
  • New Messages - Only show the latest message count
  • Account Updates - Only deliver the most recent account status
info

Android allows to supply a maximum of 4 different, comma-separated collapse keys per message.

Custom Data Payload​

Attach additional key-value pairs to your notification to support custom handling in your app or to provide extra context. Supported value types include string, boolean, and numeric. Each key must be unique within the notification.

tip

Keys must use only letters, numbers, and underscores. Both snake_case (e.g., order_status_update) and camelCase (e.g., orderStatusUpdate) formats are supported, as long as they follow these character rules.

Example Use Cases

  • Deep linking: {"route": "product", "product_id": "12345"}
  • Categorizing: {"notification_type": "promotion", "promotion_id": "summer_sale"}
  • Feature flags: {"show_image": true, "enable_sound": false}

Data Type Handling​

While values for the custom data payload are strings by default, the system will automatically detect and convert values to the appropriate data type:

  • "true" and "false" strings will be converted to boolean values
  • Numeric strings will be converted to numbers

Android Settings​

Android push notifications can be customized with the following settings:

Priority​

Sets the priority of the notification on Android devices.

  • Normal: The default priority level. Will be delivered immediately if the device is not sleeping. When in doze mode, delivery may be delayed until the device exits doze mode.
  • High: Used for urgent notifications that require immediate attention
warning

High priority messages are meant for time sensitive, user visible notifications. FCM may deprioritize messages in certain cases. Read more.

Notification Count​

Sets the number of items this notification represents. May be displayed as a badge count for devices that support badging. This might be useful if you're using just one notification to represent multiple new messages but you want the count here to represent the number of total new messages.

If zero or unspecified, devices that support badging will increment the number displayed.

Channel ID​

The notification channel ID to assign to this notification, helping users categorize and manage notifications from your app.

If not specified, the channel ID specified in the app manifest will be used.

Sound​

The sound to play when the device receives the notification. Supports "default" or the filename of a sound resource bundled in the app.

Icon​

The name of the notification icon resource to use from your app's resources.

If not specified, the apps launcher icon will be used.

Color​

The accent color of the notification in hexadecimal format (e.g., #ff5733). This affects the color of the notification icon and other accent elements.

Tag​

A string identifier that can be used to replace existing notifications with the same tag. This is useful for updating notifications instead of creating new ones.

Click Action​

The action to perform when the user taps the notification. This can be an activity name or an action defined in your app.

Ticker​

Text to display in the status bar when the notification arrives on older Android versions.

Visibility​

Controls the visibility of the notification on the lock screen:

  • Private: Shows basic information but hides sensitive details (default)
  • Public: Shows the full notification content
  • Secret: Shows no part of this notification on the lock screen

Other Options​

  • Sticky: When enabled, the notification will remain visible until the user dismisses it
  • Local Only: When enabled, the notification will only be shown on the current device and not bridged to connected devices

iOS Settings​

iOS push notifications can be customized with the following settings:

Priority​

The priority level for the notification on iOS devices:

  • 1 (Lowest): For non-time-sensitive notifications
  • 5 (Medium): Standard priority
  • 10 (Highest): For time-critical alerts and notifications

Badge​

The number to display as a badge on the app icon. This should be a number between 0 and 100.

Category​

The notification category for actionable notifications. This corresponds to the UNNotificationCategory identifier you've registered in your app.

Sound​

The sound file to play when the notification is displayed. Use "default" for the system sound or specify a custom sound file bundled with your app.

Interruption Level​

Controls how the notification will interrupt the user:

  • Passive: Doesn't interrupt the user at all
  • Active: Shows in the notification center and may play a sound
  • Time-Sensitive: Will notify the user immediately, even during Focus modes
  • Critical: Will break through Do Not Disturb and can play a sound even if the device is muted

Relevance Score​

A value between 0 and 1 that indicates the importance of this notification relative to others. Higher values (closer to 1) indicate more important notifications.

Thread ID​

A group identifier for related notifications. Notifications with the same thread ID will be grouped together in the notification center.