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
- Xcode Setup: To receive silent pushes, you must enable the Remote notifications checkbox under Signing & Capabilities → Background Modes in Xcode.
- 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).
- 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-contentkey will be completely ignored by iOS if the payload does not contain analertdictionary. 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
| Feature | content-available: 1 | mutable-content: 1 |
|---|---|---|
| Primary Purpose | Silent data sync | Modifying visible push content |
| What does it wake? | The main App (in the background) | The Notification Service Extension |
| Does it show UI? | No (unless combined with alert) | Yes (Requires alert to work) |
| Best used for | Chat updates, background pre-fetching | Adding images/media, text decryption |
| System restrictions | Subject to heavy battery/background limits | Strict 30-second execution timeout |
Comments
0 comments
Article is closed for comments.