OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Android Notification Icons

Adding custom icons to some or all of your notifications. Works with Android (and derivatives like Amazon).

Icons are a way to provide a more unique, branded experience for your Android and Amazon app.

You may add a default icon that appears with every notification you send, or you may add icons to just certain types of notifications. The below tutorial shows you how to do both.

About Notification Icons

Android supports both Small and Large Notification Icons.

Small Notification Icons - by default our SDK automatically uses either a white bell icon or your App's launcher icon. Starting with Android 5, the OS forces Small Notification Icons to be all white when your app targets Android API 21+. If you don't make a correct icon, it will most likely be displayed as a bell or solid white icon in the status bar.

Large Notification Icons - The large notification icon will show up to the left of the notification text on Android 4.0.3 - 6.0 devices, and shows on the right for Android 7.0+ devices. If you do not set a large icon, the small icon will be used instead. OneSignal will auto scale large notification icons for you to prevent the icon from being cropped.

How to Add Default Icons

We strongly recommend adding default icons to every Android and Amazon app.

1. Generate Icons


Add every icon size, transparency, & alpha channel

  • If you miss an icon size, it may not display correctly.

  • If you see a solid square, you set the image correctly, but did not generate with transparency in the shape you want to show. For more help, see this clipart link for examples in the Android Asset Studio

  • If you see a white square in the preview on the page above you did not set the alpha channel correctly on your icon.

Option A: Using Android Asset Studio

  • Recommended

To quickly and easily generate small icons with the correct settings, we recommend using the Android Asset Studio. Use ic_stat_onesignal_default as the name.

Option B: Manually Create Icons

  • Not Recommended

Small Icon

If you prefer to create your own icons, you must make your icons the following size and colors:


Size (px)

Small Notification Icon (mdpi)


Small Notification Icon (hdpi)


Small Notification Icon (xhdpi)


Small Notification Icon (xxhdpi)


Small Notification Icon (xxxhdpi)


Other - Large Icon


Size (px)

Large Notification Icon (xxxhdpi)


2. Create project paths

Make sure the following paths exist, create any folders you are missing.
Android Studio Native SDK icons would go like this:


File path

Android Native

res/drawable-mdpi/ (24x24)
res/drawable-hdpi/ (36x36)
res/drawable-xhdpi/ (48x48)
res/drawable-xxhdpi/ (72x72)
res/drawable-xxxhdpi/ (96x96)
res/drawable-xxxhdpi/ (256x256) (Large Icon)


Assets/Plugins/Android/OneSignalConfig/res/drawable-mdpi/ (24x24)
Assets/Plugins/Android/OneSignalConfig/res/drawable-hdpi/ (36x36)
Assets/Plugins/Android/OneSignalConfig/res/drawable-xhdpi/ (48x48)
Assets/Plugins/Android/OneSignalConfig/res/drawable-xxhdpi/ (72x72)
Assets/Plugins/Android/OneSignalConfig/res/drawable-xxxhdpi/ (96x96)
Assets/Plugins/Android/OneSignalConfig/res/drawable-xxxhdpi/ (256x256) (Large Icon)

PhoneGap, Cordova, Ionic, Intel XDK

<project-root>/platforms/android/app/src/main/res/drawable-mdpi/ (24x24)
<project-root>/platforms/android/app/src/main/res/drawable-hdpi/ (36x36)
<project-root>/platforms/android/app/src/main/res/drawable-xhdpi/ (48x48)
<project-root>/platforms/android/app/src/main/res/drawable-xxhdpi/ (72x72)
<project-root>/platforms/android/app/src/main/res/drawable-xxxhdpi/ (96x96)
<project-root>/platforms/android/app/src/main/res/drawable-xxxhdpi/ (256x256) (Large Icon)

PhoneGap Build (PGB), Ionic Package
(Cloud Build)

<project-root>/locales/android/drawable-mdpi/ (24x24)
<project-root>/locales/android/drawable-hdpi/ (36x36)
<project-root>/locales/android/drawable-xhdpi/ (48x48)
<project-root>/locales/android/drawable-xxhdpi/ (72x72)
<project-root>/locales/android/drawable-xxxhdpi/ (96x96)
<project-root>/locales/android/drawable-xxxhdpi/ (256x256) (Large Icon)

See this github link for more details on the directory structure if you're having issues.

React Native

android/app/src/main/res/drawable-mdpi/ (24x24)
android/app/src/main/res/drawable-hdpi/ (36x36)
android/app/src/main/res/drawable-xhdpi/ (48x48)
android/app/src/main/res/drawable-xxhdpi/ (72x72)
android/app/src/main/res/drawable-xxxhdpi/ (96x96)
android/app/src/main/res/drawable-xxxhdpi/ (256x256) (Large Icon)


Add files to root (all sizes)


Resources/drawable-mdpi/ (24x24)
Resources/drawable-hdpi/ (36x36)
Resources/drawable-xhdpi/ (48x48)
Resources/drawable-xxhdpi/ (72x72)
Resources/drawable-xxxhdpi/ (96x96)
Resources/drawable-xxxhdpi/ (256x256) (Large Icon)


Issue with Older Versions of Cordova

With versions of Cordova before 7.0, you will need to use
instead of the path shown above when adding the icon resource to config.xml

3. Name Icons Appropriately

Next, you must be sure the icon filenames are correct. If you used Android Asset Studio for your small icon then this step may have already been done for you.



Native, Unity,
PhoneGap, Cordova, Ionic,
PhoneGap Build (PGB), Xamarin, React Native, Ionic Package
(Cloud Build)

/drawable-xxxhdpi/ic_onesignal_large_icon_default.png (Large Icon)


IconNotificationDefault-ldpi.png (16x16)
IconNotificationDefault-mdpi.png (24x24)
IconNotificationDefault-hdpi.png (36x36)
IconNotificationDefault-xhdpi.png (48x48)
IconNotificationDefault-xxhdpi.png (72x72)
ic_onesignal_large_icon_default.png (256x256)(Large Icon)

4. PhoneGap Build (PGB) & Ionic Cloud Build

Add the following lines to your config.xml under the Android section.

<!-- Add to your existing android platform sction -->
<platform name="android">
    <resource-file src="locales/android/drawable-mdpi/ic_stat_onesignal_default.png" target="res/drawable-mdpi/ic_stat_onesignal_default.png" />
    <resource-file src="locales/android/drawable-hdpi/ic_stat_onesignal_default.png" target="res/drawable-hdpi/ic_stat_onesignal_default.png" />
    <resource-file src="locales/android/drawable-xhdpi/ic_stat_onesignal_default.png" target="res/drawable-xhdpi/ic_stat_onesignal_default.png" />
    <resource-file src="locales/android/drawable-xxhdpi/ic_stat_onesignal_default.png" target="res/drawable-xxhdpi/ic_stat_onesignal_default.png" />
    <resource-file src="locales/android/drawable-xxxhdpi/ic_stat_onesignal_default.png" target="res/drawable-xxxhdpi/ic_stat_onesignal_default.png" />
  <!-- Uncomment if you have added a large icon. -->
  <!--- <resource-file src="locales/android/drawable-xxxhdpi/ic_onesignal_large_icon_default.png" target="res/drawable-xxxhdpi/ic_onesignal_large_icon_default.png" /> --->
<!-- Add to your existing android platform sction -->
<platform name="android">
    <resource-file src="locales/android/drawable-mdpi/ic_stat_onesignal_default.png" target="app/src/main/res/drawable-mdpi/ic_stat_onesignal_default.png" />
    <resource-file src="locales/android/drawable-hdpi/ic_stat_onesignal_default.png" target="app/src/main/res/drawable-hdpi/ic_stat_onesignal_default.png" />
    <resource-file src="locales/android/drawable-xhdpi/ic_stat_onesignal_default.png" target="app/src/main/res/drawable-xhdpi/ic_stat_onesignal_default.png" />
    <resource-file src="locales/android/drawable-xxhdpi/ic_stat_onesignal_default.png" target="app/src/main/res/drawable-xxhdpi/ic_stat_onesignal_default.png" />
    <resource-file src="locales/android/drawable-xxxhdpi/ic_stat_onesignal_default.png" target="app/src/main/res/drawable-xxxhdpi/ic_stat_onesignal_default.png" />
  <!-- Uncomment if you have added a large icon. -->
  <!--- <resource-file src="locales/android/drawable-xxxhdpi/ic_onesignal_large_icon_default.png" target="app/src/main/res/drawable-xxxhdpi/ic_onesignal_large_icon_default.png" /> --->


Done! You should be all set with your new default icons

How to Add Non-Default Icons

  • Optional

After you've added your default icons, you may choose to add more non-default icons. These will let you show different icons depending on the types of notifications your app sends. For instance, a game with a title like "Jewel Breaker" may wish to have a different colored jewel icon for every notification sent that represents the player's level. Meanwhile, a social network may wish to show a chat bubble icon when the user receives a message from another user to differentiate those notifications from more generic system notifications.

OneSignal supports overriding default icons on a per-message basis.

1. Generate Icons

Follow the steps above to generate icons and place them in the appropriate folder for your SDK.

2. Name Non-Default Icons

To add non-default icons, you must name them something other than the default names specified above. For instance, you may name one message_icon.

3. Send Notifications with Non-Default Icons

If you've followed the above steps for creating default icons, and have updated your app, you'll be able to reference those icons when you send a notification. To send a notification with an icon, within New Message open Android Options, and specify the icon to use.

Do not add the file extension when referencing the icon file. For instance, in the below example the file is referenced as message_icon.

With Large Notification Icons, you can also supply a URL where the icon will be displayed from.

REST API - Instead of sending via the dashboard, you can send notifications with icons in the REST API by using the appropriate parameter and file extension depending on your platform (see more in Create notification REST API docs).

Additional Options

Small Icon Accent Color

Android 5.0+ enforces your icon to only be white and transparent however it still allows tinting on the notification shown in the shade, known as the "accent color". (The status bar icon color will still be unaffected). These may be adjusted in New Message or as defaults in your manifest.

Set default Small Icon and Accent Colors

To set a default color add the following line to your AndroidManifest.xml in the <application> root.

<!-- Example: Sets all OneSignal notification's accent color to Green by default.  -->
<!-- Color format is in ARGB. -->
<meta-data android:name="com.onesignal.NotificationAccentColor.DEFAULT" android:value="FF00FF00" />

To set the color on per notification bases set android_accent_color on our Create notification API call, or enter a value in the Accent color field under Options > Android on New Message.


New icons take a while to propagate to all users

If you've very recently added an icon resource to your app, you may want to wait a few days before sending notifications using the icon. This is because it can take many days or even weeks for the majority of your users to update their apps to the latest version which contain your new icons.

Updated 3 months ago

What's Next

Learn about setting up more features, or start using the OneSignal Dashboard

Features Setup

Android Notification Icons

Adding custom icons to some or all of your notifications. Works with Android (and derivatives like Amazon).

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.