whale.notifications
| Description: | Use the whale.notifications API to create rich notifications using templates and show these notifications to users in the system tray. |
|---|---|
| Availability: | Since Chrome 28. |
| Permissions: | "notifications" |
| Learn More: | Rich Notifications |
Keep Users Informed Chrome Apps Office Hours: Rich Notifications |
## Types
### TemplateType
| Enum |
|---|
|
- `"basic"`
- icon, title, message, expandedMessage, up to two buttons
- `"image"`
- icon, title, message, expandedMessage, image, up to two buttons
- `"list"`
- icon, title, message, items, up to two buttons. Users on Mac OS X only see the first item.
- `"progress"`
- icon, title, message, progress, up to two buttons
### PermissionLevel
| Enum |
|---|
|
- `"granted"`
- User has elected to show notifications from the app or extension. This is the default at install time.
- `"denied"`
- User has elected not to show notifications from the app or extension.
### NotificationOptions
| properties |
|---|
| [TemplateType](/extensions/notifications#type-TemplateType) | (optional) type |
Which type of notification to display. _Required for [notifications.create](/extensions/notifications#method-create)_ method.
|
| string | (optional) iconUrl |
A URL to the sender's avatar, app icon, or a thumbnail for image notifications.
URLs can be a data URL, a blob URL, or a URL relative to a resource within this extension's .crx file _Required for [notifications.create](/extensions/notifications#method-create)_ method.
|
| string | (optional) appIconMaskUrl |
**Deprecated** since Chrome 59. The app icon mask is not visible for Mac OS X users.
A URL to the app icon mask. URLs have the same restrictions as [iconUrl](/extensions/notifications#property-NotificationOptions-iconUrl).
The app icon mask should be in alpha channel, as only the alpha channel of the image will be considered.
|
| string | (optional) title |
Title of the notification (e.g. sender name for email). _Required for [notifications.create](/extensions/notifications#method-create)_ method.
|
| string | (optional) message |
Main notification content. _Required for [notifications.create](/extensions/notifications#method-create)_ method.
|
| string | (optional) contextMessage |
Since Chrome 31.
Alternate notification content with a lower-weight font.
|
| integer | (optional) priority |
Priority ranges from -2 to 2\. -2 is lowest priority. 2 is highest. Zero is default. On platforms that don't support a notification center (Windows, Linux & Mac), -2 and -1 result in an error as notifications with those priorities will not be shown at all.
|
| double | (optional) eventTime |
A timestamp associated with the notification, in milliseconds past the epoch (e.g. `Date.now() + n`).
|
| array of object | (optional) buttons |
Text and icons for up to two notification action buttons.
#### Properties of each object
## Methods
| string | title | |
|---|---|---|
| string | (optional) iconUrl | |
| string | title |
|---|---|
Title of one item of a list notification.
|
| string | message |
Additional details about this item.
|
### create
`whale.notifications.create(string notificationId, [NotificationOptions](/extensions/notifications#type-NotificationOptions) options, function callback)`
Creates and displays a notification.
| Parameters |
|---|
| string | (optional) notificationId |
Identifier of the notification. If not set or empty, an ID will automatically be generated. If it matches an existing notification, this method first clears that notification before proceeding with the create operation. The identifier may not be longer than 500 characters.
The `notificationId` parameter is required before Chrome 42.
|
| [NotificationOptions](/extensions/notifications#type-NotificationOptions) | options |
Contents of the notification.
|
| function | (optional) callback |
Returns the notification id (either supplied or generated) that represents the created notification.
The callback is required before Chrome 42.
If you specify the _callback_ parameter, it should be a function that looks like this:
`function(string notificationId) {...};`
| string | notificationId | |
|---|---|---|
|
### update
`whale.notifications.update(string notificationId, [NotificationOptions](/extensions/notifications#type-NotificationOptions) options, function callback)`
Updates an existing notification.
| Parameters |
|---|
| string | notificationId |
The id of the notification to be updated. This is returned by [notifications.create](/extensions/notifications#method-create) method.
|
| [NotificationOptions](/extensions/notifications#type-NotificationOptions) | options |
Contents of the notification to update to.
|
| function | (optional) callback |
Called to indicate whether a matching notification existed.
The callback is required before Chrome 42.
If you specify the _callback_ parameter, it should be a function that looks like this:
`function(boolean wasUpdated) {...};`
| boolean | wasUpdated | |
|---|---|---|
|
### clear
`whale.notifications.clear(string notificationId, function callback)`
Clears the specified notification.
| Parameters |
|---|
| string | notificationId |
The id of the notification to be cleared. This is returned by [notifications.create](/extensions/notifications#method-create) method.
|
| function | (optional) callback |
Called to indicate whether a matching notification existed.
The callback is required before Chrome 42.
If you specify the _callback_ parameter, it should be a function that looks like this:
`function(boolean wasCleared) {...};`
| boolean | wasCleared | |
|---|---|---|
|
### getAll
`whale.notifications.getAll(function callback)`
Since Chrome 29.
Retrieves all the notifications.
| Parameters |
|---|
| function | callback |
Returns the set of notification_ids currently in the system.
The _callback_ parameter should be a function that looks like this:
`function(object notifications) {...};`
| object | notifications | |
|---|---|---|
|
### getPermissionLevel
## Events
`whale.notifications.getPermissionLevel(function callback)`
Since Chrome 32.
Retrieves whether the user has enabled notifications from this app or extension.
| Parameters |
|---|
| function | callback |
Returns the current permission level.
The _callback_ parameter should be a function that looks like this:
`function( [PermissionLevel](/extensions/notifications#type-PermissionLevel) level) {...};`
| [PermissionLevel](/extensions/notifications#type-PermissionLevel) | level | |
|---|---|---|
|
### onClosed
The notification closed, either by the system or by user action.
#### addListener
`whale.notifications.onClosed.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string notificationId, boolean byUser) {...};`
| string | notificationId | |
|---|---|---|
| boolean | byUser | |
|
### onClicked
The user clicked in a non-button area of the notification.
#### addListener
`whale.notifications.onClicked.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string notificationId) {...};`
| string | notificationId | |
|---|---|---|
|
### onButtonClicked
The user pressed a button in the notification.
#### addListener
`whale.notifications.onButtonClicked.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string notificationId, integer buttonIndex) {...};`
| string | notificationId | |
|---|---|---|
| integer | buttonIndex | |
|
### onPermissionLevelChanged
Since Chrome 32.
The user changes the permission level. As of Chrome 47, only ChromeOS has UI that dispatches this event.
#### addListener
`whale.notifications.onPermissionLevelChanged.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function( [PermissionLevel](/extensions/notifications#type-PermissionLevel) level) {...};`
| [PermissionLevel](/extensions/notifications#type-PermissionLevel) | level | |
|---|---|---|
|
### onShowSettings
Since Chrome 32.
The user clicked on a link for the app's notification settings. As of Chrome 47, only ChromeOS has UI that dispatches this event.
#### addListener
`whale.notifications.onShowSettings.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function() {...};` |