目录

RemoteNotificationExtensionAbility

When a user receives a text-to-speech message (such as an order or logistics voice notification) sent by an app and the app process is not running in the foreground, Push Kit will start a child process of the app and transfer the message content to it. You can complete service processing (such as voice broadcast) in this child process and return your customized message content. Push Kit will display the notification using the content. Custom content must be returned within 10 seconds. Otherwise, the original message content will be displayed by default.

RemoteNotificationExtensionAbility provides callbacks for message data retrieval and lifecycle destruction. The restrictions are as follows:

If this extension ability fails to be executed, an error may be returned. Rectify the fault based on the error information. For details, please refer to ArkTS API Error Codes.

If your app process is running in the foreground, Push Kit will not display the notification. You can call pushService.receiveMessage to receive the message content in the app process and complete service processing.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Push.PushService

Since: 4.1.0(11)

Constraints

To ensure system security and stability and prevent RemoteNotificationExtensionAbility from abusing system resources, the system restricts its capabilities. Referencing certain modules is not supported. For details, please refer to the Appendix.

Importing Modules

import { RemoteNotificationExtensionAbility } from '@kit.PushKit';

Attributes

Model restriction: This attribute can be used only in the stage model.

System capability: SystemCapability.Push.PushService

Since: 4.1.0(11)

Name Type Read-Only Optional Description
context RemoteNotificationExtensionContext No No Context of RemoteNotificationExtensionAbility, which inherits from ExtensionContext.

onReceiveMessage

onReceiveMessage(remoteNotificationInfo: pushCommon.RemoteNotificationInfo): Promise<pushCommon.RemoteNotificationContent>

API for receiving text-to-speech message data after an app inherits from RemoteNotificationExtensionAbility. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Push.PushService

Since: 4.1.0(11)

Parameters:

Name Type Mandatory Description
remoteNotificationInfo pushCommon.RemoteNotificationInfo Yes Text-to-speech message data.

Returns:

Type Description
Promise<pushCommon.RemoteNotificationContent> Promise used to return the updated notification content.

Example:

import { RemoteNotificationExtensionAbility, pushCommon } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

const LOG_DOMAIN = 0x0000;
const LOG_TAG = 'RemoteNotificationExtAbility';

// In the following example, RemoteNotificationExtAbility inherits from RemoteNotificationExtensionAbility.
export default class RemoteNotificationExtAbility extends RemoteNotificationExtensionAbility {
  async onReceiveMessage(remoteNotificationInfo: pushCommon.RemoteNotificationInfo): Promise<pushCommon.RemoteNotificationContent> {
    hilog.info(LOG_DOMAIN, LOG_TAG, 'onReceiveMessage notifyId: %{public}d', remoteNotificationInfo.id);
    try {
      // Execute voice broadcast.
      await this.playVoice(remoteNotificationInfo);
    } catch (err) {
      const e: BusinessError = err as BusinessError;
      hilog.error(LOG_DOMAIN, LOG_TAG, 'playVoice failed, code=%{public}d, message=%{public}s', e.code, e.message);
    }

    // Construct the updated notification content.
    const remoteNotificationContent: pushCommon.RemoteNotificationContent = {
      title: 'Default replace title.',
      text: 'Default replace text.',
      badgeNumber: 1,
      wantAgent: {
        abilityName: 'DemoAbility',
        parameters: {
          key: 'Default value'
        }
      }
    };

    return remoteNotificationContent;
  }

  /**
   * Voice broadcast.
   * You can customize the logic of voice broadcast based on the notification content.
   * @param remoteNotificationInfo Notification content.
   */
  private async playVoice(remoteNotificationInfo: pushCommon.RemoteNotificationInfo): Promise<void> {
    // Implement the logic of voice broadcast by yourself.
  }
}

onDestroy

onDestroy(): void

Callback triggered when the RemoteNotificationExtensionAbility is destroyed. You are advised to clear resources in this method.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Push.PushService

Since: 4.1.0(11)

Example:

import { RemoteNotificationExtensionAbility } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

const LOG_DOMAIN = 0x0000;
const LOG_TAG = 'RemoteNotificationExtAbility';

// In the following example, RemoteNotificationExtAbility inherits from RemoteNotificationExtensionAbility.
export default class RemoteNotificationExtAbility extends RemoteNotificationExtensionAbility {
  onDestroy(): void {
    hilog.info(LOG_DOMAIN, LOG_TAG, 'RemoteNotificationExtAbility onDestroy');

    try {
      this.releaseResources();
    } catch (err) {
      const e: BusinessError = err as BusinessError;
      hilog.error(LOG_DOMAIN, LOG_TAG, 'releaseResources failed, code=%{public}d, message=%{public}s', e.code, e.message);
    }
  }
  /**
   * Releases resources.
   * Implement the service logic based on your needs.
   */
  private releaseResources(): void {
    // Logic of resource release.
  }
}

Appendix

RemoteNotificationExtensionAbility does not support referencing the following modules.

Kit Modules
Notification Kit

@ohos.notification (Notification)

@ohos.notificationManager (NotificationManager)
Form Kit

@ohos.app.form.formProvider (formProvider)

@ohos.app.form.formInfo (formInfo)

@ohos.app.form.formBindingData (formBindingData)

@ohos.app.form.FormExtensionAbility (FormExtensionAbility)

@ohos.application.formBindingData (formBindingData)

@ohos.application.formInfo (formInfo)

@ohos.application.formProvider (formProvider)
ArkUI

@ohos.prompt (Prompt)

@ohos.promptAction (Prompt)

@ohos.window (Window)
Live View Kit core.liveview.liveViewManager
Call Service Kit telephony.voipCall