public class NotificationChannelBuilder

  1. Object
  2. NotificationChannelBuilder

Builds and registers a notification channel. Notification channels are an Android concept (introduced in Android O) that let the user control the behavior of groups of notifications: importance, sound, vibration, lights, lockscreen visibility and whether a badge is shown. Once a channel is created its user-controllable settings cannot be changed programmatically, so build it once at app startup.

On platforms without a channel concept (iOS, desktop) registering a channel is a no-op, but the channel id you assign to a LocalNotification is still carried so the notification behaves consistently.

Usage

new NotificationChannelBuilder("messages", "Messages")
        .description("Incoming chat messages")
        .importance(NotificationChannelBuilder.IMPORTANCE_HIGH)
        .sound("/notification_sound_ping.mp3")
        .enableVibration(true)
        .register();

See also

Fields

public static final int IMPORTANCE_NONE = 0Channel importance: a no-importance channel does not appear in the shade.
public static final int IMPORTANCE_MIN = 1Channel importance: shows nowhere, is not intrusive.
public static final int IMPORTANCE_LOW = 2Channel importance: shows in the shade and status bar but is not intrusive.
public static final int IMPORTANCE_DEFAULT = 3Channel importance: shows everywhere, makes noise but does not visually intrude.
public static final int IMPORTANCE_HIGH = 4Channel importance: makes noise and shows as a heads-up notification.
public static final int IMPORTANCE_MAX = 5Channel importance: the highest level (rarely needed).
public static final int VISIBILITY_SECRET = -1Lockscreen visibility: do not reveal any part of the notification on a secure lockscreen.
public static final int VISIBILITY_PRIVATE = 0Lockscreen visibility: show the notification but hide sensitive content on a secure lockscreen.
public static final int VISIBILITY_PUBLIC = 1Lockscreen visibility: show the notification in its entirety on the lockscreen.

Constructors

public NotificationChannelBuilder(String id, String name)Creates a channel builder.

Methods

public NotificationChannelBuilder description(String d)Sets the user-visible channel description.
public NotificationChannelBuilder importance(int imp)Sets the channel importance, one of the IMPORTANCE_ constants.
public NotificationChannelBuilder sound(String soundFile)Sets the sound played for notifications on this channel.
public NotificationChannelBuilder enableVibration(boolean b)Enables or disables vibration for this channel.
public NotificationChannelBuilder vibrationPattern(long[] pattern)Sets the vibration pattern (alternating off/on durations in milliseconds) and enables vibration.
public NotificationChannelBuilder enableLights(boolean b)Enables or disables the notification light for this channel.
public NotificationChannelBuilder lightColor(int rgb)Sets the notification light color (as an RGB integer) and enables lights.
public NotificationChannelBuilder lockscreenVisibility(int v)Sets the lockscreen visibility, one of the VISIBILITY_ constants.
public NotificationChannelBuilder group(String groupId)Assigns this channel to a channel group.
public NotificationChannelBuilder showBadge(boolean b)Controls whether notifications on this channel may show a launcher badge.
public String getId()Returns the channel id.
public String getName()Returns the user-visible channel name.
public String getDescription()Returns the channel description.
public int getImportance()Returns the channel importance.
public String getSound()Returns the channel sound file path.
public boolean isVibrationEnabled()Returns true if vibration is enabled.
public long[] getVibrationPattern()Returns the vibration pattern.
public boolean isLightsEnabled()Returns true if lights are enabled.
public int getLightColor()Returns the light color.
public int getLockscreenVisibility()Returns the lockscreen visibility.
public String getGroup()Returns the channel group id.
public boolean isShowBadge()Returns true if a launcher badge is allowed.
public void register()Registers this channel with the platform.
public static void deleteChannel(String id)Deletes a previously registered channel.
public static void createChannelGroup(String groupId, String groupName)Creates a channel group, which visually groups channels in the system settings.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone

Field details

IMPORTANCE_NONE

public static final int IMPORTANCE_NONE = 0
Channel importance: a no-importance channel does not appear in the shade.

IMPORTANCE_MIN

public static final int IMPORTANCE_MIN = 1
Channel importance: shows nowhere, is not intrusive.

IMPORTANCE_LOW

public static final int IMPORTANCE_LOW = 2
Channel importance: shows in the shade and status bar but is not intrusive.

IMPORTANCE_DEFAULT

public static final int IMPORTANCE_DEFAULT = 3
Channel importance: shows everywhere, makes noise but does not visually intrude.

IMPORTANCE_HIGH

public static final int IMPORTANCE_HIGH = 4
Channel importance: makes noise and shows as a heads-up notification.

IMPORTANCE_MAX

public static final int IMPORTANCE_MAX = 5
Channel importance: the highest level (rarely needed).

VISIBILITY_SECRET

public static final int VISIBILITY_SECRET = -1
Lockscreen visibility: do not reveal any part of the notification on a secure lockscreen.

VISIBILITY_PRIVATE

public static final int VISIBILITY_PRIVATE = 0
Lockscreen visibility: show the notification but hide sensitive content on a secure lockscreen.

VISIBILITY_PUBLIC

public static final int VISIBILITY_PUBLIC = 1
Lockscreen visibility: show the notification in its entirety on the lockscreen.

Constructor details

NotificationChannelBuilder

public NotificationChannelBuilder(String id, String name)
Creates a channel builder.

Parameters

id String
a stable channel id used when posting notifications
name String
the user-visible channel name shown in the system settings

Method details

description

public NotificationChannelBuilder description(String d)
Sets the user-visible channel description.

Parameters

d String
the description

Returns

this builder for chaining

importance

public NotificationChannelBuilder importance(int imp)
Sets the channel importance, one of the IMPORTANCE_ constants.

Parameters

imp int
the importance level

Returns

this builder for chaining

sound

public NotificationChannelBuilder sound(String soundFile)
Sets the sound played for notifications on this channel. The file name must start with the “notification_sound” prefix and be bundled with the app.

Parameters

soundFile String
the sound file path

Returns

this builder for chaining

enableVibration

public NotificationChannelBuilder enableVibration(boolean b)
Enables or disables vibration for this channel.

Parameters

b boolean
true to enable vibration

Returns

this builder for chaining

vibrationPattern

public NotificationChannelBuilder vibrationPattern(long[] pattern)
Sets the vibration pattern (alternating off/on durations in milliseconds) and enables vibration.

Parameters

pattern long[]
the vibration pattern

Returns

this builder for chaining

enableLights

public NotificationChannelBuilder enableLights(boolean b)
Enables or disables the notification light for this channel.

Parameters

b boolean
true to enable lights

Returns

this builder for chaining

lightColor

public NotificationChannelBuilder lightColor(int rgb)
Sets the notification light color (as an RGB integer) and enables lights.

Parameters

rgb int
the light color

Returns

this builder for chaining

lockscreenVisibility

public NotificationChannelBuilder lockscreenVisibility(int v)
Sets the lockscreen visibility, one of the VISIBILITY_ constants.

Parameters

v int
the lockscreen visibility

Returns

this builder for chaining

group

public NotificationChannelBuilder group(String groupId)
Assigns this channel to a channel group. The group must be created with #createChannelGroup(String, String) before or after the channel is registered.

Parameters

groupId String
the channel group id

Returns

this builder for chaining

showBadge

public NotificationChannelBuilder showBadge(boolean b)
Controls whether notifications on this channel may show a launcher badge.

Parameters

b boolean
true to allow a badge

Returns

this builder for chaining

getId

public String getId()
Returns the channel id.

Returns

the channel id

getName

public String getName()
Returns the user-visible channel name.

Returns

the channel name

getDescription

public String getDescription()
Returns the channel description.

Returns

the description, or null

getImportance

public int getImportance()
Returns the channel importance.

Returns

the importance level

getSound

public String getSound()
Returns the channel sound file path.

Returns

the sound file, or null

isVibrationEnabled

public boolean isVibrationEnabled()
Returns true if vibration is enabled.

Returns

true if vibration is enabled

getVibrationPattern

public long[] getVibrationPattern()
Returns the vibration pattern.

Returns

the vibration pattern, or null

isLightsEnabled

public boolean isLightsEnabled()
Returns true if lights are enabled.

Returns

true if lights are enabled

getLightColor

public int getLightColor()
Returns the light color.

Returns

the light color as an RGB integer

getLockscreenVisibility

public int getLockscreenVisibility()
Returns the lockscreen visibility.

Returns

the lockscreen visibility

getGroup

public String getGroup()
Returns the channel group id.

Returns

the group id, or null

isShowBadge

public boolean isShowBadge()
Returns true if a launcher badge is allowed.

Returns

true if a badge is allowed

register

public void register()
Registers this channel with the platform. On platforms without channels this is a no-op.

deleteChannel

public static void deleteChannel(String id)
Deletes a previously registered channel. On platforms without channels this is a no-op.

Parameters

id String
the channel id to delete

createChannelGroup

public static void createChannelGroup(String groupId, String groupName)
Creates a channel group, which visually groups channels in the system settings. On platforms without channels this is a no-op.

Parameters

groupId String
a stable group id
groupName String
the user-visible group name