diff --git a/en/application-dev/notification/Readme-EN.md b/en/application-dev/notification/Readme-EN.md index dccfc8dbc4c59611db4aa53ff8a5a295cbba4d46..bf85581053f30d6aa56e0218c51339ef6ee3f268 100644 --- a/en/application-dev/notification/Readme-EN.md +++ b/en/application-dev/notification/Readme-EN.md @@ -1,9 +1,10 @@ -# Common Event and Notification +# Notification + +- [Notification Overview](notification-overview.md) +- [Notification Subscription (Open Only to System Applications)](notification-subscription.md) +- [Enabling Notification](notification-enable.md) +- Publishing a Notification + - [Publishing a Basic Notification](text-notification.md) + - [Publishing a Progress Notification](progress-bar-notification.md) + - [Adding a WantAgent Object to a Notification](notification-with-wantagent.md) -- [Common Event and Notification Overview](notification-brief.md) -- [Common Event Development](common-event.md) -- [Notification Development](notification-guidelines.md) -- Agent-Powered Scheduled Reminder - - [Agent-Powered Scheduled Reminder Overview](background-agent-scheduled-reminder-overview.md) - - [Agent-Powered Scheduled Reminder Development](background-agent-scheduled-reminder-guide.md) -- [Debugging Assistant Usage](assistant-guidelines.md) diff --git a/en/application-dev/notification/assistant-guidelines.md b/en/application-dev/notification/assistant-guidelines.md deleted file mode 100644 index 5d83cf443c0f629fcb471a6c12ccd3069ac2e593..0000000000000000000000000000000000000000 --- a/en/application-dev/notification/assistant-guidelines.md +++ /dev/null @@ -1,134 +0,0 @@ -# Debugging Assistant Usage - -The common event and notification module provides debugging tools to facilitate your application development. With these tools, you can view common event and notification information, publish common events, and more. These tools have been integrated with the system. You can run related commands directly in the shell. - -## cem Debugging Assistant - -### publish - -* Function - - Publishes a common event. - -* Usage - - `cem publish []` - - The table below describes the available options. - - | Option | Description | - | ------------ | ------------------------------------------ | - | -e/--event | Indicates the name of the common event to publish. Mandatory. | - | -s/--sticky | Indicates that the common event to publish is sticky. Optional. By default, non-sticky events are published. | - | -o/--ordered | Indicates that the common event to publish is ordered. Optional. By default, non-ordered events are published. | - | -c/--code | Indicates the result code of the common event. Optional. | - | -d/--data | Indicates the data carried in the common event. Optional. | - | -h/--help | Indicates the help Information | - -* Example - - `cem publish --event "testevent"` - - Publish a common event named **testevent**. - - ![cem-publish-event](figures/cem-publish-event.png) - - - - `cem publish -e "testevent" -s -o -c 100 -d "this is data" ` - - Publish a sticky, ordered common event named **testevent**. The result code of the event is **100** and the data carried is **this is data**. - - ![cem-publish-all](figures/cem-publish-all.png) - -### dump - -* Function - - Displays information about common events. - -* Usage - - `cem dump []` - - The table below describes the available options. - - | Option | Description | - | ---------- | -------------------------------------------- | - | -a/--all | Displays information about all common events that have been sent since system startup. | - | -e/--event | Displays information about a specific event. | - | -h/--help | Displays the help information. | - -* Example - -​ `cem dump -e "testevent"` - -​ Display information about the common event testevent. - -​ ![cem-dump-e](figures/cem-dump-e.png) - -### help - -* Function - - Displays the help information. - -* Usage - - `cem help` - -* Example - - ![cem-help](figures/cem-help.png) - - - -## anm Debugging Assistant - -### dump - -* Function - - Displays information about notifications. - -* Usage - - `anm dump []` - - The table below describes the available options. - - | Option | Description | - | ---------------- | ---------------------------------------- | - | -A/--active | Displays information about all active notifications. | - | -R/--recent | Displays information about the recent notifications. | - | -D/--distributed | Displays information about distributed notifications from other devices. | - | --setRecentCount | Indicates the number of the cached recent notifications to be displayed. Optional. | - | -h/--help | Displays the help information. | - -* Example - - `anm dump -A` - - Display information about all active notifications. - - ![anm-dump-A](figures/anm-dump-A.png) - - - - `anm dump --setRecentCount 10` - - Set the number of the cached recent notifications to be displayed to **10**. - -### help - -* Function - - Displays the help information. - -* Usage - - `anm help` - -* Example - - ![anm-help](figures/anm-help.png) diff --git a/en/application-dev/notification/common-event.md b/en/application-dev/notification/common-event.md deleted file mode 100644 index dfb611ea572b80486756faaa4b004513cd6858a7..0000000000000000000000000000000000000000 --- a/en/application-dev/notification/common-event.md +++ /dev/null @@ -1,172 +0,0 @@ -# Common Event Development -## Introduction -OpenHarmony provides a Common Event Service (CES) for applications to subscribe to, publish, and unsubscribe from common events. - -Common events are classified into system common events and custom common events. - -+ System common events: The system sends an event based on system policies to the apps that have subscribed to this event when it occurs. This type of event is typically system events published by key system services, such as HAP installation, update, and uninstallation. - -+ Custom common event: customized by applications to implement cross-application event communication. - -Each application can subscribe to common events as required. After your application subscribes to a common event, the system sends it to your application every time the event is published. Such an event may be published by the system, other applications, or your own application. - -## Common Event Subscription Development - -### When to Use -You can create a subscriber object to subscribe to a common event to obtain the parameters passed in the event. Certain system common events require specific permissions to subscribe to. For details, see [Required Permissions](../reference/apis/js-apis-commonEvent.md#support). - -### Available APIs -| API | Description| -| ---------------------------------------------------------------------------------------------- | ----------- | -| createSubscriber(subscribeInfo: CommonEventSubscribeInfo, callback: AsyncCallback) | Creates a subscriber. This API uses a callback to return the result.| -| createSubscriber(subscribeInfo: CommonEventSubscribeInfo) | Creates a subscriber. This API uses a promise to return the result. | -| subscribe(subscriber: CommonEventSubscriber, callback: AsyncCallback) | Subscribes to common events.| - -### How to Develop -1. Import the **commonEvent** module. - -```js -import commonEvent from '@ohos.commonEvent'; -``` - -2. Create a **subscribeInfo** object. For details about the data types and parameters of the object, see [CommonEventSubscribeInfo](../reference/apis/js-apis-commonEvent.md#commoneventsubscribeinfo). - -```js -// Used to save the created subscriber object for subsequent subscription and unsubscription. -private subscriber = null - -// Subscriber information -var subscribeInfo = { - events: ["event"], -} -``` - -3. Create a subscriber object and save the returned object for subsequent operations such as subscription and unsubscription. - -```js -// Callback for subscriber creation. -commonEvent.createSubscriber(subscribeInfo, (err, subscriber) => { - if (err.code) { - console.error("[CommonEvent]CreateSubscriberCallBack err=" + JSON.stringify(err)) - } else { - console.log("[CommonEvent]CreateSubscriber") - this.subscriber = subscriber - this.result = "Create subscriber succeed" - } -}) -``` - -4. Create a subscription callback, which is triggered when an event is received. The data returned by the subscription callback contains information such as the common event name and data carried by the publisher. For details about the data types and parameters of the common event data, see [CommonEventData](../reference/apis/js-apis-commonEvent.md#commoneventdata). - -```js -// Callback for common event subscription. -if (this.subscriber != null) { - commonEvent.subscribe(this.subscriber, (err, data) => { - if (err.code) { - console.error("[CommonEvent]SubscribeCallBack err=" + JSON.stringify(err)) - } else { - console.log("[CommonEvent]SubscribeCallBack data=" + JSON.stringify(data)) - this.result = "receive, event = " + data.event + ", data = " + data.data + ", code = " + data.code - } - }) - this.result = "Subscribe succeed" -} else { - prompt.showToast({ message: "Need create subscriber" }) -} -``` - -## Common Event Publishing Development - -### When to Use -You can use the **publish** APIs to publish a custom common event, which can carry data for subscribers to parse and process. - -### Available APIs -| API | Description| -| ---------------------------------- | ------ | -| publish(event: string, callback: AsyncCallback) | Publishes a common event.| -| publish(event: string, options: CommonEventPublishData, callback: AsyncCallback) | Publishes a common event with given attributes.| - -### How to Develop -#### Development for Publishing a Common Event -1. Import the **commonEvent** module. - -```js -import commonEvent from '@ohos.commonEvent'; -``` - -2. Pass in the common event name and callback, and publish the event. - -```js -// Publish a common event. -commonEvent.publish("event", (err) => { - if (err.code) { - console.error("[CommonEvent]PublishCallBack err=" + JSON.stringify(err)) - } else { - console.info("[CommonEvent]Publish1") - } -}) -``` - -#### Development for Publishing a Common Event with Given Attributes -1. Import the **commonEvent** module. - -```js -import commonEvent from '@ohos.commonEvent' -``` - -2. Define attributes of the common event to publish. For details about the data types and parameters in the data to publish, see [CommonEventPublishData](../reference/apis/js-apis-commonEvent.md#commoneventpublishdata). - -```js -// Attributes of a common event. -var options = { - code: 1, // Result code of the common event - data: "initial data";// Result data of the common event -} -``` - -3. Pass in the common event name, attributes of the common event, and callback, and publish the event. - -```js -// Publish a common event. -commonEvent.publish("event", options, (err) => { - if (err.code) { - console.error("[CommonEvent]PublishCallBack err=" + JSON.stringify(err)) - } else { - console.info("[CommonEvent]Publish2") - } -}) -``` - -## Common Event Unsubscription Development - -### When to Use -You can use the **unsubscribe** API to unsubscribe from a common event. - -### Available APIs -| API | Description| -| ---------------------------------- | ------ | -| unsubscribe(subscriber: CommonEventSubscriber, callback?: AsyncCallback) | Unsubscribes from a common event.| - -### How to Develop -1. Import the **commonEvent** module. - -```js -import commonEvent from '@ohos.commonEvent'; -``` - -2. Subscribe to a common event by following instructions in [Common Event Subscription Development](#common-event-subscription-development). -3. Invoke the **unsubscribe** API in **CommonEvent** to unsubscribe from the common event. - -```js -if (this.subscriber != null) { - commonEvent.unsubscribe(this.subscriber, (err) => { - if (err.code) { - console.error("[CommonEvent]UnsubscribeCallBack err=" + JSON.stringify(err)) - } else { - console.log("[CommonEvent]Unsubscribe") - this.subscriber = null - this.result = "Unsubscribe succeed" - } - }) -} -``` diff --git a/en/application-dev/notification/figures/anm-dump-A.png b/en/application-dev/notification/figures/anm-dump-A.png deleted file mode 100644 index 368e6f2d810976486e786a4c8f0603a87ad48540..0000000000000000000000000000000000000000 Binary files a/en/application-dev/notification/figures/anm-dump-A.png and /dev/null differ diff --git a/en/application-dev/notification/figures/anm-help.png b/en/application-dev/notification/figures/anm-help.png deleted file mode 100644 index d80ac8e76a70c2be383f0a05a12e3e707dcf242b..0000000000000000000000000000000000000000 Binary files a/en/application-dev/notification/figures/anm-help.png and /dev/null differ diff --git a/en/application-dev/notification/figures/ans.png b/en/application-dev/notification/figures/ans.png deleted file mode 100644 index 8be552d2acedbef962326365fb2d19ded3838c14..0000000000000000000000000000000000000000 Binary files a/en/application-dev/notification/figures/ans.png and /dev/null differ diff --git a/en/application-dev/notification/figures/cem-dump-e.png b/en/application-dev/notification/figures/cem-dump-e.png deleted file mode 100644 index c2422ba0e51011174c333985ad7647f170e0f126..0000000000000000000000000000000000000000 Binary files a/en/application-dev/notification/figures/cem-dump-e.png and /dev/null differ diff --git a/en/application-dev/notification/figures/cem-help.png b/en/application-dev/notification/figures/cem-help.png deleted file mode 100644 index 8ca4bc0605f9c1f75a8cb45f8ab77c9c5d6f04e4..0000000000000000000000000000000000000000 Binary files a/en/application-dev/notification/figures/cem-help.png and /dev/null differ diff --git a/en/application-dev/notification/figures/cem-publish-all.png b/en/application-dev/notification/figures/cem-publish-all.png deleted file mode 100644 index 99526e1f7245d101914354e2a89d5e97d710c27f..0000000000000000000000000000000000000000 Binary files a/en/application-dev/notification/figures/cem-publish-all.png and /dev/null differ diff --git a/en/application-dev/notification/figures/cem-publish-event.png b/en/application-dev/notification/figures/cem-publish-event.png deleted file mode 100644 index f0ca7e73093f1be72c743bd7c08467f11e2a0e05..0000000000000000000000000000000000000000 Binary files a/en/application-dev/notification/figures/cem-publish-event.png and /dev/null differ diff --git a/en/application-dev/notification/figures/ces.png b/en/application-dev/notification/figures/ces.png deleted file mode 100644 index b1aa5438a19ac79899e0f45791f3e1a79e4242dc..0000000000000000000000000000000000000000 Binary files a/en/application-dev/notification/figures/ces.png and /dev/null differ diff --git a/en/application-dev/notification/figures/en-us_image_0000001416585590.png b/en/application-dev/notification/figures/en-us_image_0000001416585590.png new file mode 100644 index 0000000000000000000000000000000000000000..9da6812580fd6c7d785391c652104ef0698ce2bc Binary files /dev/null and b/en/application-dev/notification/figures/en-us_image_0000001416585590.png differ diff --git a/en/application-dev/notification/figures/en-us_image_0000001416745530.png b/en/application-dev/notification/figures/en-us_image_0000001416745530.png new file mode 100644 index 0000000000000000000000000000000000000000..7a6fd0d9304abef2eb240a3c78a93b73bb9237af Binary files /dev/null and b/en/application-dev/notification/figures/en-us_image_0000001416745530.png differ diff --git a/en/application-dev/notification/figures/en-us_image_0000001417062434.png b/en/application-dev/notification/figures/en-us_image_0000001417062434.png new file mode 100644 index 0000000000000000000000000000000000000000..07db3298f0db1c3357624b44d271dc1e6f97ea9e Binary files /dev/null and b/en/application-dev/notification/figures/en-us_image_0000001417062434.png differ diff --git a/en/application-dev/notification/figures/en-us_image_0000001417062446.png b/en/application-dev/notification/figures/en-us_image_0000001417062446.png new file mode 100644 index 0000000000000000000000000000000000000000..c197fd6293f41890b2bfcf17a28a1477e8aa6d96 Binary files /dev/null and b/en/application-dev/notification/figures/en-us_image_0000001417062446.png differ diff --git a/en/application-dev/notification/figures/en-us_image_0000001466462297.png b/en/application-dev/notification/figures/en-us_image_0000001466462297.png new file mode 100644 index 0000000000000000000000000000000000000000..a07d9e818677e9364ad3239e61ce198471b68603 Binary files /dev/null and b/en/application-dev/notification/figures/en-us_image_0000001466462297.png differ diff --git a/en/application-dev/notification/figures/en-us_image_0000001466462305.png b/en/application-dev/notification/figures/en-us_image_0000001466462305.png new file mode 100644 index 0000000000000000000000000000000000000000..740f4b79a9ee234008cad6cf3616a8f213569476 Binary files /dev/null and b/en/application-dev/notification/figures/en-us_image_0000001466462305.png differ diff --git a/en/application-dev/notification/figures/en-us_image_0000001466582017.png b/en/application-dev/notification/figures/en-us_image_0000001466582017.png new file mode 100644 index 0000000000000000000000000000000000000000..1652d9111be2a27863fe2322c4feb577bab22ae9 Binary files /dev/null and b/en/application-dev/notification/figures/en-us_image_0000001466582017.png differ diff --git a/en/application-dev/notification/figures/en-us_image_0000001466582045.png b/en/application-dev/notification/figures/en-us_image_0000001466582045.png new file mode 100644 index 0000000000000000000000000000000000000000..4040452a87bc69ae8fa0eb9b55ca77ac32bdb2d8 Binary files /dev/null and b/en/application-dev/notification/figures/en-us_image_0000001466582045.png differ diff --git a/en/application-dev/notification/figures/en-us_image_0000001466782025.png b/en/application-dev/notification/figures/en-us_image_0000001466782025.png new file mode 100644 index 0000000000000000000000000000000000000000..d8e45c1746ab419a8056f9493c8796cfb734d2d0 Binary files /dev/null and b/en/application-dev/notification/figures/en-us_image_0000001466782025.png differ diff --git a/en/application-dev/notification/figures/en-us_image_0000001466782033.png b/en/application-dev/notification/figures/en-us_image_0000001466782033.png new file mode 100644 index 0000000000000000000000000000000000000000..218e5fcef6d163113c9037028215297ef626fcfa Binary files /dev/null and b/en/application-dev/notification/figures/en-us_image_0000001466782033.png differ diff --git a/en/application-dev/notification/figures/notification-with-wantagent.png b/en/application-dev/notification/figures/notification-with-wantagent.png new file mode 100644 index 0000000000000000000000000000000000000000..234ef895c918404598cf7640f9d072de2bb2d0d0 Binary files /dev/null and b/en/application-dev/notification/figures/notification-with-wantagent.png differ diff --git a/en/application-dev/notification/figures/notification.png b/en/application-dev/notification/figures/notification.png deleted file mode 100644 index 18dcb99b0c531a19698f749105d88db91043837a..0000000000000000000000000000000000000000 Binary files a/en/application-dev/notification/figures/notification.png and /dev/null differ diff --git a/en/application-dev/notification/notification-brief.md b/en/application-dev/notification/notification-brief.md deleted file mode 100644 index 75237412fdf29d88843a9f23fa653f64f2de7c86..0000000000000000000000000000000000000000 --- a/en/application-dev/notification/notification-brief.md +++ /dev/null @@ -1,20 +0,0 @@ -# Common Event and Notification Overview - -The common event and notification module enables applications to publish messages to other applications, and receive messages from the system or other applications. These messages can be news push messages, advertisement notifications, warning information, and more. - -Common Event Service (CES) enables applications to publish, subscribe to, and unsubscribe from common events. Based on the sender type, common events are classified into system common events and custom common events. - -![ces](figures/ces.png) - -- System common event: sent by the system based on system policies to the applications that have subscribed to the event. This type of event includes the screen-on/off events that the users are aware of and the system events published by key system services, such as USB device attachment or detachment, network connection, and system update events. -- Custom common event: customized by applications to be received by specific subscribers. This type of event is usually related to the service logic of the sender applications. - -The Advanced Notification Service (ANS) enables applications to publish notifications. Below are some typical use cases for publishing notifications: - -- Display received SMS messages and instant messages. -- Display push messages of applications, such as advertisements, version updates, and news notifications. -- Display ongoing events, such as music playback, navigation information, and download progress. - -Notifications are displayed in the notification panel. Uses can delete a notification or click the notification to trigger predefined actions. - -![ans](figures/ans.png) diff --git a/en/application-dev/notification/notification-enable.md b/en/application-dev/notification/notification-enable.md new file mode 100644 index 0000000000000000000000000000000000000000..12aa4f41eb1570d707b4c65310cefe6aa45e1b17 --- /dev/null +++ b/en/application-dev/notification/notification-enable.md @@ -0,0 +1,49 @@ +# Enabling Notification + + +To publish a notification, you must have notification enabled for your application. You can call the [requestEnableNotification()](../reference/apis/js-apis-notificationManager.md#notificationrequestenablenotification) API to display a dialog box prompting the user to enable notification for your application. Note that the dialog box is displayed only when the API is called for the first time. + + **Figure 1** Dialog box prompting the user to enable notification + +![en-us_image_0000001416585590](figures/en-us_image_0000001416585590.png) + + +- Touching **allow** enables notification for the application, and touching **ban** keeps notification disabled. + +- The dialog box will not be displayed again when [requestEnableNotification()](../reference/apis/js-apis-notificationManager.md#notificationrequestenablenotification) is called later. The user can manually enable notification as follows. + + | 1. Swipe down from the upper left corner of the device screen to access the notification panel. | 2. Touch the **Settings** icon in the upper right corner. On the notification screen, locate the target application.| 3. Toggle on **Allow notifications**. | + | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | + | ![en-us_image_0000001417062434](figures/en-us_image_0000001417062434.png) | ![en-us_image_0000001466462297](figures/en-us_image_0000001466462297.png) | ![en-us_image_0000001466782025](figures/en-us_image_0000001466782025.png) | + + +## Available APIs + +For details about the APIs, see [@ohos.notificationManager](../reference/apis/js-apis-notificationManager.md#notificationrequestenablenotification). + +**Table 1** Notification APIs + +| Name | Description | +| -------- | -------- | +| isNotificationEnabled(bundle: BundleOption, callback: AsyncCallback<boolean>): void | Checks whether notification is enabled.
**NOTE**
This is a system API and cannot be called by third-party applications. | +| setNotificationEnable(bundle: BundleOption, enable: boolean, callback: AsyncCallback<void>): void | Sets whether to enable notification. Notification can be enabled or disabled in **Notifications** of the target application under **Settings** > **Apps & services** > **Apps**.
**NOTE**
This is a system API and cannot be called by third-party applications.| +| requestEnableNotification(callback: AsyncCallback<void>): void | Requests notification to be enabled. When called for the first time, this API displays a dialog box prompting the user to enable notification. | + + +## How to Develop + +1. Import the **NotificationManager** module. + + ```ts + import notificationManager from '@ohos.notificationManager'; + ``` + +2. Call the API to request notification to be enabled. + + ```ts + notificationManager.requestEnableNotification().then(() => { + console.info(`[ANS] requestEnableNotification success`); + }).catch((err) => { + console.error(`[ANS] requestEnableNotification failed, errCode[${err}]`); + }); + ``` diff --git a/en/application-dev/notification/notification-guidelines.md b/en/application-dev/notification/notification-guidelines.md deleted file mode 100644 index fb73f274202aafd9ff852201ca2fb8c5116aba50..0000000000000000000000000000000000000000 --- a/en/application-dev/notification/notification-guidelines.md +++ /dev/null @@ -1,258 +0,0 @@ - - -# Notification Development - -## When to Use - -OpenHarmony uses the Advanced Notification Service (ANS) to manage notifications, with support for various notification types, including text, long text, multi-text, image, social, and media. All system services and applications can send notifications through the notification API. Users can view all notifications on the system UI. - -Below are some typical use cases for notifications: - -- Display received SMS messages and instant messages. -- Display push messages of applications, such as advertisements and version updates. -- Display ongoing events, such as navigation information and download progress. - - - -## Notification Service Process - -The notification service process involves the ANS subsystem, notification sender, and notification subscriber. - -A notification is generated by the notification sender and sent to the ANS through inter-process communication (IPC). The ANS then distributes the notification to the notification subscriber. - -System applications also support notification-related configuration options, such as switches. The system configuration initiates a configuration request and sends the request to the ANS for storage in the memory and database. - -![1648113187545](figures/notification.png) - - - -## Available APIs - -Certain APIs can be called only by system applications that have been granted the **SystemCapability.Notification.Notification** permission. The APIs use either a callback or promise to return the result. The tables below list the APIs that use a callback, which provide the same functions as their counterparts that use a promise. For details about the APIs, see the [API document](../reference/apis/js-apis-notification.md). - -**Table 1** APIs for notification enabling - -| API | Description | -| ------------------------------------------------------------ | ---------------- | -| isNotificationEnabled(bundle: BundleOption, callback: AsyncCallback\): void | Checks whether notification is enabled.| -| enableNotification(bundle: BundleOption, enable: boolean, callback: AsyncCallback\): void | Sets whether to enable notification. | - -If the notification function of an application is disabled, it cannot send notifications. - - - -**Table 2** APIs for notification subscription - -| API | Description | -| ------------------------------------------------------------ | ---------------- | -| subscribe(subscriber: NotificationSubscriber, info: NotificationSubscribeInfo, callback: AsyncCallback\): void | Subscribes to a notification with the subscription information specified.| -| subscribe(subscriber: NotificationSubscriber, callback: AsyncCallback\): void | Subscribes to all notifications. | -| unsubscribe(subscriber: NotificationSubscriber, callback: AsyncCallback\): void | Unsubscribes from a notification. | - -The subscription APIs support subscription to all notifications and notifications from specific applications. - - - -**Table 3** Notification subscription callbacks - -| API | Description | -| ------------------------------------------------ | ---------------- | -| onConsume?:(data: SubscribeCallbackData) => void | Callback for receiving notifications. | -| onCancel?:(data: SubscribeCallbackData) => void | Callback for canceling notifications. | -| onUpdate?:(data: NotificationSortingMap) => void | Callback for notification sorting updates.| -| onConnect?:() => void; | Callback for subscription. | -| onDisconnect?:() => void; | Callback for unsubscription. | - - - -**Table 4** APIs for notification sending - -| API | Description | -| ------------------------------------------------------------ | ------------------------ | -| publish(request: NotificationRequest, callback: AsyncCallback\): void | Publishes a notification. | -| publish(request: NotificationRequest, userId: number, callback: AsyncCallback\): void | Publishes a notification to the specified user. | -| cancel(id: number, label: string, callback: AsyncCallback\): void | Cancels a specified notification. | -| cancelAll(callback: AsyncCallback\): void; | Cancels all notifications published by the application.| - -The **publish** API that carries **userId** can be used to publish notifications to subscribers of a specified user. - - - -## Development Guidelines - -The notification development process generally involves three aspects: subscribing to notifications, enabling the notification feature, and publishing notifications. - -### Modules to Import - -```js -import Notification from '@ohos.notification'; -``` - - - -### Subscribing to Notifications - -The notification recipient preferentially initiates a notification subscription request to the notification subsystem. - -```js -var subscriber = { - onConsume: function (data) { - let req = data.request; - console.info('===>onConsume callback req.id: ' + req.id); - }, - onCancel: function (data) { - let req = data.request; - console.info('===>onCancel callback req.id: : ' + req.id); - }, - onUpdate: function (data) { - console.info('===>onUpdate in test===>'); - }, - onConnect: function () { - console.info('===>onConnect in test===>'); - }, - onDisconnect: function () { - console.info('===>onDisConnect in test===>'); - }, - onDestroy: function () { - console.info('===>onDestroy in test===>'); - }, - }; - - Notification.subscribe(subscriber, (err, data) => { // This API uses an asynchronous callback to return the result. - if (err.code) { - console.error('===>failed to subscribe because ' + JSON.stringify(err)); - return; - } - console.info('===>subscribeTest success : ' + JSON.stringify(data)); - }); -``` - - - -### Publishing Notifications - -##### Enabling Notification - -Before publishing a notification, check whether the notification feature is enabled for your application. By default, the feature is disabled. The application calls **Notification.requestEnableNotification** to prompt the user to enable the feature. - -```js -Notification.requestEnableNotification().then((data) => { - console.info('===>requestEnableNotification success'); -}).catch((err) => { - console.error('===>requestEnableNotification failed because ' + JSON.stringify(err)); -}); -``` - - - -##### Publishing Notifications - -To publish a notification, create a **NotificationRequest** object and set attributes such as the notification type, title, and content. In the following examples, a normal text notification and a notification containing a **WantAgent** are being published. - -Normal text notification: - -```js -// Create a NotificationRequest object. -var notificationRequest = { - id: 1, - content: { - contentType: Notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, - normal: { - title: "test_title", - text: "test_text", - additionalText: "test_additionalText" - } - } -} - -// Publish the notification. -Notification.publish(notificationRequest).then((data) => { - console.info('===>publish promise success req.id : ' + notificationRequest.id); -}).catch((err) => { - console.error('===>publish promise failed because ' + JSON.stringify(err)); -}); -``` - - - -Notification containing **WantAgent**: - -For details about how to use **WantAgent**, see [WantAgent Development](https://gitee.com/openharmony/docs/blob/master/en/application-dev/ability/wantagent.md). - -- Create a **WantAgent** object. - -```js -import wantAgent from '@ohos.wantAgent'; - -// WantAgentInfo object -var wantAgentInfo = { - wants: [ - { - bundleName: 'ohos.samples.eTSNotification', - abilityName: 'ohos.samples.eTSNotification.MainAbility', - } - ], - operationType: wantAgent.OperationType.START_ABILITY, - requestCode: 0, - wantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] -} - -// WantAgent object -var WantAgent; - -// getWantAgent callback -function getWantAgentCallback(err, data) { - console.info("===>getWantAgentCallback===>"); - if (err.code == 0) { - WantAgent = data; - } else { - console.info('----getWantAgent failed!----'); - } -} - -// Obtain the WantAgent object. -wantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback) -``` - -- Publish the notification. - -```js -// Create a NotificationRequest object. -var notificationRequest = { - content: { - contentType: Notification.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, - normal: { - title: "AceApplication_Title", - text: "AceApplication_Text", - additionalText: "AceApplication_AdditionalText" - }, - }, - id: 1, - label: 'TEST', - wantAgent: WantAgent, - slotType: Notification.SlotType.OTHER_TYPES, - deliveryTime: new Date().getTime() -} - -// Publish the notification. -Notification.publish(notificationRequest).then((data) => { - console.info('===>publish promise success req.id : ' + notificationRequest.id); -}).catch((err) => { - console.error('===>publish promise failed because ' + JSON.stringify(err)); -}); -``` - - - -- Cancel the notification. - -An application can cancel a single notification or all notifications. An application can cancel only the notifications published by itself. - -```js -// cancel callback -function cancelCallback(err) { - console.info("===>cancelCallback===>"); -} - -Notification.cancel(1, "label", cancelCallback) -``` diff --git a/en/application-dev/notification/notification-overview.md b/en/application-dev/notification/notification-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..6bef8be8fd446e62b3e3da04582b467c9ddc5961 --- /dev/null +++ b/en/application-dev/notification/notification-overview.md @@ -0,0 +1,27 @@ +# Notification Overview + + +## Introduction + +All system applications and services can publish notifications through the notification APIs. Users can view the notifications in the notification panel or click a notification to open the publishing application. + +Below are some typical use cases for notifications: + +- Display received SMS messages and instant messages. + +- Display push messages, such as advertisements and version updates. + +- Display ongoing events, such as the download progress. + +The Advanced Notification Service (ANS) in OpenHarmony is used to manage notifications of various types, such as basic notifications, progress notifications, and reminders published through the background agent. + + +## Notification Service Process + +The notification service process involves the notification subsystem, notification sender, and notification subscriber. + +A notification is generated by the notification sender and sent to the notification subsystem through [inter-process communication (IPC)](../connectivity/ipc-rpc-overview.md). The notification subsystem then distributes the notification to the notification subscriber. + +System applications also support notification-related configuration options, such as switches. The system configuration initiates a configuration request and sends the request to the notification subsystem for storage in the memory and database. + +![en-us_image_0000001466582017](figures/en-us_image_0000001466582017.png) diff --git a/en/application-dev/notification/notification-subscription.md b/en/application-dev/notification/notification-subscription.md new file mode 100644 index 0000000000000000000000000000000000000000..a633a2bb955bcf877fbe4befb8b40ad103d7e7e6 --- /dev/null +++ b/en/application-dev/notification/notification-subscription.md @@ -0,0 +1,82 @@ +# Notification Subscription (Open Only to System Applications) + + +To receive notifications, an application must subscribe to notifications first. The notification subsystem provides two types of subscription APIs, allowing applications to subscribe to notifications from all applications or notifications from a specific application. + + +You can use the **NotificationSubscriber** object to provide callbacks for subscription events, such as subscription success, notification reception, notification cancellation, and subscription cancellation. + + +## Available APIs + +The major APIs for notification subscription are described as follows. For details about the APIs, see [@ohos.notificationSubscribe](../reference/apis/js-apis-notificationSubscribe.md). + +**Table 1** Major APIs for notification subscription + +| Name | Description| +| -------- | -------- | +| subscribe(subscriber: NotificationSubscriber, info: NotificationSubscribeInfo, callback: AsyncCallback<void>): void | Subscribes to notifications from a specific application.| +| subscribe(subscriber: NotificationSubscriber, callback: AsyncCallback<void>): void | Subscribes to notifications from all applications. | + +**Table 2** Callbacks for notification subscription + +| Name | Description| +| -------- | -------- | +| onConsume?:(data: SubscribeCallbackData) => void | Callback for receiving notifications. | +| onCancel?:(data: SubscribeCallbackData) => void | Callback for canceling notifications. | +| onUpdate?:(data: NotificationSortingMap) => void | Callback for notification sorting updates. | +| onConnect?:() => void; | Callback for subscription. | +| onDisconnect?:() => void; | Callback for unsubscription. | +| onDestroy?:() => void | Callback for disconnecting from the notification subsystem. | +| onDoNotDisturbDateChange?:(mode: notification.DoNotDisturbDate) => void | Callback for the Do Not Disturb (DNT) time changes.| +| onEnabledNotificationChanged?:(callbackData: EnabledNotificationCallbackData) => void | Callback for notification switch changes. | + + +## How to Develop + +1. Request the **ohos.permission.NOTIFICATION_CONTROLLER** permission. For details, see [Permission Application Guide](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file). + +2. Import the **notificationSubscribe** module. + + ```ts + import notificationSubscribe from '@ohos.notificationSubscribe'; + ``` + +3. Create a **subscriber** object. + + ```ts + let subscriber = { + onConsume: function (data) { + let req = data.request; + console.info('[ANS] onConsume callback req.id: ' + req.id); + }, + onCancel: function (data) { + let req = data.request; + console.info('[ANS] onCancel callback req.id: : ' + req.id); + }, + onUpdate: function (data) { + console.info('[ANS] onUpdate in test'); + }, + onConnect: function () { + console.info('[ANS] onConnect in test'); + }, + onDisconnect: function () { + console.info('[ANS] onDisConnect in test'); + }, + onDestroy: function () { + console.info('[ANS] onDestroy in test'); + }, + }; + ``` + +4. Initiate notification subscription. + + ```ts + notificationSubscribe.subscribe(subscriber, (err, data) => { // This API uses an asynchronous callback to return the result. + if (err) { + console.error(`[ANS] failed to subscribe, error[${err}]`); + return; + } + console.info(`[ANS] subscribeTest success : + ${data}`); + }); + ``` diff --git a/en/application-dev/notification/notification-with-wantagent.md b/en/application-dev/notification/notification-with-wantagent.md new file mode 100644 index 0000000000000000000000000000000000000000..d8f0321d28738749d6ed6073e49f26181c22e706 --- /dev/null +++ b/en/application-dev/notification/notification-with-wantagent.md @@ -0,0 +1,121 @@ +# Adding a WantAgent Object to a Notification + +A [WantAgent](../reference/apis/js-apis-app-ability-wantAgent.md) object encapsulates an intention to start a specified ability, release a common event, and more. In OpenHarmony, a **WantAgent** object can be passed in a notification from the publisher to the subscriber, so as to trigger the intention specified. For example, you may want the user to start a specific ability by touching the notification published by your application. In this case, you can add a **WantAgent** object that encapsulates such an action to the notification. After receiving the **WantAgent** object, the system triggers it once the user touches the notification from the notification panel, starting the specified ability. + +Below you can see the process of adding a **WantAgent** object to a notification. The notification publisher requests a **WantAgent** object from the Ability Manager Service (AMS), and then sends a notification carrying the **WantAgent** object to the home screen. When the user touches the notification from the notification panel on the home screen, the **WantAgent** object is triggered. + + **Figure 1** Publishing a notification with a WantAgent object +![notification-with-wantagent](figures/notification-with-wantagent.png) + + +## Available APIs + +For details about the APIs, see [@ohos.app.ability.wantAgent](../reference/apis/js-apis-app-ability-wantAgent.md). + +| Name| Description| +| -------- | -------- | +| getWantAgent(info: WantAgentInfo, callback: AsyncCallback<WantAgent>): void | Creates a **WantAgent** object.| +| trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: Callback<CompleteData>): void | Triggers a **WantAgent** object.| +| cancel(agent: WantAgent, callback: AsyncCallback<void>): void | Cancels a **WantAgent** object.| +| getWant(agent: WantAgent, callback: AsyncCallback<Want>): void | Obtains a **WantAgent** object.| +| equal(agent: WantAgent, otherAgent: WantAgent, callback: AsyncCallback<boolean>): void | Checks whether two **WantAgent** objects are equal. | + + +## How to Develop + +1. [Enable notification](notification-enable.md). An application can use the notification feature only after being authorized by the user. + +2. Import the modules. + + ```typescript + import notificationManager from '@ohos.notificationManager'; + import wantAgent from '@ohos.app.ability.wantAgent'; + ``` + +3. Create a **WantAgentInfo** object. + + Scenario 1: Create a [WantAgentInfo](../reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md) object for starting a UIAbility component. + + ```typescript + let wantAgentObj = null; // Save the WantAgent object created. It will be used to complete the trigger operations. + + // Set the action type through operationType of WantAgentInfo. + let wantAgentInfo = { + wants: [ + { + deviceId: '', + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', + action: '', + entities: [], + uri: '', + parameters: {} + } + ], + operationType: wantAgent.OperationType.START_ABILITY, + requestCode: 0, + wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG] + }; + ``` + + Scenario 2: Create a [WantAgentInfo](../reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md) object for publishing a [common event](../application-models/common-event-overview.md). + + ```typescript + let wantAgentObj = null; // Save the WantAgent object created. It will be used to complete the trigger operations. + + // Set the action type through operationType of WantAgentInfo. + let wantAgentInfo = { + wants: [ + { + action: 'event_name', // Set the action name. + parameters: {}, + } + ], + operationType: wantAgent.OperationType.SEND_COMMON_EVENT, + requestCode: 0, + wantAgentFlags: [wantAgent.WantAgentFlags.CONSTANT_FLAG], + } + ``` + +4. Invoke the [getWantAgent()](../reference/apis/js-apis-app-ability-wantAgent.md#wantagentgetwantagent) API to create a **WantAgent** object. + + ```typescript + // Create a WantAgent object. + wantAgent.getWantAgent(wantAgentInfo, (err, data) => { + if (err) { + console.error('[WantAgent]getWantAgent err=' + JSON.stringify(err)); + return; + } + console.info('[WantAgent]getWantAgent success'); + wantAgentObj = data; + }); + ``` + +5. Create a **NotificationRequest** object and publish a notification that carries the **WantAgent** object. + + ```typescript + // Create a NotificationRequest object. + let notificationRequest = { + content: { + contentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, + normal: { + title: 'Test_Title', + text: 'Test_Text', + additionalText: 'Test_AdditionalText', + }, + }, + id: 1, + label: 'TEST', + wantAgent: wantAgentObj, + } + + notificationManager.publish(notificationRequest, (err) => { + if (err) { + console.error(`[ANS] failed to publish, error[${err}]`); + return; + } + console.info(`[ANS] publish success`); + }); + ``` + +6. When the user touches the notification from the notification panel, the system automatically triggers the action specified in the **WantAgent** object. diff --git a/en/application-dev/notification/progress-bar-notification.md b/en/application-dev/notification/progress-bar-notification.md new file mode 100644 index 0000000000000000000000000000000000000000..de430008e3048532e9afea94d83a62dd2f8342c1 --- /dev/null +++ b/en/application-dev/notification/progress-bar-notification.md @@ -0,0 +1,69 @@ +# Publishing a Progress Notification + + +The progress notification is a commonly used notification type, mainly used to display the progress of an ongoing operation, such as file downloading. When publishing a progress notification through the notification subsystem, you can use the readily available template by specifying the related attributes, such as the template name and template data. + +In the [NotificationTemplate](../reference/apis/js-apis-notificationManager.md#notificationtemplate), which can only be of the progress type, **data** indicates custom template data. + + +## Available APIs + +| Name| Description| +| -------- | -------- | +| isSupportTemplate(templateName: string, callback: AsyncCallback<boolean>): void | Checks whether a specific template is supported. This API uses an asynchronous callback to return the result.
Only the progress-type template is supported.| + + +## How to Develop + +1. [Enable notification](notification-enable.md). An application can use the notification feature only after being authorized by the user. + +2. Import the module. + + ```ts + import notificationManager from '@ohos.notificationManager'; + ``` + +3. Check whether a specific template is supported. In this example, the template of the **downloadTemplate** type is checked. + + ```ts + notificationManager.isSupportTemplate('downloadTemplate').then((data) => { + console.info(`[ANS] isSupportTemplate success`); + let isSupportTpl: boolean = data; // The value **true** means that the template of the **downloadTemplate** type is supported; and false means the opposite. + // ... + }).catch((err) => { + console.error(`[ANS] isSupportTemplate failed, error[${err}]`); + }); + ``` + + > **NOTE** + > + > Proceed with the step below only when the specified template is supported. +4. Create a **NotificationRequest** object and publish a progress notification. + + ```ts + let notificationRequest = { + id: 1, + content: { + contentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, + normal: { + title: 'test_title', + text: 'test_text', + additionalText: 'test_additionalText' + } + }, + // Create a progress template. The name field has a fixed value of downloadTemplate. + template: { + name: 'downloadTemplate', + data: { title: 'File Title', fileName: 'music.mp4', progressValue: 45 } + } + } + + // Publish the notification. + notificationManager.publish(notificationRequest, (err) => { + if (err) { + console.error(`[ANS] failed to publish, error[${err}]`); + return; + } + console.info(`[ANS] publish success `); + }); + ``` diff --git a/en/application-dev/notification/text-notification.md b/en/application-dev/notification/text-notification.md new file mode 100644 index 0000000000000000000000000000000000000000..ddbc5478cee37208da33d2acecb71417deaccdc2 --- /dev/null +++ b/en/application-dev/notification/text-notification.md @@ -0,0 +1,160 @@ +# Publishing a Basic Notification + + +You can publish basic notifications to send SMS messages, prompt messages, and advertisements. Available content types of basic notifications include normal text, long text, multi-line text, and picture-attached. + + + **Table 1** Basic notification content types + +| Type| Description| +| -------- | -------- | +| NOTIFICATION_CONTENT_BASIC_TEXT | Normal text notification.| +| NOTIFICATION_CONTENT_LONG_TEXT | Long text notification.| +| NOTIFICATION_CONTENT_MULTILINE | Multi-line text notification.| +| NOTIFICATION_CONTENT_PICTURE | Picture-attached notification.| + + +Notifications are displayed in the notification panel, which is the only system subscriber to notifications. Below you can see two examples of the basic notification. + +**Figure 1** Examples of the basic notification +![en-us_image_0000001466462305](figures/en-us_image_0000001466462305.png) + + +## Available APIs + +The following table describes the APIs for notification publishing. You specify the notification type by setting the [NotificationRequest](../reference/apis/js-apis-notificationManager.md#notificationrequest) parameter in the APIs. + +| Name| Description| +| -------- | -------- | +| publish(request: NotificationRequest, callback: AsyncCallback<void>): void | Publishes a notification. | +| cancel(id: number, label: string, callback: AsyncCallback<void>): void | Cancels a notification. | +| cancelAll(callback: AsyncCallback<void>): void; | Cancels all notifications published by the application.| + + +## How to Develop + +1. [Enable notification](notification-enable.md). An application can use the notification feature only after being authorized by the user. + +2. Import the module. + + ```ts + import notificationManager from '@ohos.notificationManager'; + ``` + +3. Create a **NotificationRequest** object and publish a progress notification. + - A normal text notification consists of the **title**, **text**, and **additionalText** parameters, of which **title** and **text** are mandatory. The value of these parameters contains less than 200 bytes. + + ```ts + let notificationRequest = { + id: 1, + content: { + contentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT, // Basic notification + normal: { + title: 'test_title', + text: 'test_text', + additionalText: 'test_additionalText', + } + } + } + + notificationManager.publish(notificationRequest, (err) => { + if (err) { + console.error(`[ANS] failed to publish, error[${err}]`); + return; + } + console.info(`[ANS] publish success`); + }); + ``` + + Below is an example of the normal text notification. + ![en-us_image_0000001466782033](figures/en-us_image_0000001466782033.png) + - In addition to the parameters in the normal text notification, the long text notification provides the **longText**, **briefText**, and **expandedTitle** parameters. The value of **longText** contains a maximum of 1024 bytes, while that of any other parameters contains less than 200 bytes. By default, a long-text notification looks in the same way as a normal text notification. When expanded, the notification displays the title and content specified in **expandedTitle** and **longText**, respectively. + + ```ts + let notificationRequest = { + id: 1, + content: { + contentType: notificationManager.ContentType.NOTIFICATION_CONTENT_LONG_TEXT, // Long-text notification + longText: { + title: 'test_title', + text: 'test_text', + additionalText: 'test_additionalText', + longText: 'test_longText', + briefText: 'test_briefText', + expandedTitle: 'test_expandedTitle', + } + } + } + + // Publish the notification. + notificationManager.publish(notificationRequest, (err) => { + if (err) { + console.error(`[ANS] failed to publish, error[${err}]`); + return; + } + console.info(`[ANS] publish success`); + }); + ``` + + Below is an example of the long-text notification. + ![en-us_image_0000001416745530](figures/en-us_image_0000001416745530.png) + - In addition to the parameters in the normal text notification, the multi-line text notification provides the **lines**, **briefText**, and **longTitle** parameters. The value of these parameters contains less than 200 bytes. By default, a multi-line notification looks in the same way as a normal text notification. When expanded, the notification displays the title and content specified in **longTitle** and **lines**, respectively. + + ```ts + let notificationRequest = { + id: 1, + content: { + contentType: notificationManager.ContentType.NOTIFICATION_CONTENT_MULTILINE, // Multi-line text notification + multiLine: { + title: 'test_title', + text: 'test_text', + briefText: 'test_briefText', + longTitle: 'test_longTitle', + lines: ['line_01', 'line_02', 'line_03', 'line_04'], + } + } + } + + // Publish the notification. + notificationManager.publish(notificationRequest, (err) => { + if (err) { + console.error(`[ANS] failed to publish, error[${err}]`); + return; + } + console.info(`[ANS] publish success`); + }); + ``` + + Below is an example of the multi-line notification. + ![en-us_image_0000001417062446](figures/en-us_image_0000001417062446.png) + - In addition to the parameters in the normal text notification, the picture-attached text notification provides the **picture**, **briefText**, and **expandedTitle** parameters. The value of **picture** is a pixel map that does not exceed 2 MB. + + ```ts + let notificationPicture: PixelMap = undefined; // Obtain the pixel map information. + let notificationRequest = { + id: 1, + content: { + contentType: notificationManager.ContentType.NOTIFICATION_CONTENT_PICTURE, + picture: { + title: 'test_title', + text: 'test_text', + additionalText: 'test_additionalText', + briefText: 'test_briefText', + expandedTitle: 'test_expandedTitle', + picture: notificationPicture + } + } + } + + // Publish the notification. + notificationManager.publish(notificationRequest, (err) => { + if (err) { + console.error(`[ANS] failed to publish, error[${err}]`); + return; + } + console.info(`[ANS] publish success `); + }); + ``` + + Below is an example of the picture-attached notification. + ![en-us_image_0000001466582045](figures/en-us_image_0000001466582045.png)