Notification channels

Android 8.0 introduces Notification Channels. Any application targeting the API Level 26 or higher is required to add support to notification channels, or its notifications will not be displayed.

Fortunately, Batch comes with full builtin support for them: The SDK will register a default channel for your notifications, but many APIs are available to carefully configure it to send the right notification to the right channel.

The main feature of channels is that users will be presented with options to control them, rather than toggling all of the app's notifications. That way, you'll be able to reduce your opt-out rate by segmenting your notifications. Here's how the system UI looks like:

Notification Channels System UI

For each channel, users can change various settings, such as:

• Importance

• Vibration

• Sound

Once used, an application cannot change a channel's setting anymore, letting the user retain full control on them. This also means that these settings cannot be controller on a per-notification basis anymore, or from your own App's UI: Batch.Push.setNotificationsType() is affected by this, as any flag other than ALERT will be ignored on API 26+ devices.

Default settings

The default behaviour is to register a channel named "Notifications", which ID is defined by BatchNotificationChannelsManager.DEFAULT_CHANNEL_ID.

Changing the channel that Batch uses to display notifications

Currently, there are two ways of doing this:

• By overriding the default channel for every notification

Kotlin

Batch.Push.getChannelsManager().setChannelIdOverride("MY_CHANNEL")

Java

Batch.Push.getChannelsManager().setChannelIdOverride("MY_CHANNEL");

• Or by providing an interceptor: Batch will call it before displaying any notification, giving you a chance to override (or not) the channel ID according to the content.

Kotlin

Batch.Push.getChannelsManager().setChannelIdInterceptor(
    NotificationChannelIdInterceptor { payload, deductedChannelId -> 
        // custom payload: {"high_importance":"true"}
        if ("true".equals(
                payload.pushBundle.getString("high_importance"),
                ignoreCase = true
            )
        ) {
            return@NotificationChannelIdInterceptor "IMPORTANT_CHANNEL"
        }
        deductedChannelId
    })

Java

Batch.Push.getChannelsManager().setChannelIdInterceptor(new BatchNotificationChannelsManager.NotificationChannelIdInterceptor() {
	@Nullable
	@Override
	public String getChannelId(@NonNull BatchPushPayload payload, String deductedChannelId) {
		// custom payload: {"high_importance":"true"}
		if ("true".equalsIgnoreCase(payload.getPushBundle().getString("high_importance"))) {
			return "IMPORTANT_CHANNEL";
		}
		return deductedChannelId;
	}
});

These two ways to change the channel ID are not mutually exclusive: you can use both at once.

Batch will not try to register these channels. If you override the channel ID, it becomes your responsibility to manage it.

Keep the default channel ID, but change the translation

If you register your own channels, but would like to keep Batch's default fallback, you can still rename the user-facing channel name.

You can give Batch an implementation of the BatchNotificationChannelsManager.ChannelNameProvider interface, which will be called when Batch registers its channel with Android.

Kotlin

Batch.Push.getChannelsManager().setChannelNameProvider { 
    "Marketing notifications" 
}

Java

Batch.Push.getChannelsManager().setChannelNameProvider(new BatchNotificationChannelsManager.ChannelNameProvider() {
	@NonNull
	@Override
	public String getDefaultChannelName() {
		return "Marketing notifications";
	}
});

If your string is in an Android string resource, you can use a builtin provider. Batch will fetch the right translation from the resource automatically:

Kotlin

Batch.Push.getChannelsManager().setChannelName(context, R.string.default_channel_name)

Java

Batch.Push.getChannelsManager().setChannelName(context, R.string.default_channel_name);

Like other global Batch configuration methods, these should be called in your Application's onCreate. Since this user-facing string is localized, your provider might be called on locale change.

Directing the users to the system settings

Since your app can't change any channels settings, you might want to show a button redirecting them to these settings, if you detect that they disabled the notifications.

Batch simplifies that for you:

Kotlin

// Opens Batch's channels settings
// Note: that will only work if Batch showed a notification once: the default channel is not registered beforehand. You should check if that channel has been registered beforehand.
var success = BatchNotificationChannelsManager.openSystemChannelSettings(context)

// Open the system settings for a given channel ID
success = BatchNotificationChannelsManager.openSystemChannelSettings(context, "MY_CHANNEL")

Java

// Opens Batch's channels settings
// Note: that will only work if Batch showed a notification once: the default channel is not registered beforehand. You should check if that channel has been registered beforehand.
boolean success = BatchNotificationChannelsManager.openSystemChannelSettings(context);

// Open the system settings for a given channel ID
success = BatchNotificationChannelsManager.openSystemChannelSettings(context, "MY_CHANNEL");

Custom receivers

If you're using a custom implementation of the Notification Builder in your own receiver, you will have to register your own channel, and set it in your notifications.