Customizing Notifications

[block:api-header] { "type": "basic", "title": "Small Notification Icon" } [/block] By default, Our SDK automatically uses either a white bell icon or your App's launcher icon. Starting with Android 5, the OS forces the notification icon to be all white when your app targets Android API 21+. If you don't make a correct small icon, it will most likely be displayed as a bell or solid white icon in the status bar. To quickly and easily generate small icons with the correct settings, we recommend using the [Android Asset Studio](http://romannurik.github.io/AndroidAssetStudio/icons-notification.html). Use `ic_stat_onesignal_default` as the name. Download and extract the `res` folder contents to your project and send out some test notifications to make sure it is working. [block:html] { "html": " " } [/block] If you prefer to not use the Android Asset Studio please make your icon files in the following locations and sizes: ###### Android 3.0 and higher. These icons are expected to be entirely white. - `res/drawable-mdpi-v11/ic_stat_onesignal_default.png` 24x24 pixels - `res/drawable-hdpi-v11/ic_stat_onesignal_default.png` 36x36 pixels - `res/drawable-xhdpi-v11/ic_stat_onesignal_default.png` 48x48 pixels - `res/drawable-xxhdpi-v11/ic_stat_onesignal_default.png` 72x72 pixels ###### Android 2.3 devices. These icons are expected to be [grey(#828282 to #919191)](http://web.archive.org/web/20121025153046/http://developer.android.com/guide/practices/ui_guidelines/icon_design_status_bar.html#icon9). - `res/drawable-mdpi/ic_stat_onesignal_default.png` 24x24 pixels - `res/drawable-hdpi/ic_stat_onesignal_default.png` 36x36 pixels - `res/drawable-xhdpi/ic_stat_onesignal_default.png` 48x48 pixels - `res/drawable-xxhdpi/ic_stat_onesignal_default.png` 72x72 pixels [block:html] { "html": " " } [/block] [block:api-header] { "type": "basic", "title": "Large Notification Icon" } [/block] The large notification icon will show up to the left of the notification text on Android 3.0 and newer devices. If you do not set a large icon, the small icon will be used instead. If you want a default icon to be used, name it `ic_onesignal_large_icon_default` *(keeping the file extension)* and place it in the `res/drawable-xxhdpi-v11/` folder or in the root of your assets folder. You only need one icon file at 224x224 pixels as we will auto scale the image for you to prevent it from being cropped. You can also supply a URL where the icon will be displayed from. [block:html] { "html": " " } [/block] [block:api-header] { "type": "basic", "title": "Action Buttons" } [/block] Android 4.1 and newer devices support actions buttons. You can specify up to 3 buttons that will display below your notification content. The button id is added to the additionalData variable in the notification opened callback. See the SDK API documentation for more details on looking for the id. ###### Button Icons By default icons will not display on the action buttons. If you're adding buttons to your notifications we highly recommend adding icons to them. You will need to make your icons 32x32dp (24x24dp optical square) in size, this means the following pixel sizes: ``` mdpi = 24x24 pixels in a 32x32 area hdpi = 36x36 pixels in a 48x48 area xhdpi = 48x48 pixels in a 64x64 area xxhdpi = 72x72 pixels in a 96x96 area ``` *See the image 'Big Picture' sample below to see what actions buttons look like on a notification.* [block:api-header] { "type": "basic", "title": "Big Picture" } [/block] Android 4.1 and newer devices support a big picture that will show below your notification text when it is expanded. It can be located in your drawable folders, your assets folder in your app, or it can be loaded remotely from a server with a URL. The image should be a 2:1 aspect ratio otherwise Android will crop your image. Android not have a size limit however see our recommended minimum, balanced, and maximum sizes below. * Minimum - 400x200 * Balanced - 800x400 * Maximum - 1440x720 [block:image] { "images": [ { "image": [ "https://files.readme.io/bL7zcy7gScW42PDyFdhf_AndroidActionButtonsImageLinks-1.png", "AndroidActionButtonsImageLinks-1.png", "800", "292", "#438ed9", "" ] } ] } [/block] [block:html] { "html": " " } [/block] [block:api-header] { "type": "basic", "title": "Background Image" } [/block] Using our latest SDK you can add a background image to all your notifications by adding a image file named `onesignal_bgimage_default_image` to your `res/drawable-xxxhdpi` folder. The recommend size is 1582x256. Use `onesignal_bgimage_notif_title_color` and `onesignal_bgimage_notif_body_color` in your `values/colors.xml` to set text colors to match your image. [block:image] { "images": [ { "image": [ "https://files.readme.io/ge1mfexQ0y8yCHSn5sag_CustomAndroid_Images_Blog.gif", "CustomAndroid_Images_Blog.gif", 600, 1067, "#323232", "" ] } ] } [/block] Example `color.xml` file. Title is set to red and the body is set to green below. [block:code] { "codes": [ { "code": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<resources>\n <color name=\"onesignal_bgimage_notif_title_color\">#FFFF0000</color>\n <color name=\"onesignal_bgimage_notif_body_color\">#FF00FF00</color>\n</resources>", "language": "xml" } ] } [/block] NOTE: The app icon will be overridden by the background image. Include it as part of your image if you need it to show still. [block:api-header] { "type": "basic", "title": "Notification Stacking" } [/block] Simply enter any value in the “Group Key” field under Options>Android on the New Message page on the dashboard. This is the `android_group` on the REST API. Notifications with the same group key will automatically stack on the device. [block:image] { "images": [ { "image": [ "https://files.readme.io/GnEw4PmmSVWWfgX5Uc3W_stacked_notification.png", "stacked_notification.png", "900", "460", "#886865", "" ] } ] } [/block] - *Stacking works on all our latest SDKs and on Android devices all the way back to Android 2.3.* - If a group is set on a notification the changes made with `NotificationCompat.Builder` in the `NotificationExtenderService` will be ignored. This restriction fixed in a future SDK version. - *Also works on Amazon devices, set the group key listed under the amazon settings as well.* [block:api-header] { "type": "basic", "title": "App Icon Badge counts" } [/block] The OneSignal SDK automatically sets the badge count on your app to the number of notifications that are currently in the notification shade. If you want to disable this you can add the following to your `AndroidManifest.xml`. [block:code] { "codes": [ { "code": "<application ...>\n <meta-data android:name=\"com.onesignal.BadgeCount\" android:value=\"DISABLE\" />\n</application>", "language": "xml" } ] } [/block] You can remove the badge permissions with the following entries. [block:code] { "codes": [ { "code": "<uses-permission android:name=\"com.sec.android.provider.badge.permission.READ\" tools:node=\"remove\" />\n<uses-permission android:name=\"com.sec.android.provider.badge.permission.WRITE\" tools:node=\"remove\" />\n<uses-permission android:name=\"com.htc.launcher.permission.READ_SETTINGS\" tools:node=\"remove\" />\n<uses-permission android:name=\"com.htc.launcher.permission.UPDATE_SHORTCUT\" tools:node=\"remove\" />\n<uses-permission android:name=\"com.sonyericsson.home.permission.BROADCAST_BADGE\" tools:node=\"remove\" />\n<uses-permission android:name=\"com.sonymobile.home.permission.PROVIDER_INSERT_BADGE\" tools:node=\"remove\" />\n<uses-permission android:name=\"com.anddoes.launcher.permission.UPDATE_COUNT\" tools:node=\"remove\" />\n<uses-permission android:name=\"com.majeur.launcher.permission.UPDATE_BADGE\" tools:node=\"remove\" />\n<uses-permission android:name=\"com.huawei.android.launcher.permission.CHANGE_BADGE\" tools:node=\"remove\"/>\n<uses-permission android:name=\"com.huawei.android.launcher.permission.READ_SETTINGS\" tools:node=\"remove\" />\n<uses-permission android:name=\"com.huawei.android.launcher.permission.WRITE_SETTINGS\" tools:node=\"remove\" />", "language": "xml" } ] } [/block] [block:api-header] { "type": "basic", "title": "Notification Sounds" } [/block] By default OneSignal automatically plays the default system notification sound. If you would like a custom one to always play instead, place a sound file in `res/raw/` and name it onesignal_default_sound *(keeping the file extension)*. You can use .wav, .mp3. or .ogg. If you would like to change the notification sound per notification you can add any other sound files in `res/raw` and include it's resource name (omit the file extension) in the sound field when sending the notification. If you're having issues with the sound not playing, make sure that it is getting built into your APK by extracting it and make sure it is located in `res/raw/`. [block:html] { "html": " " } [/block] [block:api-header] { "type": "basic", "title": "Background Data and Notification Overriding" } [/block] OneSignal supports sending additional data along with a notification as key value pairs. You can read this additional data when a notification is opened by adding a [NotificationOpenedHandler](android-sdk-api#NotificationOpenedHandler) instead. However if you want to one of the following continue with the instructions below. * Receive data in the background with or without displaying a notification. * Override specific notification settings depending on client side app logic such as custom accent color, vibration pattern, or other any other `NotificationCompat` options available. **1.** Create a class that extents `NotificationExtenderService` and implement the `onNotificationProcessing` method. [block:code] { "codes": [ { "code": "import com.onesignal.OSNotificationPayload;\nimport com.onesignal.NotificationExtenderService;\n\npublic class NotificationExtenderBareBonesExample extends NotificationExtenderService {\n @Override\n protected boolean onNotificationProcessing(OSNotificationReceivedResult receivedResult) {\n \t// Read properties from result.\n \n // Return true to stop the notification from displaying.\n return false;\n }\n}", "language": "java" } ] } [/block] **2.** Add the following to your `AndroidManifest.xml`. *Replace 'YOUR_CLASS_NAME' with the class name you used above.* [block:code] { "codes": [ { "code": "<service\n android:name=\".YOUR_CLASS_NAME\"\n android:exported=\"false\">\n <intent-filter>\n <action android:name=\"com.onesignal.NotificationExtender\" />\n </intent-filter>\n</service>", "language": "xml" } ] } [/block] **3.** To override or extend specific notification properties call `displayNotification` with `OverrideSettings`. [block:code] { "codes": [ { "code": "import android.support.v4.app.NotificationCompat;\n\nimport com.onesignal.OSNotificationPayload;\nimport com.onesignal.NotificationExtenderService;\n\nimport java.math.BigInteger;\n\npublic class NotificationExtenderExample extends NotificationExtenderService {\n @Override\n protected boolean onNotificationProcessing(OSNotificationReceivedResult receivedResult) {\n OverrideSettings overrideSettings = new OverrideSettings();\n overrideSettings.extender = new NotificationCompat.Extender() {\n @Override\n public NotificationCompat.Builder extend(NotificationCompat.Builder builder) {\n // Sets the background notification color to Green on Android 5.0+ devices.\n return builder.setColor(new BigInteger(\"FF00FF00\", 16).intValue());\n }\n };\n\n OSNotificationDisplayedResult displayedResult = displayNotification(overrideSettings);\n\t\t\tLog.d(\"OneSignalExample\", \"Notification displayed with id: \" + displayedResult.androidNotificationId);\n\n return true;\n }\n}", "language": "java" } ] } [/block] **Additional Notes** `NotificationExtenderService` is an Android `IntentService` so please do all your work synchronously. A wake lock is obtained so the device will not sleep while you're processing the payload. [block:api-header] { "type": "basic", "title": "Resume last Activity when opening a Notification" } [/block] Add the following code to the top of `onCreate` in your launcher `Activity`. [block:code] { "codes": [ { "code": "private static boolean activityStarted;\n\n@Override\nprotected void onCreate(Bundle savedInstanceState) {\n super.onCreate(savedInstanceState);\n\n if ( activityStarted\n && getIntent() != null\n && (getIntent().getFlags() & Intent.FLAG_ACTIVITY_REORDER_TO_FRONT) != 0) {\n \tfinish();\n \treturn;\n }\n \n activityStarted = true;\n}", "language": "java" } ] } [/block] **Additional information:** By default OneSignal calls `startActivity` with the following intent flags. ``` Intent.FLAG_ACTIVITY_REORDER_TO_FRONT | Intent.FLAG_ACTIVITY_NEW_TASK ``` [block:api-header] { "type": "basic", "title": "Changing the open action of a notification" } [/block] By default OneSignal will open or resume your launcher Activity when a notification is tapped on. You can disable this behavior by adding the meta-data tag `com.onesignal.NotificationOpened.DEFAULT` set to `DISABLE` inside your application tag in your `AndroidManifest.xml`. [block:code] { "codes": [ { "code": "<application ...>\n <meta-data android:name=\"com.onesignal.NotificationOpened.DEFAULT\" android:value=\"DISABLE\" />\n</application>", "language": "xml" } ] } [/block] Make sure you are initializing `OneSignal` with [setNotificationOpenedHandler](android-sdk-api#setNotificationOpenedHandler) in the `onCreate` method in your `Application` class. You will need to call `startActivity` from this callback. [block:api-header] { "type": "basic", "title": "Example Project" } [/block] We have an example project with a custom sound, small icon, large icon, and a background data BroadcastReceiver [you can look at for reference.](https://github.com/one-signal/OneSignal-Android-SDK/tree/master/Examples) [block:api-header] { "type": "basic", "title": "Android SDK API Reference" } [/block] See our [Android SDK API Reference](https://documentation.onesignal.com/docs/android-sdk-api) for more customizations.

OneSignal Push Notification Service Documentation

Introduction

iOS

Android

Website Push

Amazon

Windows Phone

Chrome Apps/Extensions

Mac OS X

Corona SDK

Unity SDK

Marmalade SDK

Adobe Air

PhoneGap

Cordova

Ionic

Intel XDK

Xamarin SDK

React Native

Cocos2d-x

Server REST API

Troubleshooting

Miscellaneous