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
-
Go to Settings > Messaging
-
Press Add Group to group categories by type e.g. "News Alerts", "Social Activity", "Product Updates"
-
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.
- 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. |
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. |
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
What's Next
| Android Customizations |