iOS Push Payload Keys: content-available and mutable-content

When sending push notifications to iOS devices, the system's behavior is dictated by the aps dictionary within your JSON payload. There are frequently confused keys: content-available and mutable-content.

While both allow your app to execute code in the background, they serve completely different purposes. Here is a comprehensive guide to what they do, how they work, and when to use them.

content-available: 1 (Silent Push Notifications)

The "content-available": 1 key is used to send Silent Push Notifications.

Instead of showing a visible banner or playing a sound, this key tells the iOS operating system to wake your app up in the background. This allows your app to silently fetch new data, synchronize with your server, or update its local database before the user even opens it.

How it works

When the device receives a payload with this key, iOS launches your app in the background and triggers the application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method in your AppDelegate. Your app is granted a small amount of execution time (usually up to 30 seconds) to complete its background tasks.

Common Use Cases

• Downloading new chat messages in the background.
• Syncing a local database with a remote server.
• Pre-fetching content (like news articles or weather updates) so the app loads instantly when the user taps the app icon.

Example Payload

Notice the absence of the alert and sound keys. If you include an alert, it becomes a regular visible push notification that also wakes the app.

{
  "aps": {
    "content-available": 1,
    "badge": 5
  }
}

Important Limitations

1. Xcode Setup: To receive silent pushes, you must enable the Remote notifications checkbox under Signing & Capabilities → Background Modes in Xcode.
2. Delivery is not guaranteed: iOS strictly manages device battery life. If the device is low on power, or if the user rarely opens your app, iOS may delay or completely drop silent push notifications (Apple refers to this as Background Execution Limits).
3. No Open Tracking: Because there is no visible banner for the user to tap, analytics tools cannot track "Push Opens" for purely silent notifications.

mutable-content: 1 (Rich Notifications & Service Extension)

Introduced in iOS 10, the "mutable-content": 1 key is used to modify the content of a notification before it is displayed to the user.

Unlike content-available (which wakes the main app), mutable-content wakes up a specialized mini-app bundled within your project called a Notification Service Extension (UNNotificationServiceExtension).

How it works

When iOS receives a push with this key, it holds off on displaying the notification to the user. Instead, it passes the payload to your Notification Service Extension. The extension is given a strict time limit (about 30 seconds) to process the payload, download attachments, or change the text. Once the extension finishes its work, the modified notification is presented to the user.

Common Use Cases

• Rich Media: Downloading images, GIFs, audio, or video files from a URL provided in the payload and attaching them to the notification.
• Dynamic Localization: Modifying the push notification's title or body text based on local user data or preferences stored on the device.
• End-to-End Encryption: Receiving an encrypted payload from the server and decrypting the message text securely on the device just before displaying it.

Example Payload

In this example, the extension will intercept the push, look for the custom media_url key, download the image, attach it to the alert, and then display it.

{
  "aps": {
    "alert": {
      "title": "New Event",
      "body": "Check out the new venue map!"
    },
    "mutable-content": 1
  },
  "media_url": "https://example.com/venue-map.jpg"
}

Important Limitations

• Requires an Alert: The mutable-content key will be completely ignored by iOS if the payload does not contain an alert dictionary. You cannot use it to modify silent pushes.
• Time Limits: If your extension takes too long to download an image (e.g., due to a slow network) and hits the 30-second timeout, iOS will forcefully display the original, unmodified notification.

Summary