Skip to Content
開發者計畫互動體驗（Interaction）

互動體驗（Interaction）開發

互動體驗 是品牌可在公開頁提供給訪客的互動內容，目前支援 4 種類型：

類型key說明
心理測驗quiz多題選項 → 結算結果
抽獎轉盤wheel轉盤機率抽獎，支援獎品庫存
大頭貼製造器avatar分層可選配件，匯出圖片
數位導覽手冊guide節點式多頁導覽

Feature flag key：interaction。

範本位置

hypelink-theme/
└── interaction/
    └── hypelink-interaction-template/   ← 官方互動體驗範本

目前 quiz（心理測驗） 已實作完整範本；其餘 wheel、avatar、guide 已有後端 schema，前端範本規劃中。

關鍵檔案

檔案用途
types/index.ts合約型別（InteractionContext、QuizQuestion、QuizResult、WheelPrize、AvatarLayer/Option、GuideNode）
settings.schema.tsZod schema（題目顯示方式、結果版型、轉場動畫、評分邏輯）
app/interaction-entry.tsx靜態預覽入口
components/quiz/*題目、進度、結算頁元件
mock/*假 InteractionContext（測驗題目、結果）

平台側資料模型

後端模組：hypelink-backend-v3/src/experience/

Entity（共 8 張）：

  • experience
  • experience_quiz_question
  • experience_quiz_result
  • experience_wheel_prize
  • experience_avatar_layer
  • experience_avatar_option
  • experience_guide_node
  • experience_submission

SQL：hypelink-backend-v3/sql/add_experience_tables.sql

主要 API

品牌後台（需登入、品牌擁有者）：

GET  /hypelinks/:hypeId/experiences
POST /hypelinks/:hypeId/experiences
GET  /hypelinks/:hypeId/experiences/:expUuid
PATCH /hypelinks/:hypeId/experiences/:expUuid
DELETE /hypelinks/:hypeId/experiences/:expUuid
POST /hypelinks/:hypeId/experiences/:expUuid/cover
PUT  /hypelinks/:hypeId/experiences/:expUuid/quiz/questions
PUT  /hypelinks/:hypeId/experiences/:expUuid/quiz/results
GET  /hypelinks/:hypeId/experiences/:expUuid/analytics
GET  /hypelinks/:hypeId/experiences/:expUuid/submissions

公開（訪客可用）：

GET  /hypelinks/:hypeId/experiences/by-slug/:slug/public
POST /hypelinks/:hypeId/experiences/by-slug/:slug/submit

前端路徑

  • 後台：/dashboard/brands/[hypeId]/tool/interaction-game（BrandExperiencesClient.tsx）
  • 公開頁：/[hypeId]/experiences/[slug]/（ExperiencePublicClient.tsx）
  • 路徑 helper：publicExperiencePath（在 publicBrand.ts）

建置指令

在 interaction/hypelink-interaction-template/ 下：

pnpm install
pnpm dev              # 本地預覽
pnpm build            # Next.js 靜態輸出（out/）
pnpm write-publish    # 產生 dist/interaction.publish.json（若已對齊主題模式）

測試方式

1. 本地 mock 預覽

cd hypelink-theme/interaction/hypelink-interaction-template
pnpm install
pnpm dev

mock/quiz.ts 提供一組假測驗題與假結果，可直接看到題目流、進度條、結算頁。

2. 編輯器端測試

啟動主平台 frontend + backend：

cd hypelink-backend-v3 && npm run dev
cd hypelink && npm run dev
  1. 進 /dashboard/brands/[hypeId]/tool/interaction-game 點「新增」
  2. 選類型為 quiz，輸入名稱 / slug / 封面
  3. 在「題目」分頁以 QuizQuestionsEditor.tsx 新增題目與選項
  4. 在「結果」分頁以 QuizResultsEditor.tsx 新增結果與分數門檻
  5. 儲存後可直接點「預覽公開頁」跳到 /@handle/experiences/[slug]/

3. 公開頁驗證

匿名開新分頁（或用無痕視窗）打開 /@handle/experiences/[slug]/：

  • 確認題目流可作答、進度條前進、結算頁依分數分岔
  • 送出後應寫入 experience_submission
  • 回到後台「成效分析」分頁，應看到提交數與結果分佈

4. Schema 擴充原則

  • 合約型別變更必須在 範本 + 平台前端 + 後端 entity 同一輪更新
  • DB 欄位調整請補 SQL 至 hypelink-backend-v3/sql/
  • 新增 非 quiz 類型（wheel / avatar / guide）時，請在範本 components/ 下開對應資料夾並補上 mock

參考文件

  • document/skill-interaction-development.md — 技能書（題目版型、結果模板、轉場動畫、評分邏輯、新增類型）
Last updated on
模組（Module）