OneSignal Push Notification Service Documentation

OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Support

Android Customizations

Customizing Android notifications with your app icons, colors, and style

For Developers

Custom Notification Icons

Read more on the Android Notification Icons page.

Notification Categories

Notification categories are a new Android O feature which gives users finer control over notifications.
Read more on the Android Notification Categories page.

Action Buttons

Android 4.1 and newer devices support actions buttons. You can specify up to 3 buttons that will display below your notification content. Read Customize Action Buttons for more.

Big Picture

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, but your main content should be in 43:24 ratio (~1.79) as some devices crop past this width. Android does not have a size limit, however see our recommended minimum, balanced, and maximum sizes below.

  • Minimum - 512x256
  • Balanced - 1024x512
  • Maximum - 2048x1024

Background Images

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 size should be 2600x256 (91.4:9) to fit all devices including landscape mode.
(Such as the Samsung Galaxy S7)
In portrait mode the user may only see 1280x256 (5:1) on some devices so do design your image accordingly.

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.

Example color.xml file. Title is set to red and the body is set to green below.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="onesignal_bgimage_notif_title_color">#FFFF0000</color>
    <color name="onesignal_bgimage_notif_body_color">#FF00FF00</color>
</resources>

The image by default will be top left aligned, you may change it to be right aligned by setting the key onesignal_bgimage_notif_image_align to right in your strings.xml.
Example:

<resources>
    <string name="onesignal_bgimage_notif_image_align">right</string>
</resources>

In additional to locally setting the image in your app, it can be with the android_background_layout field through the Create notification REST API call.

The small and large icons will be overridden by the background image. Include it as part of your image if you need it to show still.

LED Color

Certain Android hardware devices have LED notification lights built-in, allowing notifications to trigger a colored notification light on a device upon receipt. Notification colors may be set on a per-message basis in the OneSignal dashboard, or via the OneSignal SDK/API.

Notification colors are set using ARGB Hex values (e.g. a red LED notification light would be in the format #FFF93E3E). If LED Color is not set, the light uses the device's default color.

Accent Color

Accent colors only apply to apps targeting Android API level 21+ running on Android 5.0+ devices.

Accent colors are the background color around your small icon, which appears to the left of the notification content in a notification. Like LED Colors, accent colors may be set with an ARGB Hex value in either the dashboard or SDK/API. If Accent Color is not set, the color is set to grey. Read more in Android Notification Icons

Notification Stacking

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.

  • Stacking works on all our latest SDKs and on Android devices all the way back to Android 4.0.
  • Also works on Amazon devices, set the group key listed under the amazon settings as well.

App Icon Badge Counts

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.

<application ...>
   <meta-data android:name="com.onesignal.BadgeCount" android:value="DISABLE" />
</application>

You can remove the badge permissions with the following entries.

<uses-permission android:name="com.sec.android.provider.badge.permission.READ" tools:node="remove" />
<uses-permission android:name="com.sec.android.provider.badge.permission.WRITE" tools:node="remove" />
<uses-permission android:name="com.htc.launcher.permission.READ_SETTINGS" tools:node="remove" />
<uses-permission android:name="com.htc.launcher.permission.UPDATE_SHORTCUT" tools:node="remove" />
<uses-permission android:name="com.sonyericsson.home.permission.BROADCAST_BADGE" tools:node="remove" />
<uses-permission android:name="com.sonymobile.home.permission.PROVIDER_INSERT_BADGE" tools:node="remove" />
<uses-permission android:name="com.anddoes.launcher.permission.UPDATE_COUNT" tools:node="remove" />
<uses-permission android:name="com.majeur.launcher.permission.UPDATE_BADGE" tools:node="remove" />
<uses-permission android:name="com.huawei.android.launcher.permission.CHANGE_BADGE" tools:node="remove"/>
<uses-permission android:name="com.huawei.android.launcher.permission.READ_SETTINGS" tools:node="remove" />
<uses-permission android:name="com.huawei.android.launcher.permission.WRITE_SETTINGS" tools:node="remove" />
<uses-permission android:name="android.permission.READ_APP_BADGE" tools:node="remove" />
<uses-permission android:name="com.oppo.launcher.permission.READ_SETTINGS" tools:node="remove" />
<uses-permission android:name="com.oppo.launcher.permission.WRITE_SETTINGS" tools:node="remove" />

You will also need to add the the following to your manifest tag at the top of the file.
xmlns:tools="http://schemas.android.com/tools"

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools"
          package="com.onesignal.example">
          ...
</manifest>

Notification Sounds

Read more in Customize Notification Sounds

Background Data and Notification Overriding

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 setNotificationOpenedHandler 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 extends NotificationExtenderService and implement the onNotificationProcessing method.
import com.onesignal.OSNotificationPayload;
import com.onesignal.NotificationExtenderService;

public class NotificationExtenderBareBonesExample extends NotificationExtenderService {
   @Override
   protected boolean onNotificationProcessing(OSNotificationReceivedResult receivedResult) {
     	// Read properties from result.
     
      // Return true to stop the notification from displaying.
      return false;
   }
}
  1. Add the following to your AndroidManifest.xml.

Replace 'YOUR_CLASS_NAME' with the class name you used above.

<service
   android:name=".YOUR_CLASS_NAME"
   android:exported="false">
   <intent-filter>
      <action android:name="com.onesignal.NotificationExtender" />
   </intent-filter>
</service>
  1. To override or extend specific notification properties call displayNotification with OverrideSettings.
import android.support.v4.app.NotificationCompat;

import com.onesignal.OSNotificationPayload;
import com.onesignal.NotificationExtenderService;

import java.math.BigInteger;

public class NotificationExtenderExample extends NotificationExtenderService {
   @Override
   protected boolean onNotificationProcessing(OSNotificationReceivedResult receivedResult) {
      OverrideSettings overrideSettings = new OverrideSettings();
      overrideSettings.extender = new NotificationCompat.Extender() {
         @Override
         public NotificationCompat.Builder extend(NotificationCompat.Builder builder) {
            // Sets the background notification color to Green on Android 5.0+ devices.
            return builder.setColor(new BigInteger("FF00FF00", 16).intValue());
         }
      };

      OSNotificationDisplayedResult displayedResult = displayNotification(overrideSettings);
			Log.d("OneSignalExample", "Notification displayed with id: " + displayedResult.androidNotificationId);

      return true;
   }
}

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.
  • By default BigTextStyle is set so to change the body text you must override the style with the following:
    .setStyle(new NotificationCompat.BigTextStyle().bigText(message))
  • If you plan on setting a big picture make sure to check for this before setting the BigTextStyle style above.

Resume last Activity when opening a Notification

Add the following code to the top of onCreate in your launcher Activity.

private static boolean activityStarted;

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  if (   activityStarted
      && getIntent() != null
      && (getIntent().getFlags() & Intent.FLAG_ACTIVITY_REORDER_TO_FRONT) != 0) {
  	finish();
  	return;
  }
  
  activityStarted = true;
}

Additional information:
By default OneSignal calls startActivity with the following intent flags.

Intent.FLAG_ACTIVITY_REORDER_TO_FRONT | Intent.FLAG_ACTIVITY_NEW_TASK

Changing the open action of a notification

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.

<application ...>
   <meta-data android:name="com.onesignal.NotificationOpened.DEFAULT" android:value="DISABLE" />
</application>

Make sure you are initializing OneSignal with setNotificationOpenedHandler in the onCreate method in your Application class. You will need to call startActivity from this callback.

Preventing Multiple Instances of the same Activity

To prevent more than one copy of your Activity from running add android:launchMode="singleTop" to your Activity in your AndroidManifest.xml.

<activity
          android:name=".MainActivity"
          android:label="OneSignal Example"
          android:launchMode="singleTop" />

Right-to-Left (RTL) Notification Support

To support notifications with right-to-left languages correctly you must add android:supportsRtl="true" to your <application> tag in your AndroidManifest.xml.

<application
             android:supportsRtl="true"
             android:icon="@drawable/ic_launcher"
             android:theme="@style/AppTheme"
             android:label="OneSignal Example"
             android:name=".OneSignalExampleApp">
     ...
  </application>

Note, make sure to test all your Activities as this effect all views in your app.

Example Project

We have an example project with a custom sound, small icon, and large icon you can try for reference.

Android SDK API Reference

See our Android Native SDK reference for more information.

What's Next

Learn about setting up more features, or start using the OneSignal Dashboard

Features Setup
Dashboard

Android Customizations

Customizing Android notifications with your app icons, colors, and style

For Developers