This module provides the capabilities for managing notification extensions, including opening the notification extension subscription settings page, subscribing to and unsubscribing from notification extensions, and obtaining and setting the notification authorization status.
The initial APIs of this module are supported since API version 22. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Modules to Import
import { notificationExtensionSubscription } from '@kit.NotificationKit';
import { BusinessError } from '@kit.BasicServicesKit'; notificationExtensionSubscription.openSubscriptionSettings
openSubscriptionSettings(context: UIAbilityContext): Promise<void>
Opens the settings screen of notification extension subscription in a semi-modal dialog box. On this screen, the user can toggle on the Allow access to notifications on this device switch and grant access to notifications for specified applications. This API uses a promise to return the result.
System capability: SystemCapability.Notification.Notification
Required permissions: ohos.permission.SUBSCRIBE_NOTIFICATION
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| context | UIAbilityContext | Yes | Context of the ability bound to the notification setting page. |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Universal Error Codes and Notification Error Codes.
| ID | Error Message |
|---|---|
| 201 | Permission denied or current device not supported. |
| 1600001 | Internal error. |
| 1600018 | The notification settings window is already displayed. |
| 1600023 | The application does not implement the NotificationSubscriberExtensionAbility. |
Example
import { common } from '@kit.AbilityKit';
try {
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
notificationExtensionSubscription.openSubscriptionSettings(context).then(() => {
console.info(`openSubscriptionSettings success`);
}).catch((e: Error) => {
let error = e as BusinessError;
console.error(`failed to call openSubscriptionSettings, code is ${error.code}, message is ${error.message}`)
});
} catch (error) {
console.error(`failed to call openSubscriptionSettings, code is ${error.code}, message is ${error.message}`)
} notificationExtensionSubscription.openSubscriptionSettingsWithResult
openSubscriptionSettingsWithResult(context: UIAbilityContext): Promise<UserGrantSetting>
Opens the settings screen of notification extension subscription in a semi-modal dialog box. On this screen, the user can toggle on the "Allow access to notifications on this device" switch and grant access to notifications for specified applications. This API uses a promise to return the result. When the semi-modal window is closed, the user-defined authorization result is returned.
Since: 26.0.0
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Notification.Notification
Required permissions: ohos.permission.SUBSCRIBE_NOTIFICATION
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| context | UIAbilityContext | Yes | Context of the ability bound to the notification setting page. |
Return value
| Type | Description |
|---|---|
| Promise<UserGrantSetting> | Promise used to return the result of the authorization set by the user. |
Error codes
For details about the error codes, see Universal Error Codes and Notification Error Codes.
| ID | Error Message |
|---|---|
| 201 | Permission denied or current device not supported. |
| 1600001 | Internal error. |
| 1600018 | The notification settings window is already displayed. |
| 1600023 | The application does not implement the NotificationSubscriberExtensionAbility. |
Example
import { common } from '@kit.AbilityKit';
try {
// Obtain the context from the component and ensure that the return value of this.getUIContext().getHostContext() is UIAbilityContext.
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
notificationExtensionSubscription.openSubscriptionSettingsWithResult(context).then((data) => {
console.info(`openSubscriptionSettingsWithResult success, data: ${JSON.stringify(data)}`);
}).catch((e: Error) => {
let error = e as BusinessError;
console.error(`failed to call openSubscriptionSettingsWithResult, code is ${error.code}, message is ${error.message}`)
});
} catch (error) {
console.error(`failed to call openSubscriptionSettingsWithResult, code is ${error.code}, message is ${error.message}`)
} notificationExtensionSubscription.subscribe
subscribe(info: NotificationExtensionSubscriptionInfo[]): Promise<void>
Subscribes to the notification extension. You can subscribe to the notification extension only after obtaining the unique address of the Bluetooth device by calling the APIs related to the Bluetooth modules. This API uses a promise to return the result.
System capability: SystemCapability.Notification.Notification
Required permissions: ohos.permission.SUBSCRIBE_NOTIFICATION
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| info | NotificationExtensionSubscriptionInfo[] | Yes | List of subscribed notifications (in array). |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Universal Error Codes and Notification Error Codes.
| ID | Error Message |
|---|---|
| 201 | Permission denied or current device not supported. |
| 1600001 | Internal error. |
| 1600003 | Failed to connect to the service. |
| 1600023 | The application does not implement the NotificationSubscriberExtensionAbility. |
Example
let infos: notificationExtensionSubscription.NotificationExtensionSubscriptionInfo[] = [
{
addr: '01:23:45:67:89:AB', // Use the dynamically obtained Bluetooth address.
type: notificationExtensionSubscription.SubscribeType.BLUETOOTH
}
];
notificationExtensionSubscription.subscribe(infos).then(() => {
console.info(`subscribe success`);
}).catch((err: BusinessError) => {
console.error(`subscribe fail, code is ${err.code}, message is ${err.message}`);
}); notificationExtensionSubscription.unsubscribe
unsubscribe(): Promise<void>
Unsubscribes from the notification extension. This API uses a promise to return the result.
System capability: SystemCapability.Notification.Notification
Required permissions: ohos.permission.SUBSCRIBE_NOTIFICATION
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Universal Error Codes and Notification Error Codes.
| ID | Error Message |
|---|---|
| 201 | Permission denied or current device not supported. |
| 1600001 | Internal error. |
| 1600003 | Failed to connect to the service. |
Example
notificationExtensionSubscription.unsubscribe().then(() => {
console.info(`unsubscribe success`);
}).catch((err: BusinessError) => {
console.error(`unsubscribe fail, code is ${err.code}, message is ${err.message}`);
}); notificationExtensionSubscription.getSubscribeInfo
getSubscribeInfo(): Promise<NotificationExtensionSubscriptionInfo[]>
Obtains the subscription information about the notification extension of this application. This API uses a promise to return the result.
System capability: SystemCapability.Notification.Notification
Required permissions: ohos.permission.SUBSCRIBE_NOTIFICATION
Return value
| Type | Description |
|---|---|
| Promise<NotificationExtensionSubscriptionInfo[]> | Promise used to return the NotificationExtensionSubscriptionInfo[] array. |
Error codes
For details about the error codes, see Universal Error Codes and Notification Error Codes.
| ID | Error Message |
|---|---|
| 201 | Permission denied or current device not supported. |
| 1600001 | Internal error. |
| 1600003 | Failed to connect to the service. |
Example
notificationExtensionSubscription.getSubscribeInfo().then((data: notificationExtensionSubscription.NotificationExtensionSubscriptionInfo[]) => {
console.info(`getSubscribeInfo successfully. Data: ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
console.error(`getSubscribeInfo fail, code is ${err.code}, message is ${err.message}`);
}); notificationExtensionSubscription.isUserGranted
isUserGranted(): Promise<boolean>
Checks whether the Allow access to notifications on this device switch is toggled on. This API uses a promise to return the result.
System capability: SystemCapability.Notification.Notification
Required permissions: ohos.permission.SUBSCRIBE_NOTIFICATION
Return value
| Type | Description |
|---|---|
| Promise<boolean> | Promise used to return the result. The value true indicates that this feature is enabled, and false indicates the opposite. |
Error codes
For details about the error codes, see Universal Error Codes and Notification Error Codes.
| ID | Error Message |
|---|---|
| 201 | Permission denied or current device not supported. |
| 1600001 | Internal error. |
| 1600003 | Failed to connect to the service. |
Example
notificationExtensionSubscription.isUserGranted().then((isOpen: boolean) => {
if (isOpen) {
console.info('isUserGranted true');
} else {
console.info('isUserGranted false');
}
}).catch((err: BusinessError) => {
console.error(`isUserGranted fail, code is ${err.code}, message is ${err.message}`);
}); notificationExtensionSubscription.getUserGrantedEnabledBundles
getUserGrantedEnabledBundles(): Promise<GrantedBundleInfo[]>
Obtains the applications that are allowed to access device notifications for the current application. This API uses a promise to return the result.
System capability: SystemCapability.Notification.Notification
Required permissions: ohos.permission.SUBSCRIBE_NOTIFICATION
Return value
| Type | Description |
|---|---|
| Promise<GrantedBundleInfo[]> | Promise used to return the list of applications that are allowed to access device notifications for the current application. |
Error codes
For details about the error codes, see Universal Error Codes and Notification Error Codes.
| ID | Error Message |
|---|---|
| 201 | Permission denied or current device not supported. |
| 1600001 | Internal error. |
| 1600003 | Failed to connect to the service. |
Example
notificationExtensionSubscription.getUserGrantedEnabledBundles().then((data: notificationExtensionSubscription.GrantedBundleInfo[]) => {
console.info(`getUserGrantedEnabledBundles successfully. Data: ${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
console.error(`getUserGrantedEnabledBundles fail, code is ${err.code}, message is ${err.message}`);
}); NotificationExtensionSubscriptionInfo
type NotificationExtensionSubscriptionInfo = _NotificationExtensionSubscriptionInfo
Describes the information about the notification extension subscription.
System capability: SystemCapability.Notification.Notification
| Type | Description |
|---|---|
| _NotificationExtensionSubscriptionInfo | Describes the information about the notification extension subscription. |
NotificationInfo
type NotificationInfo = _NotificationInfo
Defines the notification information in the onReceiveMessage callback of the notification subscription extension ability.
System capability: SystemCapability.Notification.Notification
| Type | Description |
|---|---|
| _NotificationInfo | Notification information delivered to the onReceiveMessage callback of ExtensionAbility for notification subscriptions. |
SubscribeType
Describes the type that enables notification extension subscription.
System capability: SystemCapability.Notification.Notification
| Name | Value | Description |
|---|---|---|
| BLUETOOTH | 0 | Bluetooth. |
BundleOption
type BundleOption = _BundleOption
Describes the bundle information of an application.
System capability: SystemCapability.Notification.Notification
| Type | Description |
|---|---|
| _BundleOption | Bundle information. |
GrantedBundleInfo
type GrantedBundleInfo = _GrantedBundleInfo
Describes the bundle information of the authorized application.
System capability: SystemCapability.Notification.Notification
| Type | Description |
|---|---|
| _GrantedBundleInfo | Bundle information of the authorized application. |
UserGrantSetting
type UserGrantSetting = _UserGrantSetting
Describes the user authorization settings.
Since: 26.0.0
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Notification.Notification
| Type | Description |
|---|---|
| _UserGrantSetting | User authorization settings. |