通知服務 | ArcBlock

通知服務是 Blocklet SDK 的核心元件，讓您的應用程式能夠傳送各種類型的通知給使用者，並訂閱即時事件。此服務作為底層 ABT Node 通知功能的介面，處理從簡單的使用者訊息到傳送到 DID 錢包、電子郵件和其他管道的豐富互動式通知等所有事務。

無論您需要提醒使用者重要事件、傳送交易性電子郵件，或是向所有已連線的客戶端廣播訊息，通知服務都提供了一個統一且直接的 API。

Notification Service

API 參考

sendToUser

直接向一個或多個由其 DID 標識的使用者傳送通知。這是針對性使用者通訊的主要方法。

參數

receiver string | string[] (required) — 接收者的 DID。可以是一個 DID 字串、一個 DID 陣列，或使用 * 傳送給該 blocklet 的所有使用者。
notification TNotification | TNotification[] (required) — 要傳送的通知物件或通知物件陣列。詳細結構請參閱通知物件 (TNotification) 章節。
options TSendOptions — 傳送通知的額外選項。
- keepForOfflineUser boolean — 若為 true，通知將被儲存並在使用者上線時傳送。
- locale string — 通知的地區設定（例如：'en'、'zh'）。
- channels ('app' | 'email' | 'push' | 'webhook')[] — 指定透過哪些管道傳送通知。
- ttl number — 訊息的存活時間，單位為分鐘（0-7200）。超過此時間後，訊息將過期。
- allowUnsubscribe boolean — 若為 true，則允許使用者取消訂閱此類型的通知。

回傳值

Promise Promise — 一個 promise，成功傳送後會解析並回傳伺服器的回應物件。

範例

Send a simple notification

import notification from '@blocklet/sdk/service/notification';

async function notifyUser(userDid) {
  try {
    const result = await notification.sendToUser(userDid, {
      type: 'notification',
      title: 'Hello from SDK!',
      body: 'This is a test notification sent to a specific user.',
      severity: 'info',
    });
    console.log('通知傳送成功：', result);
  } catch (error) {
    console.error('傳送通知失敗：', error);
  }
}

範例回應

{
  "status": "ok",
  "message": "通知已傳送給 1 位使用者。"
}

sendToMail

透過電子郵件向一個或多個接收者傳送通知。通知物件的結構與 sendToUser 相同。

參數

receiver string | string[] (required) — 單一電子郵件地址或電子郵件地址陣列。
notification TNotification (required) — 通知物件。title 用作電子郵件主旨，body 或 attachments 構成電子郵件內容。
options TSendOptions — 與 sendToUser 相同的傳送選項。

回傳值

Promise Promise — 一個 promise，會解析並回傳伺服器的回應物件。

範例

Send an email notification

import notification from '@blocklet/sdk/service/notification';

async function emailUser(userEmail) {
  try {
    const result = await notification.sendToMail(userEmail, {
      type: 'notification',
      title: 'Your Weekly Report is Ready',
      body: 'Please log in to your dashboard to view the report.',
    });
    console.log('電子郵件傳送成功：', result);
  } catch (error) {
    console.error('傳送電子郵件失敗：', error);
  }
}

範例回應

{
  "status": "ok",
  "message": "電子郵件傳送成功。"
}

broadcast

向連接到特定 WebSocket 頻道的客戶端廣播訊息。預設情況下，它會傳送到 blocklet 的公共頻道。

參數

notification TNotificationInput (required) — 要廣播的通知物件。
options object — 控制廣播的選項。
- channel string — 要廣播到的頻道。預設為 blocklet 的公共頻道，可透過 getAppPublicChannel(did) 取得。
- event string (default: message) — 在客戶端觸發的事件名稱。
- socketId string — 若提供，則僅將訊息傳送至此特定的 socket 連線。
- userDid string — 若提供，則僅將訊息傳送至使用此 DID 驗證的 socket。

回傳值

Promise Promise — 一個 promise，會解析並回傳伺服器的回應。

範例

Broadcast a message

import notification from '@blocklet/sdk/service/notification';

function broadcastUpdate() {
  notification.broadcast(
    {
      type: 'passthrough',
      passthroughType: 'system_update',
      data: { message: 'A new version is available. Please refresh.' },
    },
    { event: 'system-update' }
  );
}

範例回應

{
  "status": "ok",
  "message": "廣播已傳送。"
}

sendToRelay

透過中繼服務將訊息傳送到特定主題，從而實現不同元件甚至不同 blocklet 之間的即時、基於主題的通訊。

參數

topic string (required) — 要發佈事件的主題。
event string (required) — 正在傳送的事件名稱。
data any (required) — 事件的負載資料。

回傳值

Promise Promise — 一個 promise，會解析並回傳伺服器的回應。

範例

Send a relay message

import notification from '@blocklet/sdk/service/notification';

async function publishNewArticle(article) {
  try {
    await notification.sendToRelay('articles', 'new-published', {
      id: article.id,
      title: article.title,
    });
    console.log('中繼訊息已傳送。');
  } catch (error) {
    console.error('傳送中繼訊息失敗：', error);
  }
}

範例回應

{
  "status": "ok",
  "message": "中繼訊息已傳送。"
}

on

訂閱從 ABT Node 推播的一般事件，例如內部 blocklet 事件或團隊相關事件。通知服務為此功能使用 EventEmitter 介面。

參數

event string (required) — 要監聽的事件名稱。
callback Function (required) — 事件觸發時要執行的函式。

範例

Listen for team member removal

import notification from '@blocklet/sdk/service/notification';
import { TeamEvents } from '@blocklet/constant';

function onMemberRemoved(data) {
  console.log('Team member removed:', data.user.did);
  // 新增更新應用程式狀態的邏輯
}

// 訂閱事件
notification.on(TeamEvents.MEMBER_REMOVED, onMemberRemoved);

off

移除先前用 on 新增的事件監聽器。

參數

event string (required) — 要停止監聽的事件名稱。
callback Function (required) — 要移除的特定監聽器函式。

範例

// 若要取消訂閱前一個範例
// notification.off(TeamEvents.MEMBER_REMOVED, onMemberRemoved);

_message.on

這是一個特殊用途的監聽器，專門用於直接傳送到您 blocklet 私人訊息頻道的訊息。它對於處理針對 blocklet 本身的直接回應或命令很有用。

參數

event string (required) — 要監聽的傳入訊息的 type。
callback Function (required) — 收到指定類型訊息時要執行的函式。

範例

Listen for direct messages

import notification from '@blocklet/sdk/service/notification';

function handleDirectMessage(response) {
  console.log('Received direct message:', response);
}

// 來自 messageChannel 的 'message' 事件會以 response.type 作為事件名稱來觸發
// 例如，如果 response.type 是 'payment_confirmation'，這裡的事件就是 'payment_confirmation'
notification._message.on('payment_confirmation', handleDirectMessage);

_message.off

移除先前用 _message.on 新增的直接訊息監聽器。

參數

event string (required) — 要停止監聽的訊息類型。
callback Function (required) — 要移除的特定監聽器函式。

通知物件 (TNotification)

通知物件是一個彈性的資料結構，定義了通知的內容和外觀。其結構可以針對不同的使用案例進行客製化。

type 'notification' | 'connect' | 'feed' | 'hi' | 'passthrough' (required) — 通知的主要類型，它決定了其整體目的和結構。
title string — 通知的標題。用於 notification 類型。
body string — 通知的主要內容/本文。用於 notification 類型。
severity 'normal' | 'success' | 'error' | 'warning' — 嚴重性級別，會影響通知在錢包中的外觀。用於 notification 類型。
attachments TNotificationAttachment[] — 一個富內容附件陣列。這些附件會在 DID 錢包中以區塊形式呈現。
- type string (required) — 附件的類型。可以是 asset、vc、token、text、image、divider、transaction、dapp、link 或 section。
- data object — 附件的資料負載，會因類型而異（例如，text 附件在這裡會有一個 text 屬性）。
actions TNotificationAction[] — 一個要與通知一起顯示的動作按鈕陣列。
- name string (required) — 動作的識別碼。
- title string — 按鈕上顯示的文字。
- link string — 點擊按鈕時要開啟的 URL。
activity TNotificationActivity — 一個描述社交活動的物件，例如評論或追蹤。這是表示社交互動的一種結構化方式。
- type 'comment' | 'like' | 'follow' | 'tips' | 'mention' | 'assign' | 'un_assign' (required) — 活動類型。
- actor string (required) — 執行此動作的使用者的 DID。
- target TActivityTarget (required) — 執行動作的目標物件（例如，一篇部落格文章）。
url string — connect 類型為必填。DID Connect 會話的 URL。
checkUrl string — connect 類型為選填。一個用於檢查會話狀態的 URL。
feedType string — feed 類型為必填。一個用於識別 feed 類型的字串。
passthroughType string — passthrough 類型為必填。一個用於識別 passthrough 資料類型的字串。
data object — feed 和 passthrough 類型為必填。這些類型的資料負載。