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

HarmonyOS_SDK發表於2024-10-10

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

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

image

業務流程

image

實現推送通知訊息的業務流程包括申請並獲取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的更多個性化服務能力,為應用的拉新促活創造更多可能性。

瞭解更多詳情>>

訪問推送服務聯盟官網

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

相關文章