Activity Log 監控

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`	區域網路上的裝置探索與同步活動

截圖

啟用截圖擷取後，可從 BRICKS Controller 觸發截圖，並以 JPEG 圖片形式上傳至 Activity Log 伺服器。截圖會加上時間戳記並依裝置儲存，讓您能視覺化檢閱裝置在任意時間所顯示的畫面。截圖適用於：

視覺稽核 — 確認在特定行銷活動或時間窗口期間顯示了正確的內容
事件調查 — 查看發生異常時裝置確切顯示的畫面
遠端監控 — 無需實體存取即可視覺化確認已部署裝置的狀態

事件的上傳方式

事件在裝置上被擷取、本機快取後，會定期以批次方式上傳至 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

以 Bearer token 方式帶入您的 token：

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）

時間範圍查詢每次請求最多限制 30 天。

查詢截圖

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 回應時間和事件頻率

概覽

指南

參考

更新日誌

Activity Log 監控

啟用記錄

事件 ID 篩選

記錄的內容

事件

截圖

事件的上傳方式

截圖

截圖擷取的運作方式

檢視截圖

使用 GraphQL 查詢

驗證

端點

查詢

查詢事件

可用篩選欄位

查詢截圖

使用 BRICKS CLI

Prometheus 相容 API

資料保留

截圖

事件

使用情境

下一步

除錯面板

自動化

​啟用記錄

​事件 ID 篩選

​記錄的內容

​事件

​截圖

​事件的上傳方式

​截圖

​截圖擷取的運作方式

​檢視截圖

​使用 GraphQL 查詢

​驗證

​端點

​查詢

​查詢事件

​可用篩選欄位

​查詢截圖

​使用 BRICKS CLI

​Prometheus 相容 API

​資料保留

​截圖

​事件

​使用情境

​下一步

除錯面板

自動化

啟用記錄

事件 ID 篩選

記錄的內容

事件

截圖

事件的上傳方式

截圖

截圖擷取的運作方式

檢視截圖

使用 GraphQL 查詢

驗證

端點

查詢

查詢事件

可用篩選欄位

查詢截圖

使用 BRICKS CLI

Prometheus 相容 API

資料保留

截圖

事件

使用情境

下一步