Android: Notification Channels

Customizing your default channel

If you want to provide custom behavior for your notifications - eg. Notification lights, vibrate patterns, custom sound effects, etc, then on devices using Android 8.0 you should do this through the NotificationChannel rather than through Sailthru Mobile's NotificationConfig class. If you're targeting versions below 8.0 (API Level 26), then you should probably provide fallback configuration using NotificationConfig. This can be done like so:

NotificationConfig config = new NotificationConfig();
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
  	NotificationChannel channel = new NotificationChannel("notifications_default", "Carnival Notifications", NotificationManager.IMPORTANCE_DEFAULT);
    // Channel config for devices where android version >= 8.0.0
  	channel.enableLights(true);
  	channel.setLightColor(Color.RED);
  	channel.enableVibration(true);
  	channel.setVibrationPattern(new long[]{100, 200, 300, 400, 500, 400, 300, 200, 400});
  	config.setDefaultNotificationChannel(channel);
}

// Fallback config for devices where android version < 8.0.0
config.setLights(Color.RED, 500, 500);
config.setVibrate(new long[]{100, 200, 300, 400, 500, 400, 300, 200, 400});

Carnival.setNotificationConfig(config);
Carnival.startEngine(getApplicationContext(), "SDK_KEY");

This means that notifications will have the same behavior on both pre- and post-Oreo devices.

Note that the nature of channels is that developers can only set presets - this is how your channel will start when your user installs the app. After that, they'll be able to change any and all of the settings that you've set above.

Using multiple channels

The addition of channels in Android Oreo means that it's easier for you to split notifications out into categories, and to alert users in specific ways for specific reasons.

For example, a news app might create channels for breaking news, political news, and weather. These can all be set up differently so that the user gets different kinds of notifications for each channel, as illustrated below

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
  NotificationChannel breaking = new NotificationChannel("breaking", "Breaking News", NotificationManager.IMPORTANCE_HIGH);
  breaking.enableLights(true);
  breaking.enableVibration(true);
  breaking.setLightColor(Color.WHITE);
  breaking.setVibrationPattern(new long[]{100, 200, 100, 200, 100, 200, 100});

  config.setDefaultNotificationChannel(breaking);

  NotificationChannel politics = new NotificationChannel("politics", "Political News", NotificationManager.IMPORTANCE_DEFAULT);
  politics.enableLights(true);
  politics.enableVibration(true);
  politics.setLightColor(Color.BLUE);
  politics.setVibrationPattern(new long[]{100, 200, 100, 200, 100});

  NotificationChannel weather = new NotificationChannel("weather", "Weather Updates", NotificationManager.IMPORTANCE_DEFAULT);
  weather.enableLights(true);
  weather.enableVibration(true);
  weather.setLightColor(Color.GREEN);
  weather.setVibrationPattern(new long[]{100, 200, 100, 150, 100});

  NotificationManager notificationManager = (NotificationManager)getApplicationContext().getSystemService(Context.NOTIFICATION_SERVICE);
  notificationManager.createNotificationChannel(breaking);
  notificationManager.createNotificationChannel(politics);
  notificationManager.createNotificationChannel(weather);
}

Note that we've set the breaking channel as the Sailthru Mobile default one on line 9. This means that any messages sent without channel IDs, or with ones that don't match those on the device being sent to, will be sent through the breaking channel.

Sending to specific channels

As mentioned above, if you send a message without a channel ID specified, it'll go through your default channel. If you'd like to send to a specific channel, however, it can be done easily through both the Sailthru Mobile UI and APIs.

In the Sailthru Mobile UI, when creating a push notification, simply click on "Add Fields", then "Custom Key/Value". The key should be set to _channel_id, and the value to the ID of the channel you wish to send to. For example, to send to the breaking channel, your push would look like this in the UI:

Using channels with using Sailthru Mobile's Notifications API is similarly straightforward:

curl -X POST -u :API_KEY -H "Content-type: application/json" -H 'Accept: application/json' https://api.carnivalmobile.com/v5/notifications -d ' {
  "notification": {
    "to":  "*",
    "payload": {
      "alert": "Man amends previous comment, says 'All dogs are good'",
      "_channel_id": "breaking" // Channel
    }
  }
}'

More information on Sailthru Mobile's Notifications API can be found here.