Chuyển đến nội dung

Bản ghi hình và dòng thời gian sự kiện

Hai cách để xem lại một trình duyệt hosted đã làm gì. Bản ghi hình là video màn hình của trình duyệt. Dòng thời gian sự kiện là danh sách những gì đã xảy ra, kèm mốc thời gian: trang, tab, cú nhấp, thao tác cuộn và gõ phím, quyết định của các solver thử thách, các bước của agent, lượt bàn giao và giới hạn. Bản phát lại kết hợp cả hai: video với mọi thao tác được vẽ chồng lên. Tất cả đều dùng được cho các phiên bạn tự điều khiển và cho lượt chạy agent.

Ghi hình một phiên

Truyền record: true khi tạo phiên hoặc lượt chạy. Theo mặc định, tính năng ghi hình tắt.

curl -X POST https://www.clearcotelabs.com/api/v1/browsers \
  -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{"record": true, "country": "de"}'

# an agent run: the same field
curl -X POST https://www.clearcotelabs.com/api/v1/runs \
  -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{"task": "Open the pricing page and read the cheapest plan", "url": "https://example.com", "record": true}'
  • Video hiển thị tab đang hoạt động, giống chế độ xem trực tiếp, với vài khung hình mỗi giây, dưới dạng MP4 H.264 1280×800 (các kích thước cửa sổ khác được thêm viền đen). Video dùng để xem điều gì đã xảy ra, không nhằm phát mượt mà.
  • Việc ghi hình dừng khi phiên kết thúc, hoặc khi tệp đạt giới hạn dung lượng; bản thân phiên vẫn tiếp tục.
  • Ghi hình không bị tính phí như lưu lượng: các khung hình được chụp trên máy chủ của chúng tôi, không tải về từ internet.
  • Chỉ một số máy chủ có thể ghi hình. Phiên có record: true chỉ được khởi động trên máy chủ có khả năng đó; nếu không còn máy chủ nào trống, bạn nhận mã 503 như thường lệ.

Trạng thái

Dữ liệu phiên (GET /api/v1/browsers/<id>, và session của một lượt chạy) có trường recording: null khi phiên không được ghi hình, nếu không thì:

json
"recording": {
  "status": "ready",              // recording | processing | ready | failed | expired
  "bytes": 18230411,
  "durationSec": 312.4,
  "expiresAt": "2026-10-16T09:20:11.000Z"   // when it stops being available
}

bytes, durationSec và expiresAt là null cho tới khi bản ghi hình ở trạng thái ready.

statusÝ nghĩa
recordingPhiên đang chạy và đang được ghi hình.
processingPhiên đã kết thúc; tệp đang được hoàn thiện và tải lên.
readyBạn có thể tải xuống hoặc chia sẻ.
failedKhông thể tạo hoặc tải lên bản ghi hình: phiên chưa bao giờ bắt đầu, máy chủ không hoàn thiện được tệp, hoặc 25 giờ sau khi phiên kết thúc tệp vẫn chưa tới. Không có tệp nào.
expiredĐã quá thời hạn lưu trữ: tệp đã bị xóa.

Tệp được tải lên sau khi phiên kết thúc, nên bản ghi hình chuyển sang ready muộn hơn phiên một chút; bản dài thì lâu hơn. Nếu 25 giờ sau khi phiên kết thúc tệp vẫn chưa tới, bản ghi hình được đánh dấu failed. Để được thông báo thay vì phải hỏi liên tục, hãy thêm một webhook recording.ready.

Tải xuống

GET /api/v1/browsers/<id>/recording trả về một chuyển hướng 302 tới liên kết tải xuống riêng tư có hiệu lực tối đa 5 phút. Hãy theo liên kết ngay thay vì lưu lại. Khi bản ghi hình còn ở recording hoặc processing, phản hồi là 409 với mã NOT_READY; phiên không được ghi hình, phiên có bản ghi hình bị lỗi hoặc đã hết hạn trả về 404 (NOT_FOUND).

bash
# -L follows the redirect to the file
curl -L -o session.mp4 -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/<id>/recording

# or with the SDK's command
clearcote cloud recording <id> -o session.mp4
python
from clearcote.cloud import Cloud

cloud = Cloud()
cloud.browsers.download_recording("bs_…", "session.mp4")   # saves the file
url = cloud.browsers.recording_url("bs_…")                 # or just the short-lived link

Dashboard phát bản ghi hình bên cạnh thông tin chi tiết của phiên, dưới dạng bản phát lại.

Bản phát lại

Bản phát lại chạy bản ghi hình với dòng thời gian của phiên được vẽ chồng lên: con trỏ và đường đi của nó, một vòng tròn tại nơi mỗi cú nhấp rơi xuống, đường đi của mỗi thao tác kéo (kể cả thanh trượt mà solver đã kéo), mỗi lần cuộn và mỗi đợt gõ phím, trang vừa mở, quyết định của các solver thử thách và các bước của agent dưới dạng phụ đề. Bên cạnh là danh sách hoạt động: nhấp vào một dòng để nhảy tới đó, và dòng của thời điểm hiện tại chạy theo video. Bạn có thể tăng tốc, hoặc bỏ qua những đoạn không có gì xảy ra. Phiên không được ghi hình cũng phát lại được: khi đó các thao tác được phát trên một nền trống, theo đúng thứ tự và nhịp độ thực.

Dưới khung hình là các số liệu của phiên, tại thời điểm bạn đang xem và tổng cộng: phiên đã chạy bao lâu, bao nhiêu dữ liệu đã đi qua proxy của nó (tải xuống và tải lên), các trang đã mở, số cú nhấp, lần cuộn và ký tự đã gõ, và kết quả của các thử thách. Biểu đồ thông lượng hiển thị lưu lượng trên cùng trục thời gian với video, kèm đầu phát; nhấp vào biểu đồ để nhảy tới đó. Bên cạnh là các site dùng nhiều dữ liệu nhất, và bên dưới là cách phiên ra internet (proxy dân cư, proxy của riêng bạn hoặc trực tiếp, kèm quốc gia đã yêu cầu), các kết nối đã mở và bao nhiêu kết nối thất bại, số lần thử lại của proxy, cùng quảng cáo và tracker mà adblock đã từ chối. Liên kết chia sẻ không bao giờ hiển thị địa chỉ proxy hay chi phí của phiên; dashboard của bạn có thêm chi phí.

Văn bản đã gõ không bao giờ được ghi vào dòng thời gian, chỉ có số ký tự đã gõ và tên các phím như Enter hay Tab; video hiển thị những gì trang đã hiển thị, như mô tả bên dưới.

Chia sẻ một phiên: trực tiếp, sau đó là bản phát lại

Liên kết theo dõi cho thấy phiên trực tiếp khi nó đang chạy, kèm danh sách những gì nó làm ở bên cạnh, và khi phiên kết thúc, chính liên kết đó mở bản phát lại. Không cần tài khoản để mở, và liên kết này không bao giờ cho phép điều khiển:

bash
curl -X POST -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{"replay": true}' https://www.clearcotelabs.com/api/v1/browsers/<id>/share
# { "url": "https://www.clearcotelabs.com/live/bs_…#t=…", "expiresAt": "…", "control": false, "replay": true }

replay: true dùng được cho mọi phiên của bạn, đang chạy hay đã kết thúc. minutes đặt thời gian liên kết có hiệu lực: 1 đến 20160 (14 ngày), mặc định 10080 (7 ngày). control không áp dụng (400). Bản phát lại chạy bản ghi hình khi phiên được ghi hình (record: true), và chạy các thao tác trên nền trống khi không được ghi hình. Token nằm sau dấu #, nên không bao giờ xuất hiện trong log máy chủ, và nó vẫn ở trong địa chỉ của trang, nên có thể chuyển nguyên địa chỉ đó cho người khác. Bất kỳ ai có liên kết đều xem được phiên và bản phát lại của nó cho tới khi liên kết hết hạn, vì vậy chỉ chia sẻ với những người được phép xem. Dòng thời gian hiển thị địa chỉ trang mà không có query string. Trong dashboard, “Share” trong chế độ xem trực tiếp tạo cùng liên kết này (“Watch + replay”), còn phiên đã kết thúc có “Share replay”.

Chia sẻ một bản ghi hình

Để chỉ cho ai đó không có tài khoản xem video, hãy tạo một liên kết bản ghi hình. Liên kết mở một trang trên site này để phát video, cho tới khi liên kết hết hạn:

bash
curl -X POST -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{"recording": true, "minutes": 120}' https://www.clearcotelabs.com/api/v1/browsers/<id>/share
# { "url": "https://www.clearcotelabs.com/replay/bs_…#t=…", "expiresAt": "…" }

Đây là cùng lệnh gọi share như với liên kết xem trực tiếp, kèm recording: true; minutes đặt thời gian liên kết có hiệu lực: 1 đến 240, mặc định 30, và không bao giờ quá expiresAt của bản ghi hình. Bản ghi hình chưa sẵn sàng trả về 409 NOT_READY, và control không áp dụng (400). Token nằm sau dấu #, nên không bao giờ xuất hiện trong log máy chủ; hãy chuyển nguyên vẹn liên kết. Các loại liên kết được tách riêng: liên kết bản ghi hình không mở được chế độ xem trực tiếp, và liên kết xem trực tiếp không mở được bản phát lại (liên kết theo dõi mở được cả hai). Bất kỳ ai có liên kết bản ghi hình đều xem được video, vì vậy hãy đối xử với nó như chính bản ghi hình.

Lưu trữ và quyền riêng tư

  • Bản ghi hình được lưu riêng tư trong 14 ngày kể từ khi chuyển sang ready. Tại recording.expiresAt, liên kết tải xuống và liên kết phát lại ngừng hoạt động và tệp bị xóa ngay sau đó; hãy tải xuống những gì bạn muốn giữ trước thời điểm đó.
  • Liên kết tải xuống chỉ được cấp cho bạn (qua API key của bạn hoặc dashboard) và ngừng hoạt động sau tối đa 5 phút; trước đó, bất kỳ ai có liên kết đều dùng được.
  • Bản ghi hình hiển thị những gì trang đã hiển thị. Mọi thứ gõ vào một ô nhập thông thường đều có trong video, kể cả một secret được gõ vào ô hiển thị văn bản. Ô mật khẩu hiển thị dấu chấm, giống như trên màn hình. Hãy tắt ghi hình cho những lượt chạy có màn hình mà bạn không muốn lưu lại.

Dòng thời gian sự kiện

Mỗi phiên đều lưu một dòng thời gian. Đọc nó bằng GET /api/v1/browsers/<id>/events, cũng dùng được cho lượt chạy (id của lượt chạy chính là id phiên của nó):

bash
curl -H "authorization: Bearer cc_live_..." "https://www.clearcotelabs.com/api/v1/browsers/<id>/events?after=0&limit=200"
json
{
  "events": [
    { "seq": 1, "at": "2026-10-02T09:14:05.410Z", "type": "session.started", "data": { "kind": "run" } },
    { "seq": 2, "at": "2026-10-02T09:14:05.912Z", "type": "run.started", "data": { "jet": { "version": "0.1.0", "commit": "cd7011c…" } } },
    { "seq": 3, "at": "2026-10-02T09:14:06.730Z", "type": "navigation", "data": { "url": "https://www.gov.uk/", "title": "Welcome to GOV.UK" } },
    { "seq": 4, "at": "2026-10-02T09:14:07.950Z", "type": "run.step",
      "data": { "step": 1, "kind": "click", "action": "Reject additional cookies", "text": null, "probability": 0.85, "url": "https://www.gov.uk/" } },
    …
    { "seq": 19, "at": "2026-10-02T09:14:21.006Z", "type": "session.ended", "data": { "reason": "run_finished" } }
  ],
  "next": null
}
  • seq đánh số các sự kiện của một phiên theo thứ tự, bắt đầu từ 1; có thể có khoảng trống. at là thời điểm sự kiện xảy ra.
  • after trả về các sự kiện sau seq đó (mặc định 0, tức từ đầu); limit từ 1 đến 500, mặc định 200. Giá trị nằm ngoài các khoảng này trả về 400.
  • next là giá trị after cho trang tiếp theo, hoặc null khi bạn đã có mọi thứ được lưu tính đến lúc này.
  • Khi phiên đang chạy, các sự kiện tới theo từng đợt cùng với báo cáo sử dụng của trình duyệt, khoảng 15 giây một lần. Để theo dõi một phiên đang chạy, hãy tiếp tục hỏi với after đặt bằng seq cuối cùng bạn đã thấy.
  • Một phiên lưu tối đa 1000 sự kiện, ngoài ra thêm tối đa 2000 sự kiện input và 1500 sự kiện traffic; một sự kiện truncated duy nhất đánh dấu nơi các sự kiện bị bỏ. Sự kiện bị xóa 2 ngày sau khi phiên kết thúc.
  • Sự kiện input được gửi khi thao tác đã xong, nên at của nó (thời điểm thao tác bắt đầu) có thể sớm hơn sự kiện đứng trước. Hãy sắp xếp theo at để hiển thị đúng thứ tự mọi việc đã xảy ra.
  • Chế độ xem trực tiếp nhận sự kiện ngay khi chúng xảy ra, không chờ báo cáo sử dụng: mỗi sự kiện tới qua WebSocket của nó dưới dạng tin nhắn văn bản {"ev": {"seq", "at", "type", "data"}}, với at tính bằng mili giây (chỉ các loại mà chế độ xem được chia sẻ có thể hiển thị: không có client.connected, lệnh hay host bị từ chối, chi tiết profile hay chi phí).
from clearcote.cloud import Cloud

cloud = Cloud()
after = 0
while True:
    page = cloud.browsers.events("bs_…", after=after)
    for e in page["events"]:
        print(e["seq"], e["at"], e["type"], e["data"])
    if page["next"] is None:
        break
    after = page["next"]
Tab này chạy trên máy của bạn.

Các loại sự kiện

typedataÝ nghĩa
session.started{ kind, proxy, country?, state?, city?, adblock, headless, geo? }Trình duyệt đã sẵn sàng. kind là "cdp" với phiên do bạn điều khiển, "run" với một lượt chạy agent.
navigation{ url, title }Một tab đã chuyển tới địa chỉ mới. Tối đa một sự kiện mỗi giây cho mỗi tab.
tab.opened{ url }Một tab mới hoặc cửa sổ pop-up đã mở.
tab.closed{}Một tab đã đóng.
cdp.denied{ method, reason }Trình duyệt hosted đã từ chối một lệnh CDP, ví dụ tải tệp lên từ máy chủ. Tối đa 50 sự kiện mỗi phiên.
profile.loaded{ cookies, files }Một profile đã lưu được nạp vào trình duyệt.
profile.saved{ cookies, bytes }Profile được lưu lại khi phiên kết thúc.
run.started{ jet: { version, commit } }Jet bắt đầu một lượt chạy, kèm phiên bản của nó.
run.step{ step, kind, action, text, probability, url }Một bước của lượt chạy, giống như trong result.steps. Secret trong text hiển thị dưới dạng {{name}}.
run.finished{ status, detail }Jet đã dừng, kèm trạng thái của kết quả (done, blocked, needs_input, budget, error).
handoff.requested{ reason }Agent của một lượt chạy đã yêu cầu một người can thiệp (handoff: true). Lượt bàn giao do bạn tự bắt đầu bằng POST …/handoff không có trong dòng thời gian; với những trường hợp đó, hãy dùng webhook handoff.requested.
handoff.done{}Lượt bàn giao của một lượt chạy đã được đánh dấu là xong (nút “I'm done”, dashboard hoặc API) và agent tiếp tục làm việc.
recording.started{ fps }Khung hình đầu tiên của bản ghi hình: giây 0 của video. Vị trí của một sự kiện trong video là at của nó trừ đi at của sự kiện này. fps là tốc độ khung hình.
slider{ variant, outcome, attempt?, reason?, site }Một lần thử với thử thách thanh trượt (solveSliders). variant là slide hoặc puzzle; outcome là passed (thử thách biến mất), failed (thử thách vẫn còn; attempt đếm số lần, tối đa ba lần mỗi trang) hoặc skipped, kèm một reason, khi một câu đố được để nguyên thay vì kéo theo phỏng đoán.
checkbox{ outcome, attempt?, reason?, site }Một lần thử với thử thách ô đánh dấu (solveCheckboxes): một ô “xác minh bạn là người” đã được nhấp. outcome là passed (ô biến mất hoặc đã được đánh dấu), failed (ô vẫn đang chờ; attempt đếm số lần, tối đa ba lần mỗi trang) hoặc skipped, kèm một reason.
pressHold{ outcome, attempt?, reason?, site }Một lần thử với thử thách nhấn giữ (solvePressHold): một nút xác minh dạng nhấn giữ đã được giữ cho tới khi nó báo hoàn tất. outcome là passed (nút báo hoàn tất hoặc biến mất), failed (nút không báo; lần giữ bị hết thời gian có reason là timeout, và attempt đếm số lần thử) hoặc skipped, kèm một reason.
challenge.detected{ category, solvable, reason?, site } once per challenge per page, with challengeService onKhi bật challengeService: một thử thách mà trang đã hiển thị, một lần cho mỗi thử thách trên mỗi trang. category (token, score, clearance, block-page, image), solvable, và một reason khi không giải được (not_supported, needs_relay, category_off, ip_blocked, missing_parameters).
challenge.service{ category, outcome, reason?, applied?, attempt?, ms?, costUsd?, site } one per answer the solving service was asked forMột yêu cầu gửi tới dịch vụ giải (challengeService). outcome là solved (câu trả lời đã được áp dụng và thử thách biến mất; applied cho biết cách áp dụng: callback, field, cookie, typed, dragged, hook), failed hoặc skipped, kèm một reason (unsolved, still_there, bad_key, no_balance, budget, ...). costUsd là số tiền dịch vụ đã tính cho yêu cầu đó.
client.connected{ ip, ua }Một client CDP đã kết nối tới phiên (kể cả khi kết nối lại): địa chỉ mà máy chủ của phiên nhìn thấy và User-Agent của client.
egress.refused{ host, port, reason }Trình duyệt đã cố truy cập một địa chỉ private, loopback hoặc link-local (reason: private, loopback, link-local, own-ip, blocked-range) hoặc một cổng bị chặn như cổng 25 (blocked-port), và kết nối đã bị từ chối. Một lần cho mỗi host và cổng, tối đa 50 sự kiện mỗi phiên.
input{ kind, by, x?, y?, vw?, vh?, shown?, ms, path?, x2?, y2?, dx?, dy?, button?, n?, chars?, keys? }Một thao tác trên trang, gửi khi thao tác đã xong: kind là click, drag, tap, scroll, type, move (con trỏ di chuyển rồi dừng mà không nhấp) hoặc capped (từ đây các thao tác của phiên không còn được lưu). by cho biết ai thao tác: client (kết nối của bạn), agent (agent của một lượt chạy), viewer (một người trong chế độ xem trực tiếp) hoặc solver (các solver thử thách). x, y là pixel CSS trong viewport vw × vh của trang; shown là true trên tab mà chế độ xem trực tiếp và bản ghi hình đang hiển thị, false trên tab khác. path là đường đi của con trỏ dưới dạng [ms from at, x, y], ms là thời gian thao tác kéo dài. type cho chars, số ký tự đã gõ, và keys, tên các phím như Enter hay Tab và các phím tắt như Ctrl+V; không bao giờ có nội dung văn bản.
traffic{ up, down, conns, failed, retries, blocked }Lưu lượng đã đi qua proxy của phiên tính đến lúc này, cộng dồn: up và down tính bằng byte, conns số kết nối đã mở, failed số kết nối không thực hiện được, retries số tunnel được thử lại sau khi proxy trục trặc, blocked số request bị adblock từ chối. Gửi vài giây một lần khi có giá trị nào thay đổi; bản phát lại vẽ nó thành biểu đồ.
limit{ reason }Đã chạm một giới hạn: max_duration, idle_timeout, max_bytes, max_files_size (thư mục tệp của phiên đã đầy) hoặc max_recording_size (chỉ việc ghi hình dừng lại; phiên vẫn tiếp tục). Hết số dư chỉ hiện trong session.ended.
geo.drift{ code: "GEO_EXIT_ROTATING" } your own proxy's exit IP changed after the start: the timezone, language and WebRTC address describe the previous one
session.ended{ reason, code? }Phiên đã kết thúc, kèm lý do (giống endReason của phiên).
truncated{} One marker at the first event that was not kept: the session reached 1000 stored eventsTừ đây các sự kiện đã bị bỏ: phiên đã vượt quá 1000 sự kiện (sự kiện input và traffic có hạn mức riêng), hoặc máy chủ của phiên không gửi kịp. Tối đa một sự kiện mỗi phiên.

Dữ liệu sự kiện được giữ gọn: sự kiện có data lớn hơn 2 KB sẽ lưu { "truncated": true } thay thế. Secret không bao giờ xuất hiện trong sự kiện; khi một bước gõ một secret, text của nó hiển thị {{name}}. Có thể có thêm loại sự kiện mới, vì vậy hãy bỏ qua những loại bạn không biết thay vì báo lỗi.

Cập nhật 22 thg 11, 2026 · SDK 0.70.5 · trình duyệt r63

Trang này có hữu ích không?