Android > Advanced

Customizing notifications

Setting up custom push icons

Small notification icon

The small icon is displayed in the notification and in the status bar. It allows users to recognize your app when they receive a push. Before releasing a new version of your app on the Store, make sure you have set a small icon for your notifications.

Small icon samples

The small icon should be opaque white, using only the alpha channel and 24x24dp as mentioned in Google documentation. You can easily create one using the Android Assets Studio.

Here's how to set it to Batch Push:

public class YourApp extends Application
{
    @Override
    public void onCreate()
    {
        super.onCreate();

        Batch.setConfig(new Config(YOUR_BATCH_API_KEY));

        Batch.Push.setGCMSenderId("YOUR-GCM-SENDER-ID");
        Batch.Push.setSmallIconResourceId(R.drawable.push_icon);
    }
}

Important

If you use a colored small icon, Google will display it as a white square:
Small icon issue

Large notification icon

The large icon is the one that appears on the left of your notification. Here is how it looks: Large icon sample

If you don't set any custom large notification icon, Android will use the small one. Here's how to set a custom large icon to Batch Push:

public class YourApp extends Application
{
    @Override
    public void onCreate()
    {
        super.onCreate();

        Batch.setConfig(new Config(YOUR_BATCH_API_KEY));

        Batch.Push.setGCMSenderId("your_gcm_sender_id");
        Batch.Push.setSmallIconResourceId(R.drawable.push_icon);
        Batch.Push.setLargeIcon(BitmapFactory.decodeResource(getResources(),
                R.drawable.large_push_icon));
    }
}

Setting notification accent color

Google allows you to set an accent color for your push notifications. That accent color will be used to customise the color of your small icon / app name (Android 7.+) or of the circle that contains your small icon on Android 5.0 and 6.0.

Accent color

You can customize the color of the circle / name of the app, and Batch provides with an API to do it:

public class YourApp extends Application
{
    @Override
    public void onCreate()
    {
        ...

        Batch.Push.setNotificationsColor(0xFF00FF00); // You should pass an aRGB integer
    }
}

If you don't set a custom accent color, Android will use a grey accent color.

Sending silent notifications

Silent push notifications allow you wake up the app to run actions for a limited amount of time without notifying the user.

Here is the key you need to add to your payload to send silent notifications:

{"msg": null}

Please note that this will work out of the box with Batch’s default receiver. In case you are using a custom receiver, ensure you don’t display any notification when a null value is received for the “msg” parameter.

Setting notification default sound

Starting with Batch 1.8, you can now override the default sound that will be played when showing a notification.
To do so, simply provide an Uri to Batch. Accepted Uris are the same as the framework's Notification.Builder.setSound

public class YourApp extends Application
{
    @Override
    public void onCreate()
    {
        ...

        Batch.Push.setSound(RingtoneManager.getDefaultUri(RingtoneManager.TYPE_ALARM));
    }
}

Managing notification display

You can restrict notification display on Android with several parameters such as disabling sound, vibration, or simply disabling notifications for that user if you have a way to ask for opt-in.

Batch Push provides you with an enum with the interactions a notification can have via: PushNotificationType. This enum contains ALERT, SOUND, LIGHTS and VIBRATE. By default, everything is activated.

Disabling notifications

EnumSet<PushNotificationType> set = EnumSet.of(PushNotificationType.NONE); // Disable all notifications

Batch.Push.setNotificationsType(set);

You can call Batch.Push.setNotificationsType whenever you want in the runtime of your application.

Disabling sound

EnumSet<PushNotificationType> set = EnumSet.allOf(PushNotificationType.class);
        set.remove(PushNotificationType.SOUND); // Disable only sound

Batch.Push.setNotificationsType(set);

Please keep in mind that once you've set notification type within Batch, you have to set it again to change it.

Advanced notification customization

Sometimes, you might want to alter and/or enhance the way Batch builds the notification, or override other fields based on the notification payload.
Starting with Batch 1.9.2, Batch includes a notification interception system so you don't have to make your own notification from scratch.

First, you will need to extend the BatchNotificationInterceptor class. It has two methods you can override to tweak notifications:

  • getPushNotificationCompatBuilder gives you full access the the NotificationCompat.Builder. This method is called after Batch is done setting everything up in the builder you get in a parameter. You can add your own customizations to it, or return a totally different builder.
  • getPushNotificationId lets you change the Notification ID. This is handy to turn the ID into a non unique one, allowing notifications to be updated (such as a sports game score update, for example).

Then you can either use this interceptor in a Batch.Push.displayNotification() call in a custom receiver, or set it globally using Batch.Push.setNotificationInterceptor() in your Application's onCreate().

Note: Like other setup methods, it is VERY important that you set the global interceptor in the Application's onCreate() and not the Activity's.

Example interceptor implementation:

public class NotificationInterceptor extends BatchNotificationInterceptor
{
  @Nullable
  @Override
  public NotificationCompat.Builder getPushNotificationCompatBuilder(@NonNull Context context,
                                                                     @NonNull NotificationCompat.Builder defaultBuilder,
                                                                     @NonNull Bundle pushIntentExtras,
                                                                     int notificationId)
  {
    defaultBuilder.setOngoing(true);
    return defaultBuilder;
  }
}

All that is left to do, is to globally register the interceptor:

public class MyApplication extends Application
{
  @Override
  public void onCreate()
  {
    super.onCreate();

    Batch.Push.setNotificationInterceptor(new NotificationInterceptor());

    // Other Batch configuration ...
  }
}

Note: Batch sets some default values on the Notification builder that cannot be overridden later. If you run into such a case, please contact us, so we can take this into account for future SDK improvements.

Adding actions to notifications

By combining Batch Actions and BatchNotificationInterceptor, you can easily add action buttons to notifications based on your custom payload: BatchNotificationAction comes with an helper method allowing you to generate NotificationCompat.Action easily without needing to worry about PendingIntents or services.

Here's an example of BatchNotificationInterceptor implementation that adds a "Call" button for the following custom payload: {"phoneCTA": "123456789"}

public class NotificationInterceptor extends BatchNotificationInterceptor
{
    @Nullable
    @Override
    public NotificationCompat.Builder getPushNotificationCompatBuilder(@NonNull Context context,
                                                                       @NonNull NotificationCompat.Builder defaultBuilder,
                                                                       @NonNull Bundle pushIntentExtras,
                                                                       int notificationId)
    {
        final String phoneNumber = pushIntentExtras.getString("phoneCTA");
        if (phoneNumber != null) {
            try {
                JSONObject jsonArgs = new JSONObject();
                jsonArgs.put("number", phoneNumber);

                BatchNotificationAction notificationAction = new BatchNotificationAction();
                notificationAction.shouldDismissNotification = false;
                notificationAction.actionIdentifier = "CALL";
                notificationAction.label = "Call";
                notificationAction.actionArguments = jsonArgs;

                List<BatchNotificationAction> notificationActions = new ArrayList<>(1);
                notificationActions.add(notificationAction);

                List<NotificationCompat.Action> compatActions = BatchNotificationAction.getSupportActions(
                        context,
                        notificationActions,
                        BatchPushPayload.payloadFromReceiverExtras(pushIntentExtras),
                        notificationId);

                for (NotificationCompat.Action compatAction : compatActions) {
                    defaultBuilder.addAction(compatAction);
                }
            } catch (JSONException | MissingDependencyException | BatchPushPayload.ParsingException e) {
                e.printStackTrace();
            }

        }

        return defaultBuilder;
    }
}

This interceptor assumes that you've registered the CALL action to Batch earlier:


public class MyApplication extends Application
{
  @Override
  public void onCreate()
  {
    super.onCreate();  
    Batch.Push.setNotificationInterceptor(new NotificationInterceptor());
    Batch.Actions.register(new UserAction("CALL", new UserActionRunnable()
    {
      @Override
      public void performAction(@Nullable Context context,
                                @NonNull String identifier,
                                @NonNull JSONObject args,
                                @Nullable UserActionSource source)
      {
        try {
          Intent callIntent = new Intent(Intent.ACTION_DIAL);
          callIntent.setData(Uri.parse("tel:" + Uri.encode(args.getString("number"))));
          callIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
          startActivity(callIntent);
        } catch (JSONException e) {
          e.printStackTrace();
          Toast.makeText(context, "Could not execute CALL action", Toast.LENGTH_SHORT).show();
        }
      }
    }));
    // Other Batch configuration ...
  }  
}