Sending web push notifications with images and icons

The following sections describe the best practices for sending web push notifications that include images and icons.

How to add an icon

The icon is displayed on all devices and usually represents your website logo or a profile picture.

You can add a default icon for all your notifications from the project settings.

You can also use a specific icon when you send a notification. If you use the dashboard, you can change it from Advanced settings.

How to add a badge

A badge is a small icon that will be displayed when there is not enough space to display the full notification.

For example the notification badge is displayed in the Android status bar or when the screen is locked: it suggests to the user that there is a new notification.

Sometimes the badge is also displayed inside the notification, near the domain name, but it is very small.

Usually the badge represents the website (e.g. logo) or the notification category (e.g. message icon, heart icon).

The badge must be a PNG image and will be masked automatically: for this reason we recommend to draw a shape over a transparent background.

You can set a default badge for your website in project settings or set a custom badge when you send a notification.

In any case the badge is optional, and if you don't set it, the browser logo will be used.

How to add a large image

Some browsers (e.g. Chrome on Windows and Android) let you display a large image inside the notification content.

You can set the image when you send a notification.

How to add a small icon near the action button

You can add an icon for each action button when you send the notification. However since these icons are very small and each one would create an additional request to your server, you should consider using emoji instead.

How to get the address of an image hosted on your website

All the images and icons must be hosted on your website. When you want to include them in a notification you simply provide the Image URL or the Icon URL.

In order to find the address (URL) of an image, simply open your website with your favorite browser, right click on an image and click Copy Image Address.

Suggested format

For icons and badges the suggested format is PNG, because it is widely supported and offers a high level of detail.

For the large image the suggested format is JPG, because it is widely supported and offers the best compression.

In any case other formats may be supported as well.

Suggested size

In general you can use any size and the image will be resized automatically by the browser. However keep in mind that very large images may cost you useless bandwith, while very small images offer poor quality.

For the main icon you should use a squared image and the suggested size is 192x192px.

For the small badge displayed in the status bar the suggested size is 96x96px.

For the large image you should use an image which is at least 800px wide.

Using a CDN is recommended

All images and icons should be served from your website using a CDN. This is not only general advice. The point is that when a notification is sent to many recipients, there are thousands of browsers that download your image every second. Make sure that the server or CDN that you use can handle that load, otherwise the download will fail and the image will not be displayed inside the notification.

You can use any scalable CDN, like Cloudflare or AWS CloudFront. However you should not use servers meant for personal use like Dropbox or Google Drive because they have very low rate limits and the image won't be displayed.

Saving bandwidth

In order to save bandwidth it is recommended that you compress your images.

It is also recommended that you use HTTP caching to reduce the number of requests for the same image.

Using HTTPS is recommended

You should serve all your images and icons over HTTPS, otherwise some browsers (e.g. Chrome) may not display them for security reasons.