目录

PushExtensionAbility

This module is available only to system apps and is not open for application.

When an app enters the background, the system typically restricts its resource usage (such as CPU), which may prevent the app from completing data synchronization with the app server. Push Kit provides the capability for apps to synchronize updates with the app server even when running in the background. When a background message for starting an app child process arrives at a device, Push Kit will start the child process and transfer the message content to the child process, where you can complete operations such as background data processing and data updates.

PushExtensionAbility 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.

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

System capability: SystemCapability.Push.PushService

Since: 4.0.0(10)

Constraints

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

Modules to Import

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

Attributes

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

System capability: SystemCapability.Push.PushService

Since: 4.0.0(10)

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

onReceiveMessage

onReceiveMessage(payload: pushCommon.PushPayload): void

API for receiving the data of a background message that starts an app child process after the app inherits from PushExtensionAbility.

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

System capability: SystemCapability.Push.PushService

Since: 4.0.0(10)

Parameters:

Name Type Mandatory Description
payload pushCommon.PushPayload Yes Data of the background message for starting an app child process.

Example:

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

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

// In the following example, PushExtAbility inherits from PushExtensionAbility:
export default class PushExtAbility extends PushExtensionAbility {
  onReceiveMessage(payload: pushCommon.PushPayload): void {
    hilog.info(LOG_DOMAIN, LOG_TAG,'onReceiveMessage');

    try {
      this.updateData(payload.data);
    } catch (err) {
      const e: BusinessError = err as BusinessError;
      hilog.error(LOG_DOMAIN, LOG_TAG, 'updateData failed, code=%{public}d, message=%{public}s', e.code, e.message);
    }
  }

  /**
   * Data update.
   * You can customize the data update logic based on the transparently transmitted data.
   * @param data Transparently transmit data.
   */
  private updateData(data: string): void {
    // Implement the logic of updating data by yourself.
  }
}

onDestroy

onDestroy(): void

Callback triggered when the PushExtensionAbility is destroyed. You are advised to perform operations such as clearing resources in this method.

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

System capability: SystemCapability.Push.PushService

Since: 4.0.0(10)

Example:

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

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

// In the following example, PushExtAbility inherits from PushExtensionAbility:
export default class PushExtAbility extends PushExtensionAbility {
  onDestroy(): void {
    hilog.info(LOG_DOMAIN, LOG_TAG,'PushExtAbility 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

PushExtensionAbility 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