Android: Notification Channel Categories
Categorizing notifications on Android to improve the user's notification experience.
Notification categories were added in Android Oreo (8.0) which gives users finer control over notifications. When the user receives a notification with a category they can long press it or go into the Notification Settings 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.
More details in Android's Notification Channels Docs 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 Channel Categories
-
In your OneSignal Dashboard, go to Settings > Messaging > 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".
| Category Parameter | Detail |
|---|---|
| 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 | 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. |
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
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:
-
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.
-
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 these 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.
Does OneSignal Support Localization of Notification Channels?
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.
Updated over 1 year ago