@ohos.notificationExtensionSubscription (notificationExtensionSubscription)

The notificationExtensionSubscription module provides capabilities for managing notification extension, including opening the extension settings screen, subscribing to/unsubscribing from notification extension, and obtaining/setting the notification authorization status.

NOTE

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	Ability context bound to the notification settings 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(`openSubscriberSettings success`);
  }).catch((e:Error) => {
    let error = e as BusinessError
    console.error(`failed to call openSubscriptionSettings ${JSON.stringify(error)}`)
  });
} catch (error) {
  console.error(`failed to call openSubscriptionSettings ${JSON.stringify(error)}`)
}

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	Ability context bound to the notification settings 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 ${JSON.stringify(error)}`)
  });
} catch (error) {
  console.error(`failed to call openSubscriptionSettingsWithResult ${JSON.stringify(error)}`)
}

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: ${JSON.stringify(err)}`);
});

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: ${JSON.stringify(err)}`);
});

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: ${JSON.stringify(err)}`);
});

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: ${JSON.stringify(err)}`);
});

notificationExtensionSubscription.getUserGrantedEnabledBundles

getUserGrantedEnabledBundles(): Promise<GrantedBundleInfo[]>

Obtains the applications that are allowed to access device notifications. 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 applications obtained.

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: ${JSON.stringify(err)}`);
});

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

Describes the notification information delivered to the onReceiveMessage callback of ExtensionAbility for notification subscriptions.

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.