目录

Obtaining a Push Token

Use Cases

Push Kit will verify your relevant permissions when you obtain a push token. Before obtaining a push token, complete configurations described in Enabling Push Kit.

A push token identifies an app on a user device. You can call the getToken API to request a push token from the Push Kit server and use the token to push messages.

Generally, the push token changes and the previous token becomes invalid only in the following scenarios:

Therefore, you are advised to call the getToken API when your app is launched to check the push token. If the push token of the device changes, report the change to your app server in a timely manner to prevent message receiving failure due to the invalid push token.

Constraints

The capability of obtaining a push token is supported on phones, tablets, and PCs/2-in-1 devices. Support for wearables is available starting from 5.1.0(18), and for TVs starting from 5.1.1(19).

Precautions

API Description

The APIs use either a callback or promise to return the result. The table below lists only the APIs that use a promise. The APIs that use a callback provide the same functions as their counterparts that use a promise.

API Description
getToken(): Promise<string> Obtains a push token and returns it using a promise.
deleteToken(): Promise<void> Deletes a push token and returns the result using a promise.

Obtaining a Push Token

  1. Push Kit will verify your relevant permissions when you obtain a push token. Before obtaining a push token, complete configurations described in Enabling Push Kit.

  2. Import the pushService module and related common modules.

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

  3. You are advised to call the getToken API in the onCreate() method of your UIAbility (for example, EntryAbility) to obtain the push token and report it to your app server so that your server can push messages to devices. The sample code is as follows:

    const DOMAIN = 0x0000;

export default class EntryAbility extends UIAbility {
  // ...
  // The input parameters want and launchParam are not actually used. They are defined during project initialization.
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // ...
    // Obtain a push token.
    pushService.getToken().then(token => {
      hilog.info(DOMAIN, 'testTag', 'Succeeded in getting push token.');
      // Report the obtained push token to the server.
    }).catch((err: BusinessError) => {
      hilog.error(DOMAIN, 'testTag', 'Failed to get push token: %{public}d %{public}s', err.code, err.message);
    });
  }
  // ...
}

If the app authentication fails (error code 1000900010 is reported) when you obtain a push token, rectify the error by referring to ArkTS API Error Codes.

Deleting a Push Token

After a push token is deleted, all historical Push Kit data of the app will also be deleted. Call the deleteToken API only when necessary.

  1. Import the pushService module and related common modules.

    import { pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
const DOMAIN = 0x0000;

  2. Call the deleteToken API to delete the push token. The sample code is as follows:

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

Implementing Push Token Update Callback

The push token update callback capability is supported on wearables. Starting from version 6.1.0(23), it is also supported on phones, tablets, and PCs/2-in-1 devices.

When a device leaves a country or region, the push token may be automatically updated. If your app needs to detect the push token update event, call the on() method to register the callback. To deregister the callback so your app can stop receiving push token update events, call the off() method.

  1. Import the pushService module and related common modules.

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

  2. Call the pushService.on() method in the ability (PushMessageAbility is used as an example) of your project to receive token update messages. Note that you can only use UIAbility to receive token update messages. The sample code is as follows:

    const DOMAIN = 0x0000;

export default class PushMessageAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // ...
    const callBack = (data: string) => {
      try {
        hilog.info(DOMAIN, 'testTag', 'update token: %{public}s', data);
      } catch (e) {
        let err: BusinessError = e as BusinessError;
        hilog.error(DOMAIN, 'testTag', 'Failed to update data: %{public}d %{public}s', err.code, err.message);
      }
    }

    try {
      // Register a token update callback.
      pushService.on('tokenUpdate', this, callBack);
      hilog.info(DOMAIN, 'testTag', 'Register on success');
    } catch (e) {
      let err: BusinessError = e as BusinessError;
      hilog.error(DOMAIN, 'testTag', 'Register on error: %{public}d %{public}s', err.code, err.message);
    }
  }

  onDestroy(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'PushMessageAbility onDestroy');

    try {
      // Deregister a token update callback.
      pushService.off('tokenUpdate');
      hilog.info(DOMAIN, 'testTag', 'Register off success');
    } catch (e) {
      let err: BusinessError = e as BusinessError;
      hilog.error(DOMAIN, 'testTag', 'Register off error: %{public}d %{public}s', err.code, err.message);
    }
  }
  // ...
}

  3. Set actions to action.ohos.push.listener in skills in the abilities section of the src/main/module.json5 file at the project level. (This action can be defined for only one ability. If the uris parameter also exists, it should be left empty.)

    {
  "name": "PushMessageAbility",
  "srcEntry": "./ets/abilities/PushMessageAbility.ets",
  "description": "$string:PushMessageAbility_desc",
  "icon": "$media:layered_image",
  "label": "$string:PushMessageAbility_label",
  "startWindowIcon": "$media:startIcon",
  "startWindowBackground": "$color:start_window_background",
  "launchType": "singleton",
  "exported": false,
  "skills": [
    // Keep the existing skill object unchanged.
    {
      "actions": [
        "com.app.action"
      ]
    },
    // Add an independent skill object and set the actions parameter.
    {
      "actions": [
        "action.ohos.push.listener"
      ]
    }
  ]
// ...
}