Send an image in the notification payload

The FCM HTTP v1 API and the Notifications composer support sending image links in the payload of a display notification, for image download to the device after delivery. This functionality supports both images and videos for Apple apps (see Apple documentation for file size limits).

To be able to receive and handle notification images in an Apple app, you must add a Notification Service Extension. The notification service extension allows your app to handle the image delivered in the FCM payload before displaying the notification to the end user.

Set up the notification service extension

To add a service extension, perform the required setup tasks for modifying and presenting notifications in APNs, and then add the FCM extension helper API in NotificationService.m. Specifically, instead of completing the callback with self.contentHandler(self.bestAttemptContent);, complete it with FIRMessaging extensionHelper as shown:

@interface NotificationService () <NSURLSessionDelegate>
@property(nonatomic) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property(nonatomic) UNMutableNotificationContent *bestAttemptContent;
@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];

    // Modify the notification content here as you wish
    self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]",
    self.bestAttemptContent.title];

  // Call FIRMessaging extension helper API.
  [[FIRMessaging extensionHelper] populateNotificationContent:self.bestAttemptContent
                                            withContentHandler:contentHandler];

}
...

Build the send request

In your notification send request, set the following ApnsConfig options:

  • fcm_options.image containing the image URL. Apple requires that the image URL includes a valid file extension to correctly identify the resource type.
  • headers({ "mutable-content": 1})

The following example send request sends a common notification title to all platforms, but it also sends an image. Here's an approximation of the visual effect on a user's device:

Simple drawing of an image in a display notification

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: 'Sparky says hello!'
  },
  android: {
    notification: {
      imageUrl: 'https://foo.bar.pizza-monster.png'
    }
  },
  apns: {
    payload: {
      aps: {
        'mutable-content': 1
      }
    },
    fcm_options: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  webpush: {
    headers: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  topic: topicName,
};

getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
     "topic":"industry-tech",
     "notification":{
       "title":"Sparky says hello!",
     },
     "android":{
       "notification":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "apns":{
       "payload":{
         "aps":{
           "mutable-content":1
         }
       },
       "fcm_options": {
           "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "webpush":{
       "headers":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     }
   }
 }

See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body.

With mutable-content set as shown, this send request enables the service extension on the receiving client to handle the image delivered in the payload.