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
Requires Android
You must have already set up an Android app to continue. See Android SDK Setup
-
Go to Settings > Messaging
-
Press "ADD GROUP" and give it a name.
-
Next press "ADD CATEGORY" under the newly created group providing a name as well.
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. 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!
Categories are useful when you set up a few categories and groups to give users fine-grained control over the type of notifications you send.
Changing or Deleting Categories
Changing Existing Categories
Any changes made to your category settings through the dashboard will not update for existing users. This is a designed limitation of Android as the users have final say in their settings. To test changes to existing categories you will need to clear app data under Settings or fully uninstall and reinstall your app.
Android has a limitation on being able to change category settings on devices that received a push already from that category. This is because users can change the settings manually once they receive a push from that category.
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 should 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
From and the Options > Android section contains a dropdown with categories you have configured.
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 call to the channel id of your category. This can be found on the bottom of the edit category dialog.
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.
Updated 3 months ago
What's Next
| Features Setup |
| Android Customizations |