網頁掛件

程式碼中的 window.SingChat 等是掛件與 API 的技術名稱，請原樣保留。

網站聊天視窗就是一個 script：widget.js，由 askais.com 提供。它會在你的頁面上加入聊天按鈕，並在 Shadow DOM 裡繪製聊天視窗，所以你網站的樣式和聊天視窗的樣式互不影響。

加到你的網站

把這段程式碼貼到每個需要顯示聊天的頁面的 </body> 之前。App ID 在設定 → 收件匣與聊天框外觀裡。

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  async></script>

在你自己的網站上，data-base-url 是必填的：少了它，聊天視窗會到你的網域上找它的伺服器，而不是到 askais.com。

⚠️ 從 askais.com 載入 widget.js

不要下載 widget.js，也不要把它打包進你自己的程式碼。從 askais.com 載入，它一律執行目前的版本；複製下來的副本會停在當時的版本，之後的每一個修正和新功能都用不到。

Script 屬性

所有設定都透過 script 標籤上的 data- 屬性完成：

• data-app-id — 必填。你的收件匣的 App ID。
• data-base-url — 在你的網站上必填。固定為 https://askais.com。
• data-locale — 選填。強制指定聊天視窗的語言，例如 ja 或 zh-Hant。不填時，聊天視窗會依照訪客裝置的語言，其次是你頁面的 lang。
• data-external-id — 已登入使用者在你系統裡的 ID。
• data-email — 使用者的 Email，會顯示給你的團隊。
• data-name — 使用者的名字，會顯示給你的團隊。
• data-avatar-url — 使用者大頭貼的連結。
• data-hmac — 身分簽章，見下文。
• data-attrs — 以 JSON 表示的額外資料，例如 {"plan":"Pro"}，會顯示在訪客資料裡給你的團隊看。無效的 JSON 會被忽略。

data-embed、data-platform、data-app-version 和 data-device-model 由 App 內聊天頁面設定。 請參閱「App 內聊天（WebView）」。

已登入訪客

對於已登入的使用者，把他們的資料加到 script 標籤上。你的團隊能看到在跟誰對話，對話也會跟著使用者到其他裝置上：

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  data-external-id="user_123"
  data-email="ada@example.com"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

沒有 data-external-id 時，聊天視窗會給每個瀏覽器一個自己的匿名 ID，存放在瀏覽器的本機儲存空間裡，所以在這個瀏覽器裡重新整理頁面後，聊天紀錄仍會保留。如果收件匣設有 Pre-chat 表單，匿名訪客要先填寫表單才能開始聊天。

身分驗證（HMAC）

• hmac 是以收件匣密鑰為 key、對 externalId 計算出的 HMAC-SHA256，以小寫十六進位表示。
• 在你的伺服器上計算。密鑰絕對不能放進網頁或 App。
• 密鑰在建立收件匣時顯示一次，在設定 → 收件匣與聊天框外觀裡輪換時（該收件匣的 ⋮ 選單 → 輪換密鑰）會再顯示一次。要用整串密鑰，包含 sk_ 前綴。輪換後，所有舊簽章都會失效。
• data-external-id 一定要和 data-hmac 一起傳送，而且簽的就是這個值。聊天視窗一定會帶 external ID（你不傳它會自己產生匿名的），所以只對 Email 簽章永遠驗證不了任何人。
• 簽章錯了或沒帶，都不會擋住聊天：訪客照樣能跟你聊，只是被當成「未驗證」。未驗證的資料會照頁面提供的內容直接採用，所以任何能修改頁面的人都可以冒充別人；除非你打開「必須驗證身分」，未驗證的訪客就會被當成匿名訪客，看不到以前的對話。

Node.js 範例：

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

用 JavaScript 啟動聊天視窗

如果要自己啟動聊天視窗，例如等頁面確認使用者是誰之後再啟動，就在載入 script 時不帶 data-app-id，並在 script 載入完成後呼叫 window.SingChat.start()：

<script src="https://askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "ada@example.com",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

start() 是 script 提供的唯一方法。沒有用來開啟、關閉或監聽聊天視窗的方法；訪客會從聊天按鈕開啟它。

外觀與行為

• 設定 → 收件匣與聊天框外觀，再展開某個收件匣：主色和文字顏色、位置（右下或左下）、泡泡大小、淺色或深色背景、視窗標題和副標題，並有即時預覽。
• Pre-chat 表單（同一處）：在開始聊天前，請匿名訪客填寫 Email、姓名、電話或公司。
• 允許的網域（同一處）：可以載入這個收件匣聊天視窗的網站。清單為空時允許任何網站。
• 品牌署名（同一處）：聊天視窗底部的「Powered by」字樣。能否隱藏它，或在那裡顯示你自己的名稱，取決於你的方案。
• AI 歡迎訊息在 AI 助理裡設定，可點選的 FAQ 泡泡在設定 → 常見問題裡設定，文章在幫助中心裡設定。

安全性

• App ID 是公開的，放在 HTML 裡很安全。
• 收件匣密鑰只能放在你的伺服器上。
• 只要頁面知道使用者是誰，就使用身分驗證（HMAC）。
• 在「允許的網域」裡只填你自己的網域，這樣聊天視窗就無法在其他網站上載入。