3個步驟輕鬆整合Push Kit，實現App訊息推送

推送通知作為App重要的訊息傳遞工具，廣泛應用於電子商務、社交媒體、旅遊交通等領域的通知場景。比如當應用有新功能或安全補丁時，系統將推送訊息提醒使用者及時更新；如果是航班出行類的應用，會傳送最新的班次時間表給使用者，以確保及時提醒。推送通知是App與使用者建立聯絡，保持信任和滿意度的重要方式，那麼App怎樣才能實現傳送通知訊息給使用者呢？

HarmonyOS SDK推送服務（Push Kit）是華為提供的訊息推送平臺，建立了從雲端到終端的訊息推送通道，透過整合推送服務，HarmonyOS應用就可以實現向使用者實時推送通知訊息。其顯示場景主要包括通知中心、鎖屏、橫幅、桌面圖示角標與通知圖示。

業務流程

實現推送通知訊息的業務流程包括申請並獲取Push Token、上報Token等資訊至應用服務端、傳送推送訊息請求、下發訊息到Push Kit和處理訊息5個步驟。

名詞解釋

在學習實現推送通知訊息的能力之前，我們先來學習幾個專有名詞。

Push Token：

Push Token標識了每臺裝置上的每個應用，開發者呼叫getToken()介面向Push Kit服務端請求Token，在獲取到Token後，需要使用Push Token來推送訊息。當在應用啟動時呼叫getToken()介面時，如果裝置的Token發生變化，開發者需要及時上報到應用伺服器更新Token。

Category：

通知訊息類別。為了改善終端使用者推送體驗，Push Kit對通知訊息進行分類管理，category的取值不同，標識的訊息型別則不同，不同的通知訊息型別影響訊息展示和提醒方式，開發者在推送訊息前，需先申請通知訊息自分類權益。

開發步驟

實現透過Push Kit推送通知訊息主要分為三個步驟，分別為獲取Push Token、告知使用者需要允許接收通知訊息、推送通知訊息。

1.獲取Push Token。

首先匯入pushService模組，建議在您的UIAbility（例如EntryAbility）的onCreate()方法中呼叫getToken()介面獲取Push Token並上報到您的服務端，方便您的服務端向終端推送訊息。

import { pushService } from '@kit.PushKit';
//匯入pushService模組。
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  // 入參 want 與 launchParam 並未使用，為初始化專案時自帶引數
  async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> {
    // 獲取Push Token
    try {
      const pushToken: string = await pushService.getToken();
      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);
    }
    // 上報Push Token並上報到您的服務端
  }
}

2.應用需要獲取使用者授權才能傳送通知，為確保應用可正常收到訊息，建議應用傳送通知前呼叫requestEnableNotification()方法，彈窗讓使用者選擇是否允許傳送通知。

import { notificationManager } from '@kit.NotificationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { common } from '@kit.AbilityKit';

const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00;

let context = getContext(this) as common.UIAbilityContext;
notificationManager.isNotificationEnabled().then((data: boolean) => {
  console.info("isNotificationEnabled success, data: " + JSON.stringify(data));
  if(!data){
    notificationManager.requestEnableNotification(context).then(() => {
      hilog.info(DOMAIN_NUMBER, TAG, `[ANS] requestEnableNotification success`);
    }).catch((err : BusinessError) => {
      if(1600004 == err.code){
        hilog.error(DOMAIN_NUMBER, TAG, `[ANS] requestEnableNotification refused, code is ${err.code}, message is ${err.message}`);
      } else {
        hilog.error(DOMAIN_NUMBER, TAG, `[ANS] requestEnableNotification failed, code is ${err.code}, message is ${err.message}`);
      }
    });
  }
}).catch((err : BusinessError) => {
    hilog.error(DOMAIN_NUMBER, TAG, `isNotificationEnabled fail: ${JSON.stringify(err)}`);
});

3.應用服務端呼叫Push Kit服務端的REST API推送通知訊息。

// Request URL
POST https://push-api.cloud.huawei.com/v3/[projectId]/messages:send

// Request Header
Content-Type: application/json
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
push-type: 0

// Request Body
{
  "payload": {
    "notification": {
      "category": "MARKETING",
      "title": "普通通知標題",
      "body": "普通通知內容",
      "clickAction": {
        "actionType": 0
        "data": {"testKey": "testValue"}
      },
      "notifyId": 12345
    }
  },
  "target": {
    "token": ["IQAAAA**********4Tw"]
  },
  "pushOptions": {
    "testMessage": true
  }
}

在推送通知訊息的這段示例程式碼中，projectId為專案ID，可登入AppGallery Connect網站，選擇"我的專案"，在專案列表中選擇對應的專案，左側導航欄選擇"專案設定"，在該頁面獲取；push-type為0表示通知訊息場景；actionType為0表示點選訊息開啟應用首頁。

此外，當actionType為1時，則代表點選訊息開啟應用內自定義頁面，如果要實現點選訊息開啟指定的應用內頁面，需要先設定待跳轉Ability的skills標籤中的actions或uris值。

設定actions引數完成點選訊息進入應用內頁的示例如下：

{
  "name": "TestAbility",
  "srcEntry": "./ets/abilities/TestAbility.ets",
  "exported": false,
  "startWindowIcon": "$media:icon",
  "startWindowBackground": "$color:start_window_background",
  "skills": [
    {
      "actions": [
        "com.test.action"
      ]
    }
  ]
}

如果要透過設定uris引數完成點選訊息進入應用內頁，skills中必須同時設定actions引數，且actions引數為空。

"skills": [
  {
    "actions": [""],
    "uris": [
      {
        "scheme": "https",
        "host": "www.xxxx.com",
        "port": "8080",
        "path": "push/test"
      }
    ]
  }
]

設定完skills標籤後，在傳送訊息時，clickAction中需攜帶data欄位並設定actionType欄位為1，則可實現點選訊息進入指定的應用內頁面。

// Request URL
POST https://push-api.cloud.huawei.com/v3/[projectId]/messages:send

// Request Header
Content-Type: application/json
Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
push-type: 0

// Request Body
{
  "payload": {
    "notification": {
      "category": "MARKETING",
      "title": "普通通知標題",
      "body": "普通通知內容",
      "clickAction": {
        "actionType": 1,
        "action": "com.test.action",
        "uri": "https://www.xxxx.com:8080/push/test",
        "data": {"testKey": "testValue"}
      }
    }
  },
  "target": {
    "token": ["IQAAAA**********4Tw"]
  },
  "pushOptions": {
    "testMessage": true
  }
}

其中需要注意的是，在獲取訊息中傳遞的data資料時，如果是點選訊息首次進入應用首頁或應用內頁，可以在onCreate()方法中獲取訊息data資料。

import { UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

export default class MainAbility extends UIAbility {
  onCreate(want: Want): void {
    // 獲取訊息中傳遞的data資料
    const data = want.parameters;
    hilog.info(0x0000, 'testTag', 'Succeeded in getting message data');
    // 根據實際業務場景對data進行處理
   }
}

如果當前應用程序存在時，點選訊息進入應用首頁或應用內頁，可以在onNewWant()方法中獲取訊息data資料，且onNewWant()方法僅在單例（singleton）模式下可用。

import { UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

export default class MainAbility extends UIAbility {
  onNewWant(want: Want): void {
    // 獲取訊息中傳遞的data資料
    const data = want.parameters;
    hilog.info(0x0000, 'testTag', 'Succeeded in getting message data');
    // 根據實際業務場景對data進行處理
  }
}

在實際開發過程中，以上兩種方式都需要注意到。在成功傳送訊息後，可以檢查裝置是否收到了通知訊息，至此，透過Push Kit傳送通知訊息的步驟就結束了。

在推送通知訊息時，還存在一種情況，那就是當推送的通知訊息有錯誤或者存在違規情況時，可能會引起使用者投訴或面臨監管風險。基於此，Push Kit還提供消了息撤回功能，以降低此類推送可能造成的影響。

需要注意的是，訊息撤回僅支援還未下發到端側的訊息，或者已在終端展示但使用者還未點選的訊息，並且僅支援使用Token和notifyId撤回。

在成功推送通知訊息後，如果需要撤回訊息，需要確保應用可正常收到通知訊息，並且在推送訊息時設定了notifyId欄位，這樣應用服務端就可以呼叫REST API撤回通知訊息了。

// Request URL 
POST https://push-api.cloud.huawei.com/v1/[clientId]/messages:revoke
 
// Request Header 
Content-Type:application/json
Authorization:Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
push-type: 0 
 
// Request Body 
{
  "notifyId": 1234567,
  "token": [
    "pushToken1",
    "pushToken2",
    "pushToken3"
  ]
}

這裡程式碼中的clientId需要替換為應用的Client ID，獲取方式與projectId一樣。notifyId作為訊息ID，是訊息的唯一標識。

透過以上步驟，我們就可以實現透過Push Kit推送和撤回普通通知訊息了，在此能力的基礎上，我們還可以繼續探索Push Kit的更多個性化服務能力，為應用的拉新促活創造更多可能性。

瞭解更多詳情>>

訪問推送服務聯盟官網

獲取推送通知訊息開發指導文件