辨識已登入訪客

身分驗證讓你的後端告訴 TinyInbox 已登入訪客是誰。當你希望收件匣顯示可信任的姓名、email 或使用者 ID，而不是瀏覽器自行提供的資訊時，請使用這個方式。

何時使用

以下情況適合使用簽署身分：

訪客已登入你的產品
你想把回覆連到自己的使用者 ID
你需要姓名或 email 由後端提供

如果只是公開行銷頁面，通常使用瀏覽器傳入的訪客資訊就足夠。

取得網站密鑰

在儀表板建立該網站的第一組 identity signing secret。TinyInbox 只會顯示新的密鑰一次，因此離開頁面前請先複製到你的後端環境變數。你也可以從 API 建立或輪替：

POST /sites/{siteId}/security/rotate-identity-secret
Authorization: Bearer <user-session-token>

回應會包含新的 identitySecret，且只顯示這一次。既有密鑰不會再次回傳。

簽署 token

身分 token 必須：

使用 HS256 演算法
如果你的 JWT library 會設定 type header，請使用 typ: "JWT"。沒有 typ 的 token 可以接受，但其他 typ 值會被拒絕。
將 aud 設為 tinyinbox-widget-identity
包含 userId 或 sub
可選擇包含 name、email 和 siteKey
設定短時間過期

後端路由範例：

import { SignJWT } from "jose"

export async function GET() {
  const token = await new SignJWT({
    userId: user.id,
    name: user.name,
    email: user.email,
    siteKey: "tin_your_site_key",
  })
    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
    .setAudience("tinyinbox-widget-identity")
    .setExpirationTime("30m")
    .sign(new TextEncoder().encode(process.env.TINYINBOX_IDENTITY_SECRET))

  return Response.json({ identityToken: token })
}

傳給小工具

提供一個瀏覽器可呼叫、會回傳 { identityToken } 的 endpoint，然後從 client-only code 把這個 token 傳給 widget。請繼續使用 TinyInbox 儀表板複製出來的 widget script；不要在應用程式碼裡重新組合 widget URL 或 site key。如果你對已登入訪客使用 signed identity，不要再為同一位訪客呼叫 TinyInbox.identify({ name, email })。可信任的 name 和 email 應該放在 signed token 裡；兩種方式同時使用可能先建立匿名 session，接著又切換到 signed visitor session。對於已登入 app 頁面，請在 auth state 已知後取得 token，然後傳給 TinyInbox。如果這段程式碼可以在複製的 widget script 載入前執行，指令會先排入 queue，第一個 widget session 就會是 signed visitor。

const { identityToken } = await fetch("/api/tinyinbox/identity").then((res) =>
  res.json()
)

window.TinyInbox = window.TinyInbox || []
window.TinyInbox.push(["identify", { identityToken }])

如果你偏好明確等待 ready hook，或頁面在 auth state 確定前就已經安裝 widget script，則等 runtime ready 後傳入 token：

const { identityToken } = await fetch("/api/tinyinbox/identity").then((res) =>
  res.json()
)

function onTinyInboxReady(callback) {
  if (window.TinyInbox && window.TinyInbox.isReady) {
    callback(window.TinyInbox)
    return
  }

  window.addEventListener(
    "tinyinbox:ready",
    (event) => callback(event.detail),
    { once: true }
  )
}

onTinyInboxReady((TinyInbox) => {
  TinyInbox.identify({ identityToken })
})

你也可以在 script 標籤中使用 data-tinyinbox-identity 屬性直接提供 token。

輪替密鑰

如果網站的 identity secret 外洩，或你需要新的密鑰，請輪替密鑰。輪替後，請更新你的後端環境變數。 API 路由：

POST /sites/{siteId}/security/rotate-identity-secret
Authorization: Bearer <user-session-token>

用舊密鑰簽署的身分 token 會在輪替後停止運作。

開始使用

使用 TinyInbox

帳號

開發者

辨識已登入訪客

何時使用

取得網站密鑰

簽署 token

傳給小工具

輪替密鑰

​何時使用

​取得網站密鑰

​簽署 token

​傳給小工具

​輪替密鑰

何時使用

取得網站密鑰

簽署 token

傳給小工具

輪替密鑰