品牌消消樂 · Campaign Match

可換皮的三消行銷活動模板。純 HTML / CSS / JavaScript，無執行依賴、無建置步驟；直接開啟 index.html，或部署整個目錄至靜態網站。

本機啟動與測試索引

建議從專案目錄啟動靜態 HTTP 伺服器（需已安裝 Python 3）：

python3 -m http.server 8080 --bind 127.0.0.1

開啟 http://127.0.0.1:8080/test-index.html，即可集中進入每個活動的遊戲、設定及介紹頁。清單直接讀取 campaign-config.js，新增活動後會自動出現；顯示的是設定檔預設參數，不包含瀏覽器儲存的覆寫。遊戲首頁和設定頁也有「測試索引」連結。

index.html 是玩家遊戲入口，test-index.html 是測試入口。請持續使用相同網域及連接埠測試，因為瀏覽器儲存依來源區隔；localhost 與 127.0.0.1 也屬不同來源。停止本機伺服器請按 Ctrl+C。

三套示範

入口	活動	規則	結果按鈕
index.html 或 index.html?campaign=classic	原始動物三消	20 步 / 10,000 分	查看活動資訊
index.html?campaign=pet	毛孩好物消消樂	20 步 / 10,000 分	完成一局即可探索好物
index.html?campaign=midautumn	月圓好禮消消樂	24 步 / 6,000 分	過關後才顯示禮盒連結

沒有指定 campaign 時，預設使用原本的動物三消：六種動物符號、原有深色配色、20 步與 10,000 分。流程：活動介紹 → 玩家按下開始 → 遊玩 → 結果與分數 → 活動連結。示範連結前往同目錄的 offer.html，不發放真實優惠或獎品。

建立一個活動

1. 複製專案至新的部署目錄。
2. 在 campaign-config.js 複製一份活動設定，使用新的 key 與唯一 id，並將 defaultCampaign 改成該 key。
3. 將 Logo、背景與六種棋子放入 assets/<活動名稱>/，修改設定內的素材路徑。
4. 修改品牌文案、顏色、規則與 cta.url；可以連到既有優惠頁、商品頁或報名頁。
5. 使用下方測試命令，並在手機檢查開始、交換、結果與連結，再將整個目錄發布。

?campaign=key 可預覽指定設定；沒有參數時使用 defaultCampaign。未知 key 或必要設定錯誤會顯示活動無法開啟，避免誤用另一活動。正式單活動部署可刪除其他示範設定與素材。

修改與儲存設定

從遊戲首頁的「遊戲設定」進入 settings.html，或使用 settings.html?campaign=pet 選擇活動。可調整步數、目標分數、背景色與圖片、Logo、配色、字體、圓角、六種棋子、品牌文案與活動連結。

1. 從測試索引選擇「調整設定」，確認目前活動。
2. 修改遊戲參數或視覺。背景圖片填入 HTTP(S) 網址或相對路徑，例如 assets/pet/background.svg；留空即顯示背景色，載入失敗時也保留此底色。圖片欄位不會上傳檔案，請自行將素材放入 assets/。
3. 按「預覽外觀」檢查設定頁的外觀；此步驟尚未保存。背景套用在整頁，頁面底部另有棋子、按鈕及參數預覽。
4. 按「儲存設定」，看到成功訊息後返回遊戲或重新載入。已開啟的遊戲不會中途變動；離開前未儲存的修改不會保留。
5. 要讓所有玩家使用，按「匯出設定檔」，將下載檔替換專案中的 campaign-config.js，並依下方部署流程發布。

操作	儲存位置與影響
預覽外觀	僅目前設定頁，重新載入後消失
儲存設定	目前來源的 localStorage，以 critter-match-settings:<活動 key> 區隔；不修改專案或伺服器檔案，也不跨瀏覽器同步
還原此活動預設值	移除此活動的本機覆寫，重新讀取已部署設定檔；其他活動及最高分不受影響，未儲存表單也會重設
匯出設定檔	下載目前表單內容，不必先按儲存；目前活動成為 defaultCampaign，其他活動保留原設定檔的內容，不合併其他活動的本機覆寫
直接編輯 campaign-config.js	修改可部署的共用預設值；發布後供沒有本機覆寫的玩家使用

如果要發布多個活動的修改，請依序匯出、替換設定檔、重新載入設定頁，再修改下一個活動，或直接編輯設定檔中的各活動。

本機覆寫優先於設定檔。部署新版後若仍看到舊設定，請按「還原此活動預設值」，或用無痕視窗驗證。相同來源下的不同目錄會共用 localStorage，活動 key 相同時也會共用覆寫；需要隔離的測試站請使用不同來源或不同活動 key。

建議透過 HTTP 開啟；file:// 的跨頁儲存取決於瀏覽器支援。儲存被禁止或空間不足時會顯示錯誤，仍可匯出；損壞的本機設定會回退到活動預設值。

設定欄位

欄位	用途
id	英數字、底線、連字號組成的唯一活動 ID，區隔最高分與分析事件
brand, title, tagline	品牌名稱、頁面標題、副標
introHeading, intro, terms	開場標題、活動說明、活動條款文字
logo, background	圖片路徑；背景省略或留空時顯示 colors.bg 單色
colors	bg、panel、cell、cell-hi、ink、muted、accent、good、bad、focus，使用六碼 HEX
font, radius	CSS 字體列表、0–99px 圓角；建議使用系統字體
tiles	必須六種，每種有 name、symbol，可選 image
rules.maxMoves	1–100 的整數步數
rules.targetScore	1–1,000,000 的整數目標分數
copy	開始、重玩、提示、成功與失敗文案，參照示範欄位
cta.label, cta.url	結果頁主要按鈕文字與網址；支援相對路徑或 HTTP(S)
cta.requiresWin	true：過關後顯示；false：完成一局即顯示
offer	本機示範活動介紹頁的 title 與 description

設定是由主辦方維護的 JavaScript 檔案，文案以純文字呈現。圖片失敗時棋子保留備用符號；Logo 失敗時保留品牌文字。未載入成功的必要腳本仍需由部署端監控。

素材規範

• 棋子建議透明背景、正方形 SVG 或 128×128 以上 PNG / WebP；主體保留約 10% 留白。
• 六種圖案應在小尺寸下仍能區分，避免只靠細微色差；每張建議不超過 50 KB。
• Logo 使用正方形素材，避免將長段文字塞入圖內；品牌文字另有欄位。
• 背景使用低對比裝飾，確保棋盤與文案清晰。
• 附帶的 SVG 是本專案繪製的示範素材，沿用 MIT License。

建議部署方式

此專案只需靜態檔案託管，不需要 Node.js 常駐服務、資料庫或建置指令。本機 Python 伺服器用於測試；正式發布建議使用提供 HTTPS 的靜態網站服務，或既有的 Nginx / Apache 靜態目錄。

GitHub Pages（適合此 GitHub 專案）

1. 將要發布的 campaign-config.js、頁面、腳本與素材提交至發布分支。
2. 在儲存庫的 Settings → Pages 設定分支發布來源，選擇發布分支（此專案目前使用 master）與根目錄 / (root)。
3. 等待 Pages 部署完成，使用 Pages 顯示的網址開啟 index.html；測試人員可開啟同目錄的 test-index.html。

GitHub Pages 支援直接發布靜態檔案，入口檔需位於發布來源頂層。帳號方案與儲存庫可見性須符合 Pages 使用條件；設定細節見 GitHub Pages 官方建立指南。

ZIP 部署至既有靜態主機

1. 匯出並替換 campaign-config.js，確認圖片已放在正確相對路徑。

2. 執行下方回歸測試，取得 build latest 工作流程的 ZIP，或直接複製以下部署檔案：

   index.html        style.css
   game-core.js      game-ui.js
   campaign-config.js  campaign.js
   offer.html        offer.js
   settings.html     settings.js
   test-index.html   test-index.js
   assets/
   

3. 將 ZIP 解壓縮至網站目錄，保留目錄結構；index.html 應位於預期網址的根層，例如 /campaign/index.html。

4. 使用 HTTPS 網址測試遊戲、圖片與 CTA 連結。若外部圖片使用 HTTP，請改為 HTTPS，避免混合內容載入問題。

5. 用無痕視窗確認部署預設值，再用一般視窗測試設定儲存；若主機或 CDN 有快取，更新後需讓設定檔、HTML 與腳本快取同步失效。

現有 build latest 只產生 ZIP artifact，不會自動部署網站。設定頁是本機編輯工具，公開部署後也只會修改使用者自己的瀏覽器設定；共用預設值必須透過替換檔案及重新部署更新。

分析事件

預設不載入第三方分析、不傳送網路請求，也不建立永久訪客識別。整合者需在 game-ui.js 執行之前註冊監聽器，才能收到首次瀏覽事件：

window.addEventListener('critter:analytics', function (event) {
  console.log(event.detail); // 在此交給所選的分析服務
});

若頁面已建立 window.dataLayer = []，相同事件也會送入該陣列。請選一種方式接收，避免重複計算。此介面本身不代表資料已被分析平台保存。

event	時機與額外欄位
campaign_view	遊戲頁初始化完成，一次頁面載入一筆
game_start	開始或重新開始，含 play_id
game_end	過關或步數耗盡，含 play_id, won, score, moves_remaining, duration_ms
cta_click	點擊結果頁活動連結，含 play_id, won, score

所有事件都有 campaign_id 與 ISO 格式 timestamp。play_id 僅為本次頁面中的局數序號；中途重玩不算一局完成。cta_click 是點擊，不是領券、報名或購買完成；完成轉換需由目的服務確認。外部分析服務的送出方式需自行處理離頁傳輸。

遊戲與可達性

棋盤 8×8、六種圖案，橫／縱三個以上相同即可消除。每波計分 消除數 × 100 × combo，無效交換不扣步數，死局自動洗牌。保留滑動、點擊、鍵盤操作與減少動畫偏好。

鍵盤：方向鍵移動、Enter / Space 選取及交換、Escape 取消選取；結果視窗以 Tab / Shift+Tab 在活動按鈕與重玩之間循環。最高分儲存於 critter-match-best:<活動 ID>，舊版最高分不遷移至新活動。

requiresWin 只控制畫面呈現，純前端分數與最高分不能作為兌獎依據。每人限領、限量獎品、身分驗證及正式發獎需要後端服務，本版未實作。

開發與驗證

推送到 master 或在 GitHub Actions 手動執行 build latest，會先執行核心與活動設定測試，再產生 critter-match-latest.zip。該 ZIP 只包含可部署的 HTML、CSS、JavaScript 與 assets/，並以 Actions artifact 保存 30 天；下載後解壓縮即可開啟 index.html。

node test/core.test.js
node test/campaign.test.js

核心測試驗證棋盤、交換、消除、補牌與洗牌；活動測試驗證設定、素材、網址、事件與錯誤狀態。

瀏覽器流程測試需另行安裝 Playwright（僅開發使用，不是網站依賴）：

npm install --prefix /tmp/pethouse-qa playwright
/tmp/pethouse-qa/node_modules/.bin/playwright install chromium
NODE_PATH=/tmp/pethouse-qa/node_modules node test/browser.cjs

測試自行啟動只綁定本機的臨時 HTTP server，結束後關閉。

檔案	用途
campaign-config.js	活動設定與三套示範
campaign.js	設定驗證、本機儲存、主題與事件介面
settings.html, settings.js	設定表單、外觀預覽與設定檔匯出
game-core.js	純三消邏輯；棋盤參數集中於此
game-ui.js	遊戲狀態、動畫、輸入、計分與結果
index.html, style.css	活動版型與響應式樣式
offer.html, offer.js	本機示範活動介紹頁
test-index.html, test-index.js	自動列出活動的測試索引
assets/	毛孩與中秋 SVG 主題素材
test/	核心、活動設定及瀏覽器回歸測試

License

MIT