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 Categories

Categorizing notifications on Android to improve the user's notification experience.

What are Notification Categories?

Notification categories are an Android Oreo (8.0+) feature which gives users finer control over notifications.
When the user receives a notification with a category they can long press on it to change the category's settings. They will be presented with options to change Importance, Sound, Vibration, Badges and more or can opt out of future notifications in the category if they choose.

Google refers to these as Notification Channels in their developer documentation but to the user these are presented as Notification Categories on the device.

Example of an app's notification categories on the device

Setting up Notification Categories

  1. Go to Settings > Messaging

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

  3. Press Add Category 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.

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

Category Parameter

Detail

Name

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

Description

More details on what the category is used for.

Importance

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

Can turn off, set default or custom sounds.

Vibration

Can turn off, set default or custom vibration patters.

LED Color

Can turn off, set default or custom LED Color

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.

πŸ‘

You created your first category!

You can now use them when sending push notifications.

Changing or Deleting Categories

🚧

Changing Existing 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.

You will need to 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.

Deleting 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.

Using the Notification Category

From the Dashboard

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 on the bottom of the edit category dialog.

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

🚧

Categories vs Channels

Categories are referred to as 'Categories' for users (such as when they're using their Android device) as well as in our dashboard. However, in Google's developer documentation they may also be referred to as Channels. For the sake of consistency with Google's documentation, our REST API calls them Channels.

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.

Default Android Categories

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.

Can I use Android Categories to Play a 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.

Updated 12 days ago



Android Notification Categories


Categorizing notifications on Android to improve the user's notification experience.

Suggested Edits are limited on API Reference Pages

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