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)
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. |
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);
} 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. |
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);
} 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. |
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);
} 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. |
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);
} 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);
} 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. |
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);
} 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);
} 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);
} 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:
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 | 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);
}
}
}