Guides
Log InSign Up

Android notification categories

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

Suggest Edits

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 up your own Android channels, see Android's Create and manage notification channels.

Details on referencing these channels can be found below in Add the category to your push notifications.


Android device notification categories

Example of an app's notification categories on the device

Default notification categories

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

If you do not set your own Notification Category, we will default to use "Miscellaneous" category which uses:

The "Restored" category is used for notifications that our SDK recreates when the user force stops the app. The Android operating system will remove notifications from the notification center if the user or device force stops the app. Our SDK will recreate them on the next app launch so the notifications are not lost. We use the "Restored" category to prevent annoying users with sounds, vibrations and interruptions. The "Restored" category uses:

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.

Create notification channel categories

In your OneSignal Dashboard, go to Settings > Push & In-App > 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.

1750

Where to add Android categories in OneSignal.

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

Name

User-visible. Give the category a descriptive name.

Description

User-visible. Provide more details to the user on what the category is used for.

Importance

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

  • Low - No sound, no vibration and no visual interruption.
  • Medium - No sound and no vibration.
  • High - Makes sound or vibrates. Does not pop up on screen.
  • Urgent - Makes sound and pops up on screen.

Sound

Play a sound when the notification is received.

  • Off - No sound will play.
  • Default - The device's default sound will play.
  • Custom - Use a custom sound you add to the app. Set the sound name without file extension. Example: explode_sound NOT explode_sound.wav.

See Notification Sounds for more details.

Vibration

Vibrate the device when the notification is received.

  • Off - No vibration.
  • Default - Use the device's default vibration pattern.
  • Custom - Use 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

Some devices will blink the LED light in a chosen color. See LED Color for more details.

  • Off - No light.
  • Default - Use the device's default color.
  • Custom - Uses ARGB Hex format. Example: FF0000FF is full brightness and blue.

Badges

Show a badge number or notification dot on the app icon.

  • Enabled - Display the badge.
  • Disabled - Do not display the badge.

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

After you send users a push with a specific category, any changes you make to that category will not update for those 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

If you delete a category from the OneSignal dashboard, it will be removed from the user's device's App Notification Settings after a couple hours once:

  1. All notifications for your app are removed from the device's Notification Center.
  2. The app is opened again from a new session. The app is put out of focus for 60+ seconds, then opened again.

This triggers our SDK to initialize and pull down the updated Categories.

Add the category to your push notifications

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 message API to the channel ID of your category. This can be found at the top of the Channel after it has been created.

The Channel ID is found in the Android Category setup screen.

The Channel ID is found in the Android Category setup screen.

If you created your own Android Channel, use the existing_android_channel_id in the Create message API.

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.

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.

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.

Updated 2 months ago