This guide details push notification images for mobile apps.

• For Web Push, see Web Push Notifications Guide.
• For In-App Messages, see Design In-App Messages with Drag and Drop.
• For Email, see Design Emails with Drag and Drop.
• For SMS, see Sending SMS Messages .

Mobile app images

There are 2 types of images on notifications:

1. Icons: smaller images that are generally used for brand recognition. iOS icons are set automatically based on the app's icon. Android supports large and small icons which can be updated. See Notification icons for more details.
2. Big Picture: Large mobile push images that may look small in the "collapsed view" and will display fully in the "expanded view" of the notification.

When big pictures are added on Android notifications, they will generally show expanded when they are first in your Notification Center of the device. This depends on the device and Android version. iOS notifications generally need to be long-pressed or swiped to view.

Images can be added to push using the Dashboard or API Image Parameters.

Recommended image details

The recommended image is a jpg filetype with 2:1 aspect ratio landscape, size 512x256px or 1440x720px.

• gif image animations not supported on Android mobile apps.
• Adding Action Buttons may affect image sizes, please try testing on your devices to make sure the layout fits your needs.
• Android 4.1+ and iOS 10+ supports large images.
• For troubleshooting, see Notification Images Not Showing.

🚧

Push Media Upload Limitations

OneSignal has a 5MB limit on images you upload to our server and does not support uploading video or audio media.

OneSignal only stores images uploaded to our servers for 33 days from the time it was uploaded.

If you duplicate or use a draft message with an image uploaded longer than 33 days, you will need to re-upload the image.

If you need the image for longer, you can use templates or store the image on your own servers and reference the resource URL directly.

---

Rich notifications

Android and iOS allow for certain customizations to be done in your app to change the way notifications display to your users. Along with changing the visuals and adding media, you can also setup Action buttons, Notification grouping, and Remove notifications & TTL.

Android custom notification layout

For Android apps, you can build a custom notification layout which changes how the notification is displayed to the user. Starting with Android 12 (API level 31), apps targeting Android 12 or higher are no longer able to create fully custom notifications as they were with Android 11 and lower. Instead, the system applies a standard template nearly identical to the behavior of Notification.DecoratedCustomViewStyle.

See Android's developer guide to create a custom notification layout and add your customizations to our Notification Service Extension.

iOS content extensions

Content extensions allow developers to add custom views of their app within a notification. These require additional development with the UNNotificationContentExtension and once setup, these custom views can do almost anything from playing videos, allowing users to chat without opening the app, update calendar events, and much more. See our guide on iOS Image Carousel Push Notifications for an example.

Media Attachments

Media attachments allow developers to attach URLs to relevant content. This is most commonly used for images. If you want to send video in your push, this will you will need to implement the UNNotificationContentExtension.

Supported media formats

Media formats supported by iOS 10+.

Make sure the hosted image, video or audio is a direct link to the resource. If it does not end in a correct file extension (listed File Type's below), you can add for example &file=type.mp4 (use your resource's correct .file_extension) to the end of the url so our SDK recognizes this as a media url.

🚧

Media Uploads

OneSignal has a 5MB limit on images you upload to our server and does not support uploading video or audio media.

You would need to host the video or larger image files on your own servers and include the URL to the resource.

* The OneSignalNotificationServiceExtension should already be available in your mobile app if you implemented the OneSignal SDK following our Mobile Setup docs. This is responsible for images, badges, and confirmed delivery tracking.

---

Mobile Push Image Troubleshooting

See Notification Images Not Showing Troubleshooting guide.