仕様・API
分析イベント v0.1
step_view 閾値・dwell・バッチPOST。
分析イベント v0.1（確定）
方針
- 公開ビューアは 匿名
sessionIdのみ保持（ローカルストレージ等）。ログイン情報は送らない。 lpIdは公開ID。サーバ側で Workspace 等に解決する。- イベントは バッチ送信可能にし、オフライン時はキューして再送（ZIP/埋め込みとも実装可能な範囲で）。
共通エンベロープ（全イベント）
クライアントが生成する各レコードに含める。
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
eventId | string | ✓ | クライアント生成UUID。重複排除に使用。 |
name | string | ✓ | イベント名（下表）。 |
occurredAt | string | ✓ | ISO8601 UTC（Z）。 |
sessionId | string | ✓ | 端末単位の匿名ID。初回生成後に保存。 |
surface | string | ✓ | embed | zip | preview |
lpId | string | ✓ | LP定義の id。 |
revision | string | ✓ | LP定義の revision。 |
context | object | 任意。下記。 |
context（任意・共通）
| フィールド | 型 | 説明 |
|---|---|---|
userAgent | string | 短く切ってよい。 |
viewport | object | { w, h } ピクセル。 |
イベント別ペイロード
name 以外の追加フィールドは payload にネストする（実装はフラットでもよいが、意味の分離のため推奨）。
lp_view
LPが初めてユーザーに表示された（同一 sessionId で1回）。
payload フィールド | 型 | 必須 |
|---|---|---|
entry | string | |
utm_source | string | |
utm_medium | string | |
utm_campaign | string | |
utm_content | string | |
utm_term | string | |
ab_experiment_id | string | |
ab_variant | string |
entry の判定（viewer 実装）: ページ URL に utm_* が1つでもあれば utm、なければ direct。
step_view
ステップが「十分に見えた」と判定されたとき。初回のみ payload.firstInSession: true を付けてもよい。
payload フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
stepId | string | ✓ | |
stepIndex | number | ✓ | 0始まり。 |
visibilityRatio | number | ✓ | 0〜1。算出方法はランタイムで定義。 |
firstInSession | boolean | 省略時は false 扱い。 |
閾値（確定）: visibilityRatio >= 0.5 が 連続100ms 維持されたときに1回発火。同じステップに再入した場合は再度発火してよい（eventId で区別）。
step_dwell
ステップが上記閾値以上で表示されていた時間を、ステップを離れるときに送る。
payload フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
stepId | string | ✓ | |
stepIndex | number | ✓ | |
durationMs | integer | ✓ | 閾値以上だったミリ秒。 |
cta_click
payload フィールド | 型 | 必須 |
|---|---|---|
stepId | string | ✓ |
stepIndex | number | ✓ |
popup_cta_click
meta.popupCta のフローティングボタンタップ。クリック時点で表示中のステップを記録する。
payload フィールド | 型 | 必須 |
|---|---|---|
stepId | string | ✓ |
stepIndex | number | ✓ |
hotspot_click
payload フィールド | 型 | 必須 |
|---|---|---|
stepId | string | ✓ |
stepIndex | number | ✓ |
hotspotId | string | ✓ |
step_tap
スライドのメディア領域をタップした位置（ホットスポット・CTA ボタン以外）。ヒートマップ集計用。
payload フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
stepId | string | ✓ | |
stepIndex | number | ✓ | 0始まり |
x | number | ✓ | メディア領域内の正規化 X（0〜1） |
y | number | ✓ | メディア領域内の正規化 Y（0〜1） |
集計 API は 20×20 グリッドにバケット化して heatmap として返す（管理 UI のタップヒートマップ）。
swipe_next / swipe_prev
payload フィールド | 型 | 必須 |
|---|---|---|
fromStepId | string | ✓ |
fromIndex | number | ✓ |
toStepId | string | ✓ |
toIndex | number | ✓ |
direction | string | ✓ |
動画（type: video ステップ）
name | payload 必須フィールド |
|---|---|
video_play | stepId, stepIndex |
video_progress | stepId, stepIndex, percent（25 | 50 | 75） |
video_complete | stepId, stepIndex |
送信API（クライアント向け）
- HTTP:
POST /v1/analytics/events - Body:
{ "events": [ { ...上記エンベロープ＋payload... } ] } - 上限: 1リクエスト 最大100件。超える場合は分割。
- 認証: 公開エンドポイントは 公開LP用の計測キー（ヘッダ
X-SwipeLP-Key）を付与。キーはLP公開時に発行し、サーバでlpIdと紐づけて検証（詳細はAPI実装で定義）。
埋め込み・ZIPからの apiBase・キー・定義取得URL は embed-and-zip-v0.1.md を正とする。HTTPステータス・キー検証は api-v0.1.md。
ダッシュボードMVPで見せる指標（確定）
- LPあたり: ユニーク
sessionId数（lp_viewベース） - ステップあたり:
step_view数、step_dwell平均・合計 - コンバージョン寄り:
cta_click+hotspot_click数
リクエスト例
{
"events": [
{
"eventId": "550e8400-e29b-41d4-a716-446655440000",
"name": "step_view",
"occurredAt": "2026-04-15T12:00:00.000Z",
"sessionId": "anon_sess_ulid_or_uuid",
"surface": "embed",
"lpId": "01JRQEXAMPLELPID00",
"revision": "1",
"payload": {
"stepId": "01JRQEXAMPLESTEP01",
"stepIndex": 0,
"visibilityRatio": 0.62,
"firstInSession": true
}
}
]
}
payload をトップレベルとフラット結合する実装でもよいが、名前空間の衝突を避けるため payload ネストを推奨する。