跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs.tinyinbox.co/llms.txt

Use this file to discover all available pages before exploring further.

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

​
何時使用

以下情況適合使用簽署身分：
  • 訪客已登入你的產品
  • 你想把回覆連到自己的使用者 ID
  • 你需要姓名或 email 由後端提供
如果只是公開行銷頁面，通常使用瀏覽器傳入的訪客資訊就足夠。

​
取得網站密鑰

在儀表板顯示該網站的 identity signing secret。請只把這個密鑰放在後端。 你也可以從 API 取得： 
GET /sites/{siteId}/security
Authorization: Bearer <user-session-token>

​
簽署 token

身分 token 必須：
  • 使用 HS256 演算法
  • 將 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 })
}

​
傳給小工具

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

window.TinyInbox.identify({ identityToken })
你也可以在 script 標籤中使用 data-tinyinbox-identity 屬性直接提供 token。

​
輪替密鑰

如果網站的 identity secret 外洩，請輪替密鑰。輪替後，請更新你的後端環境變數。 API 路由： 
POST /sites/{siteId}/security/rotate-identity-secret
Authorization: Bearer <user-session-token>
用舊密鑰簽署的身分 token 會在輪替後停止運作。