This guide describes the features and customizations available for Android Mobile apps only.

For iOS, see iOS Customizations and for web, see Web push setup.

Background Data and Notification Overriding

OneSignal supports sending additional data within a notification as key :value pairs. You can read this additional data when a notification is opened with the SDK Notification Event Handlers.

To receive data in the background with or without displaying a notification, see the Notification Service Extension Setup.

To override specific notification settings with client-side app logic (e.g custom accent color, vibration pattern, or any other NotificationCompat options) see Android's documentation on the NotificationCompat options and add your customizations to the Notification Service Extension.

Custom Notification Layout

If you would like to build a custom notification layout, see Android's developer guide to create a custom notification layout and add your customizations to the Notification Service Extension.

📘

Android 12+ behavior changes

Starting with Android 12 (API level 31), apps targeting Android 12 or newer are no longer able to create fully custom notifications. Instead, the system applies a standard template nearly identical to the behavior of Notification.DecoratedCustomViewStyle.

Disable OneSignal's Notification Open Behavior

When a notification is clicked, OneSignal will resume your app, or open your launcher Activity if your app was swiped away. If you have set a launch URL OneSignal will also open it. To customize this behavior, see URLs, Links and Deep Links.

If you want to fully disable all automatic open behaviors of your OneSignal notifications add the following to your AndroidManifest.xml:

<application ...>
   <meta-data android:name="com.onesignal.NotificationOpened.DEFAULT" android:value="DISABLE" />
</application>

Make sure you are initializing OneSignal with the Notification Opened Listener in the onCreate method in your Application class. You will need to call startActivity from this callback to take the user to your intended Activity.

Custom Notification Icons

Android notifications have small and large icons. You can also set a big picture that displays in the expanded notification. If you do not set your own icons, OneSignal will default to a bell icon.

Read more on the Android Notification Icons page.

Accent Color

The accent color changes the background color around your small icon. Set with an ARGB Hex value in either the dashboard or SDK/API. If accent color is not set, the color is set to grey.

Read more in Android Notification Icons.

App Name

The <application android:label="YOUR APP NAME"> in the AndroidManifest.xml

The accent color will also change the app name color for notifications on Android 5-11 (API levels 22-30).

📘

Android 12+ Behavior Changes to App Name Color

Starting with Android 12 (API level 31), apps targeting Android 12 or newer are no longer able to create fully custom notifications. Instead, the system applies a standard template nearly identical to the behavior of Notification.DecoratedCustomViewStyle.

If you would still like to build a custom notification layout, see Android's developer guide to create a custom notification layout and add your customizations to the Notification Service Extension.

Big Picture

A large image that shows in the expanded view of a notification. Read more in Images & Rich Media.

Notification Categories

Notification categories were introduced in Android Oreo (8.0) which gives users finer control over notifications. Use these to set common options like Importance (how notification displays on device), Sound, Vibration, LED Color, Badges, and Lockscreen display.

Read more in Android: Notification Channel Categories.

Notification Sound

A custom sound to help users identify when your app sends a notification. Read more in Customize Notification Sounds.

App Icon Badge Count Permissions

Small dots on your app icon that help prompt users to take action. Read more in Android Badges Guide.

LED Color

Certain Android hardware devices have LED notification lights built-in, allowing notifications to trigger a colored notification light on a device upon receipt. Notification colors may be set on a per-message basis in the OneSignal dashboard, or via the OneSignal SDK/API.

Notification colors are set using ARGB Hex values (e.g. a red LED notification light would be in the format FF99000). If LED Color is not set, the light uses the device's default color.

Action Buttons

Android 4.1 and newer devices support actions buttons. You can set custom buttons that will display below your notification content. Read more in Action Buttons.

Notification Grouping

Android supports grouping or combining notifications together. Read more in Notification Grouping.

Right-to-Left (RTL) Notification Support

To support notifications with right-to-left languages correctly you must add android:supportsRtl="true" to your <application> tag in your AndroidManifest.xml.

<application
             android:supportsRtl="true"
             android:icon="@drawable/ic_launcher"
             android:theme="@style/AppTheme"
             android:label="OneSignal Example"
             android:name=".OneSignalExampleApp">
     ...
  </application>

Note, make sure to test all your Activities as this effect all views in your app.

Notification Priority

Android Notifications can be assigned normal or high priority.

For Android 7.1 and lower, priority handles both "Delivery Priority" and "Display Priority"

For Android 8+, priority handles "Delivery Priority" and Android Notification Categories handles the "Display Priority"

Normal Priority: If the app is in the foreground, normal priority notifications are delivered immediately (except in Doze mode). Choose this setting for things such as new message notifications, syncing your UI, and syncing data in the background.

High Priority: These notifications are delivered immediately, though fall subject to the standby bucket policy on the device.

• Set a high priority 10 if you need it to go through any doze mode / other power saving modes. But only use priority 10 when you really need to as there is a daily limit where it might fallback to normal priority.