Lorixen.
EN

Adding product images to your app's push notifications

Short answer: On Android, an image URL in the notification is usually enough: the system downloads and shows it. On iPhone, the app needs a notification service extension, a small extra component that receives the notification just before it's shown, downloads the image and attaches it, and your server must mark the notification as modifiable with mutable-content: 1. If the extension is missing, the flag isn't set, the download is slow or the URL doesn't look like an image, iPhone users get plain text. Keep images small, served over HTTPS from a fast host, and test on real devices.

Why images are worth it, and why they go missing

A product photo in a "back in stock" alert or an order update with the item's picture is easier to recognise at a glance. But teams often launch image notifications, test on an Android phone, and only later notice iPhone customers see text only.

The reason is architectural. Notifications are kept small, so the image itself isn't in the message; only its address is. Someone has to fetch it before the notification appears. Android's notification system does that for you when you use a supported field. iOS hands that job to your app.

iPhone: the notification service extension

Apple's documentation describes modifying a remote notification before it's displayed, for reasons including downloading images or other media attachments that would exceed the maximum payload size. It requires a notification service app extension, which ships inside your app bundle and receives the notification's contents before the system displays them.

Setting it up:

  1. In Xcode, add a new target and choose Notification Service Extension.
  2. In its handler, read the image URL from the notification payload, download the image, save it to a temporary file and attach it to the notification content.
  3. Call the completion handler with the updated content.

Apple notes the extension has only about 30 seconds to modify the payload and call the completion handler. If it runs out of time, a second method is called and you must return whatever you have immediately; if the completion handler is never called, the system shows the original notification. So a slow image server means text-only notifications.

Apple also notes the extension only runs for notifications set to show an alert. Silent notifications, or ones that only update a badge or play a sound, don't trigger it.

The server side: mark it modifiable

The extension only runs when the notification's payload says it may be modified, the mutable-content flag. If you send through Firebase Cloud Messaging, its documentation lists the options for an image across platforms:

  • Android: set notification.image to the image URL.
  • iOS: set fcm_options.image to the image URL and include the header mutable-content: 1.

Firebase's documentation adds that Apple requires the image URL to include a valid file extension so the resource type can be identified. A URL like /images/12345 with no .jpg or .png may fail on iOS even though it loads in a browser. It also notes images uploaded through its notifications composer are limited to 300KB.

Other push services have equivalent fields; check their documentation for the iOS flag.

Make images reliable

  • Small files. Resize and compress images specifically for notifications; there's no need for a full product photo.
  • Fast, public HTTPS URLs. Serve them from a CDN. The phone downloads them over whatever connection it has, possibly a weak mobile signal.
  • Stable URLs. Don't use links that expire within minutes; notifications may be delivered later if the phone was off.
  • Sensible formats. JPEG and PNG are the safe choices.
  • Fallback text that stands alone. The words must make sense without the image, because sometimes it won't load.

Android notes

On Android, the image appears when the notification is expanded, and some launchers show a thumbnail when collapsed. If your app handles data-only messages itself instead of using the notification field, your code has to download the image and build the notification, with the same reliability concerns as iOS.

Testing checklist

  1. Send a test notification with an image to an iPhone and an Android phone, with the app closed.
  2. Repeat on a slow connection to check what happens when the download is slow.
  3. Try an image URL without a file extension to confirm your URLs are in the right form.
  4. Check that the iOS extension is included in the release build and enabled for the right app ID.
  5. Confirm the extension is signed and provisioned correctly, since it's a separate target.

Don't overdo it

Images make notifications more noticeable, which cuts both ways. Use them for things customers actually care about: their order, an item they saved, a booking. A stream of image-heavy promotions gets notifications turned off.

A worked example

An illustrative Denver sneaker shop added product photos to "back in stock" notifications. Android users saw them immediately; iPhone users saw plain text. The developer found the app had no notification service extension, and the image URLs came from a resizing service without file extensions. They added the extension, switched to URLs ending in .jpg from the CDN, set mutable-content on iOS sends, and resized images for notifications. Images appeared on both platforms, with plain text as the fallback on poor connections.

FAQ

Can I add buttons as well as images?

Yes, notifications can include action buttons on both platforms, set up through notification categories or actions.

Does the extension drain battery?

It runs briefly for each notification that requests it, then stops.

Can I show a GIF or video?

iOS attachments support some animated images and video, but large files often time out. A still image is more reliable.

Why do images work in testing but not for some customers?

Slow connections, expired URLs or older app versions without the extension are the usual causes.

If your app's notifications need images, buttons or better reliability, tell us how you send them today and we'll help you set them up on both platforms.

Sources

WhatsAppBook a call