# Runtime SDK Spec

## 目標

定義 SDK 的部署、模式、payload 套用與追蹤邏輯，支援網站端實驗運行。

## SDK 雙模式

### Edit Mode

- 配合 editor 做選取與變更預覽
- 提供 overlay / bridge 事件

### Runtime Mode

- 正式流量分流
- 套用 payload 變更
- 回傳 impression / conversion 事件

## 部署拓撲

- 商家網站 -> 載入 SDK（CloudFront）
- SDK -> 呼叫 FastAPI Runtime API
- Origin 由自有 VPS 提供靜態檔

## 變更規則（DOM Change）

- change_type：replace_text / set_attribute / set_style / insert / remove / toggle_visibility
- selector 必須穩定可重建
- payload 必須可序列化與回放

## Assignment 與 Payload

- assignment 由 runtime API 決策
- payload 由 release 快照提供
- 套用前必須驗 selector 是否存在

## 事件策略

- FastAPI 先收事件，再依策略轉送 GA4/GTM
- 事件層次：audit event、runtime event、forwarded analytics event

## 風險與檢查

- CSP
- iframe / script injection
- DOM 穩定性
- style 汙染與 z-index 衝突
- cookie / storage 相容性