Activity Log 監控會擷取來自 BRICKS Foundation 裝置的應用程式事件與截圖，並儲存至雲端時間序列資料庫。使用它來分析裝置行為、追蹤使用者互動、監控應用程式健康狀況，並視覺化檢閱裝置在任意時間點所顯示的畫面。
Activity Log 監控適用於 Business 方案的工作區。
啟用記錄
從 BRICKS Controller 在裝置上啟用 Activity Log：
- 開啟裝置詳細頁面
- 前往設定 > Activity Log
- 開啟已啟用
您也可以透過Device Group 分頁部署 Activity Log 設定，為群組中的所有裝置啟用記錄。
事件 ID 篩選
使用事件 ID 篩選欄位設定 regex 模式，以控制要記錄哪些事件。只有 ID 符合模式的事件才會被擷取。留空則記錄所有事件。
記錄的內容
每個記錄項目包含：
| 欄位 | 說明 |
|---|
| 事件名稱 | 事件類型的識別碼 |
| 時間戳記 | 事件發生的時間 |
| Payload | 自訂的事件特定內容 |
| 裝置 ID | 產生事件的裝置 |
| Subspace ID | Canvas Subspace 情境（若適用） |
| Sender | 發出事件的元件或模組 |
| 類別 | 事件名稱 | 說明 |
|---|
| General | BRICK_*、GENERATOR_*、CANVAS_*、SUBSPACE_* 等 | UI 互動、生命週期事件及自訂應用程式事件 |
| Data | PROPERTY_BANK_* | Property bank 狀態更新 |
| Local Sync | LOCAL_SYNC_INFO | 區域網路上的裝置探索與同步活動 |
- 視覺稽核 — 確認在特定行銷活動或時間窗口期間顯示了正確的內容
- 事件調查 — 查看發生異常時裝置確切顯示的畫面
- 遠端監控 — 無需實體存取即可視覺化確認已部署裝置的狀態
事件的上傳方式
事件在裝置上被擷取、本機快取後，會定期以批次方式上傳至 Activity Log 伺服器（預設：每 2 分鐘）。在瀏覽器環境中，頁面卸載時會自動觸發最後一次上傳，以將資料遺失降至最低。
截圖擷取的運作方式
啟用後，可從 BRICKS Controller 觸發截圖，並以 JPEG 圖片形式上傳至 Activity Log 伺服器，並附上擷取時間戳記。伺服器每台裝置每個時間戳記僅儲存一張圖片——以相同時間戳記重新上傳會取代先前的圖片。
每張圖片必須小於 5 MB。
檢視截圖
截圖可透過 BRICKS Controller 或 GraphQL API 依時間戳記取得。screenshots 查詢會回傳可用時間戳記的清單；使用下載 API 或 BRICKS CLI 取得任意時間戳記的圖片。
# 列出裝置的可用截圖
bricks activity-log screenshots --device <device-id> --start-time 2024-01-01T00:00:00Z
# 下載特定截圖
bricks activity-log screenshot --device <device-id> --ts 2024-01-15T10:30:00Z -o screenshot.jpg --open
使用 GraphQL 查詢
Activity Log 伺服器提供 GraphQL API，可查詢事件與截圖。用它來建立自訂儀表板、整合外部分析工具，或自動化記錄分析。
所有 GraphQL 查詢都需要具有 query_activity_log 權限的工作區 token。在 BRICKS Controller → 工作區設定 → Tokens 中建立。
https://activity-log.bricks.tools/api/graphql
Authorization: Bearer <token>
查詢事件
API 提供依類別分類的查詢（general_events、data_events、local_sync_stats）以及用於跨類別取得資料的統一 events 查詢。使用同一端點網址的 GraphQL 測試介面瀏覽完整 schema。
query {
general_events(filter: {
device_id: "your-device-id"
start_time: "2024-01-15T00:00:00Z"
end_time: "2024-01-15T23:59:59Z"
}) @stream {
timestamp
event_name
payload
}
}
可用篩選欄位
| 欄位 | 適用對象 | 說明 |
|---|
device_id | 全部 | 依裝置篩選 |
event_type | 僅 events | general、data 或 local_sync |
event_name | 全部 | 依特定事件名稱篩選 |
subspace_id | 全部 | 依 Canvas Subspace 篩選 |
sender | 全部 | 依發出元件篩選 |
start_time | 全部 | 範圍起始（ISO 8601） |
end_time | 全部 | 範圍結束（ISO 8601） |
查詢截圖
query {
screenshots(filter: {
device_id: "your-device-id"
start_time: "2024-01-15T00:00:00Z"
end_time: "2024-01-15T23:59:59Z"
}) @stream {
timestamp
}
}
使用 BRICKS CLI
BRICKS CLI 封裝了常見查詢模式的 GraphQL API：
# 使用篩選條件查詢事件
bricks activity-log events \
--start-time 2024-01-15T00:00:00Z \
--device your-device-id \
--type general \
--event-name BRICK_CLICK \
--limit 100
# 以 JSON 格式輸出
bricks activity-log events --start-time 2024-01-15T00:00:00Z --device your-device-id -f json
Prometheus 相容 API
若需要指標儀表板（Grafana 等），Activity Log 也可透過 Prometheus 相容 API 查詢。請參閱工作區設定中的查詢 Activity Log 指南，了解端點 URL 與使用範例。
資料保留
截圖保留期限由上傳時的工作區方案決定：
| 方案 | 截圖保留期限 |
|---|
| Free | 7 天 |
| Basic | 90 天 |
| Pro | 90 天 |
| Business | 90 天 |
使用情境
- 使用者行為分析 — 追蹤使用者如何與 Brick 互動並在 Canvas 之間切換
- 疑難排解 — 調查錯誤或非預期行為發生前的情況
- 機隊監控 — 監控多台已部署裝置的事件模式
- 視覺稽核 — 檢閱截圖以確認顯示了正確的內容
- 效能追蹤 — 分析 Generator 回應時間和事件頻率
下一步
