Notification categories (aka notification channels) were added in Android Oreo (8.0) which gives users finer control over their notification experience with your app. You setup the categories and when users receive notifications, they can long press it or go into the Notification Settings to customize how they want to receive it. Options include: badges, sound, how they are displayed and received, and more!

We have provided a simple solution to set these up directly in your OneSignal dashboard (details below), but you can also use your own categories programmatically in your app if desired.

🔨

Developers: Android notification channel docs

Optional: If you want to programmatically set these up in your app, see Android's Notification Channels Docs.

Setting up notification channel categories

In your OneSignal Dashboard, go to Settings > Push > Android Notification Channels

Press Add Group to group categories by type e.g. "News Alerts", "Social Activity", "Product Updates"

Press Add Channel under the newly created group.

These names will be visible to the user when they view the notification settings for your app on the device.

Enter the category name, description, and any defaults the device will use for notifications sent with this category. When finished, click "Create Category".

Name

What you call the category and describes what it is used for. User-visible.

Description

More details on what the category is used for. User-visible.

Importance

How interruptive the notification will be. Can be changed by user.

URGENT - Makes sound and pops up on screen.
HIGH - Makes sound or vibrates. Does not pop up on screen.
MEDIUM - No sound and no vibration.
LOW - No sound, no vibration and no visual interruption

Sound

Set the sound to be turned off, set as device default or use a custom sound you set within the app. See Notification Sounds for more details.

Set the sound name without file extension. Example: explode_sound NOT explode_sound.wav.

Vibration

Set the vibration to be turned off, phone's default settings, or a custom vibration pattern.

First value is the time in milliseconds vibration will be off, followed by the time it will be on, followed by the time off again, etc.

Example: 0, 300, 500, 300 means pause for 0ms, vibrate for 300ms, then pause for 500ms, then vibrate for 300ms again.

LED Color

Can turn off, set default or custom LED Color.

This is the device’s LED that shows when a notification is received. Note: Only some Android devices have color LEDs.

Uses ARGB Hex format. Example: FF0000FF is full brightness and blue.

Badges

Can be enabled or disabled. If enabled it will increment based on how many notifications for your app are still in the device's Notification Center for your app. See Badges for more details.

Lockscreen

PUBLIC - Shows notification contents on lock screen.
PRIVATE - Shows a notification was received for your app, but not the contents of the push.
SECRET - No notification message on the lock screen.

👍

Category created!

You can now add the notification category to your push notifications.

Update categories

Any changes made to your category settings will not update for existing users.

This is a designed limitation of Android as your users have the final say in their settings.

If you want to update your categories, you should create a new category or test your current category by clearing app data under Settings or fully uninstall and reinstall your app.

You can however update the Category and Group name. Once the updated Category and/or Group is set and notification is received, it will be reflected in the App Notification Settings.

Delete categories

Categories will be deleted once the user clears App Data inside the Settings > Internal Shared Storage > Your App > Click Clear Cache and Clear Storage.

If you delete a category from the OneSignal dashboard, it will be removed from the device's App Notification Settings once all notifications for your app are removed from the Notification Center and the app is opened again triggering the OneSignal SDK to initialize and pull down the updated Categories.

Add the notification category

Created categories will be available under the Android Platform Settings in the "Category" field.

After selecting a category, the Sound, Lockscreen Visibility, and LED Color options will hide as these values will now be used from the category options you have set previously.

From the REST API

Set android_channel_id on the create notification REST API to the channel id of your category. This can be found at the top of the Channel after it has been created.

If you created your own Android Channel, use the existing_android_channel_id in the create notification REST API.

Notification priority

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

Android Notifications can be assigned normal or high 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.

FAQ

Why are my Android categories not working?

There are a couple reasons why an android category is not working:

1. The OneSignal init call is not in the right place. For instance, on our Android Native SDK, it should be in the Applications class as outlined in our docs and not in an Activity Class.

2. If you sent the device a notification with this channel id, then updated the settings of the channel id and sent the device again, the new settings will not get registered, you will need to create a new channel id to make changes. This is an android limitation.

What are the default Android categories?

Google Android

OneSignal creates 2 notification categories by default called "Restored" and "Miscellaneous".

The "Restored" category uses the Lowest Importance and is used for notifications that were not interacted with (not dismissed or opened), but app was force quit (which removes all the notifications) and then reopened (restores the notifications).

The "Miscellaneous" category uses the Highest Importance and is used by default when no Notification Category is set.

If you alway send a push with a Category, then the "Miscellaneous" category will never be on the device. "Restored" will always show due to notifications that get removed when force quitting the app and re-opening "restores" those notifications.

Huawei Android

OneSignal does not set a default for Huawei. If you do not include a Notification Category, then it defaults to "High" importance.

Can I use Android Categories to play sound when in Do Not Disturb Mode?

OneSignal does not add the setBypassDnd property on our Notification Channels. If you would like to play a sound while the app is in Do Not Disturb Mode, you would create your own Notification Channel and set this property. See Android's Guide on NotificationChannel and setBypassDnd.

Does OneSignal support localization of notification categories?

OneSignal does not support multiple languages of the channel name or description. You can set a single language of your choosing. To support localization, you can create your own Android Channels and reference them in your Create notification API requests with the existing_android_channel_id property.