目录

pushService

This module provides basic capabilities of Push Kit, including obtaining and deleting push tokens, binding and unbinding accounts, and receiving scenario-specific messages.

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

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Push.PushService

Start version: 4.0.0(10)

Module Import

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

pushService.getToken

getToken(callback: AsyncCallback<string>): void

Obtains a push token. This API returns the result asynchronously through a callback.

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

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Push.PushService

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Optional

Description

callback

AsyncCallback<string>

No

Callback function. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

1000900001

System internal error.

1000900008

Failed to connect to the push service.

1000900009

Internal error of the push service.

1000900010

Illegal application identity.

1000900011

The network is unavailable.

1000900012

Push rights are not activated.

1000900013

Cross-location application is not allowed to obtain the token.

1000900014

The device does not support getting token.

Example:
import { pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  pushService.getToken((err: BusinessError, data: string) => {
    if (err) {
      hilog.error(0x0000, 'testTag', 'Failed to get push token: %{public}d %{public}s', err.code, err.message);
    } else {
      hilog.info(0x0000, 'testTag', 'Succeeded in getting push token');
    }
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, 'testTag', 'Failed to get push token: %{public}d %{public}s', e.code, e.message);
}

pushService.getToken

getToken(): Promise<string>

Obtains a push token. This API returns the result asynchronously through a promise.

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

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Push.PushService

Start version: 4.0.0(10)

Returns:

Type

Description

Promise<string>

Token returned through a promise.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

1000900001

System internal error.

1000900008

Failed to connect to the push service.

1000900009

Internal error of the push service.

1000900010

Illegal application identity.

1000900011

The network is unavailable.

1000900012

Push rights are not activated.

1000900013

Cross-location application is not allowed to obtain the token.

1000900014

The device does not support getting token.

Example:
import { pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  pushService.getToken().then((data: string) => {
    hilog.info(0x0000, 'testTag', 'Succeeded in getting push token.');
  }).catch((err: BusinessError) => {
    hilog.error(0x0000, 'testTag', 'Failed to get push token: %{public}d %{public}s', err.code, err.message);
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, 'testTag', 'Failed to get push token: %{public}d %{public}s', e.code, e.message);
}

pushService.deleteToken

deleteToken(callback: AsyncCallback<void>): void

Deletes a push token. This API returns the result asynchronously through a callback.

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

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Push.PushService

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Optional

Description

callback

AsyncCallback<void>

No

Callback function. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

1000900001

System internal error.

1000900008

Failed to connect to the push service.

1000900009

Internal error of the push service.

1000900010

Illegal application identity.

1000900011

The network is unavailable.

Example:
import { pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  pushService.deleteToken((err: BusinessError) => {
    if (err) {
      hilog.error(0x0000, 'testTag', 'Failed to delete push token: %{public}d %{public}s', err.code, err.message);
    } else {
      hilog.info(0x0000, 'testTag', 'Succeeded in deleting push token.');
    }
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, 'testTag', 'Failed to delete push token: %{public}d %{public}s', e.code, e.message);
}

pushService.deleteToken

deleteToken(): Promise<void>

Deletes a push token. This API returns the result asynchronously through a promise.

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

Atomic service API: This API can be used in atomic services since API version 5.0.0(12).

System capability: SystemCapability.Push.PushService

Start version: 4.0.0(10)

Returns:

Type

Description

Promise<void>

Promise object. No result is returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

1000900001

System internal error.

1000900008

Failed to connect to the push service.

1000900009

Internal error of the push service.

1000900010

Illegal application identity.

1000900011

The network is unavailable.

Example:
import { pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  pushService.deleteToken().then(() => {
    hilog.info(0x0000, 'testTag', 'Succeeded in deleting push token.');
  }).catch((err: BusinessError) => {
    hilog.error(0x0000, 'testTag', 'Failed to delete push token: %{public}d %{public}s', err.code, err.message);
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, 'testTag', 'Failed to delete push token: %{public}d %{public}s', e.code, e.message);
}

pushService.bindAppProfileId

bindAppProfileId(appProfileType: pushCommon.AppProfileType, appProfileId: string, callback: AsyncCallback<void>): void

Binds the anonymous identifier of an app account. This API returns the result asynchronously through a callback.

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

System capability: SystemCapability.Push.PushService

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Optional

Description

appProfileType

pushCommon.AppProfileType

No

Bound account type, which can be HUAWEI ID or an account in the app's own account system.

appProfileId

string

No

Anonymous identifier of an account. The value cannot be an empty string. You are not advised to use the actual account ID as appProfileId. Generate an anonymous identifier that can uniquely map to the account ID. There is no restriction on the generation algorithm.

callback

AsyncCallback<void>

No

Callback function. If the operation is successful, err is null; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

1000900001

System internal error.

1000900008

Failed to connect to the push service.

1000900009

Internal error of the push service.

1000900010

Illegal application identity.

1000900015

The number of bound profile-app relationships exceeds the maximum.

1000900016

The os distributed account is not logged in.

Example:

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

// Define the profileId to be bound.
const profileId: string = '1****9';
try {
  pushService.bindAppProfileId(pushCommon.AppProfileType.PROFILE_TYPE_APPLICATION_ACCOUNT, profileId, (err: BusinessError) => {
    if (err) {
      hilog.error(0x0000, 'testTag', 'Failed to bind app profile id: %{public}d %{public}s', err.code, err.message);
    } else {
      hilog.info(0x0000, 'testTag', 'Succeeded in binding app profile id.');
    }
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, 'testTag', 'Failed to bind app profile id: %{public}d %{public}s', e.code, e.message);
}

pushService.bindAppProfileId

bindAppProfileId(appProfileType: pushCommon.AppProfileType, appProfileId: string): Promise<void>

Binds the anonymous identifier of an app account. This API returns the result asynchronously through a promise.

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

System capability: SystemCapability.Push.PushService

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Optional

Description

appProfileType

pushCommon.AppProfileType

No

Bound account type, which can be HUAWEI ID or an account in the app's own account system.

appProfileId

string

No

Anonymous identifier of an account. The value cannot be an empty string. You are not advised to use the actual account ID as appProfileId. Generate an anonymous identifier that can uniquely map to the account ID. There is no restriction on the generation algorithm.

Returns:

Type

Description

Promise<void>

Promise object. No result is returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

1000900001

System internal error.

1000900008

Failed to connect to the push service.

1000900009

Internal error of the push service.

1000900010

Illegal application identity.

1000900015

The number of bound profile-app relationships exceeds the maximum.

1000900016

The os distributed account is not logged in.

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

// Define the profileId to be bound.
const profileId = '1****9';
try {
  // Bind the app account.
  pushService.bindAppProfileId(pushCommon.AppProfileType.PROFILE_TYPE_APPLICATION_ACCOUNT, profileId).then(() => {
    hilog.info(0x0000, 'testTag', 'Succeeded in binding app profile id.');
  }).catch((err: BusinessError) => {
    hilog.error(0x0000, 'testTag', 'Failed to bind app profile id: %{public}d %{public}s', err.code, err.message);
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, 'testTag', 'Failed to bind app profile id: %{public}d %{public}s', e.code, e.message);
}

pushService.unbindAppProfileId

unbindAppProfileId(appProfileId: string, callback: AsyncCallback<void>): void

Unbinds the anonymous identifier of an app account. This API returns the result asynchronously through a callback.

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

System capability: SystemCapability.Push.PushService

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Optional

Description

appProfileId

string

No

Anonymous identifier of an account. Set this parameter to the value of appProfileId specified in the bindAppProfileId() call.

callback

AsyncCallback<void>

No

Callback function. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

1000900001

System internal error.

1000900008

Failed to connect to the push service.

1000900009

Internal error of the push service.

1000900010

Illegal application identity.

Example:

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

// Define the profileId to be unbound.
const profileId: string = '1****9';
try {
  pushService.unbindAppProfileId(profileId, (err: BusinessError) => {
    if (err) {
      hilog.error(0x0000, 'testTag', 'Failed to unbind app profile id: %{public}d %{public}s', err.code, err.message);
    } else {
      hilog.info(0x0000, 'testTag', 'Succeeded in unbinding app profile id.');
    }
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, 'testTag', 'Failed to unbind app profile id: %{public}d %{public}s', e.code, e.message);
}

pushService.unbindAppProfileId

unbindAppProfileId(appProfileId: string): Promise<void>

Unbinds the anonymous identifier of an app account. This API returns the result asynchronously through a promise.

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

System capability: SystemCapability.Push.PushService

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Optional

Description

appProfileId

string

No

Anonymous identifier of an account. Set this parameter to the value of appProfileId specified in the bindAppProfileId() call.

Returns:

Type

Description

Promise<void>

Promise object. No result is returned.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

1000900001

System internal error.

1000900008

Failed to connect to the push service.

1000900009

Internal error of the push service.

1000900010

Illegal application identity.

Example:

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

// Define the profileId to be unbound.
const profileId: string = '1****9';
try {
  pushService.unbindAppProfileId(profileId).then(() => {
    hilog.info(0x0000, 'testTag', 'Succeeded in unbinding app profile id.');
  }).catch((err: BusinessError) => {
    hilog.error(0x0000, 'testTag', 'Failed to unbind app profile id: %{public}d %{public}s', err.code, err.message);
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  hilog.error(0x0000, 'testTag', 'Failed to unbind app profile id: %{public}d %{public}s', e.code, e.message);
}

pushService.receiveMessage

receiveMessage(pushType: 'IM' | 'VoIP' | 'BACKGROUND' | 'EMERGENCY', ability: Ability, onMessage: Callback<pushCommon.PushPayload>): void

Receives scenario-specific messages from Push Kit.

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

System capability: SystemCapability.Push.PushService

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Optional

Description

pushType

'IM' | 'VoIP' | 'BACKGROUND' | 'EMERGENCY'

No

Scenario-specific message type. The options are as follows:

  • IM: extended notification message
  • VoIP: in-app call message
  • BACKGROUND: background message
  • EMERGENCY: emergency event message
NOTE:

The EMERGENCY value is provided since API version 5.0.0(12). It is only used in special scenarios such as earthquakes. Currently, this value is in the beta test phase and not open for application. Please stay tuned for future updates.

ability

Ability

No

UIAbility.

onMessage

Callback<pushCommon.PushPayload>

No

Callback function, which returns the scenario-specific message data.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

Error Code

Error Message

401

Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

1000900001

System internal error.

1000900005

Messages of the same push type cannot be received repeatedly.

Example:

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

// You do not need to add a UIAbility. You can call the API in the onCreate method of the original UIAbility. Here, PushMessageAbility is used as an example.
export default class PushMessageAbility extends UIAbility {
  // The onCreate() API returns the result synchronously and does not support asynchronous callback.
  onCreate(): void {
    try {
      // The receiveMessage() method cannot be called immediately after an asynchronous method, as this may affect message reception.
      // Register the BACKGROUND scenario-specific message.
      pushService.receiveMessage('BACKGROUND', this, (data: pushCommon.PushPayload) => {
        // Process the message. You are advised to add a try-catch block for the callback.
        try {
          hilog.info(0x0000, 'testTag', 'Receive background message : %{public}s', JSON.stringify(data));
        } catch (e) {
          let errRes: BusinessError = e as BusinessError;
          hilog.error(0x0000, 'testTag', 'Failed to process data: %{public}d %{public}s', errRes.code, errRes.message);
        }
      });
    } catch (err) {
      let e: BusinessError = err as BusinessError;
      hilog.error(0x0000, 'testTag', 'Failed to receive message: %{public}d %{public}s', e.code, e.message);
    }
  }
}