Xem trực tiếp và phiên
Theo dõi một trình duyệt hosted trực tiếp, tự điều khiển hoặc chia sẻ chế độ xem, quản lý các phiên của bạn, và giữ trình duyệt chạy để kết nối lại sau.
Mọi request trên trang này đều gửi được ngay từ chính trang này. Khi bạn đã đăng nhập, các ví dụ mang sẵn API key của bạn, và nút Gửi thực hiện lệnh gọi thật và cho bạn xem phản hồi thật, nên bạn có thể đổi một trường và xem nó tác động ra sao.
Một trình duyệt để chạy thử
Hầu hết các phần bên dưới cần một trình duyệt đang chạy. Hãy khởi động một trình duyệt tại đây: đó là một phiên bình thường, tính phí như mọi phiên khác (€1.00 mỗi GB, trừ vào số dư của bạn), và phiên này tự kết thúc sau năm phút không nhận lệnh nào, hoặc sau tổng cộng mười lăm phút.
POST Khởi động một trình duyệt
Phản hồi chứa id của phiên và một connectUrl chỉ dùng được một lần. Phiên bắt đầu khi một client kết nối tới URL đó (trước đó phiên ở trạng thái pending, và sẽ hết hạn sau 45 giây). Nhấn Kết nối và trang tài liệu sẽ kết nối, đọc tab rồi ngắt kết nối, giống như script Playwright hoặc Puppeteer của bạn; với keepAlive, trình duyệt tiếp tục chạy cho các request bên dưới.
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers' \ -H "authorization: Bearer cc_live_..." \ -H "content-type: application/json" \ -d '{"keepAlive":true,"url":"https://example.com","idleTimeoutSec":300,"timeoutSec":900,"note":"docs"}'
Xem trực tiếp: theo dõi, tự điều khiển, chia sẻ
Trong dashboard, nhấp vào một phiên để xem lưu lượng của nó đã đi tới những site nào và để xem trực tiếp. Nhấn “Take control” để tự nhấp, gõ, cuộn, dán và điều hướng trong đó, ví dụ để đăng nhập hoặc hoàn tất một bước kiểm tra mà script của bạn không tự làm được. Script của bạn vẫn giữ kết nối suốt thời gian đó, nên hãy tạm dừng nó trong lúc bạn thao tác. Thao tác của con người được tính là hoạt động, nên một phiên bạn đang điều khiển sẽ không bị đóng vì idle. “Share” tạo một liên kết mà bất kỳ ai cũng mở được mà không cần tài khoản, chỉ để xem hoặc kèm quyền điều khiển, có hiệu lực từ 15 phút đến 4 giờ và không bao giờ kéo dài quá thời điểm phiên kết thúc. Liên kết “Watch + replay” cho xem phiên trực tiếp và, khi phiên kết thúc, xem lại bản phát lại của nó: mọi cú nhấp, thao tác cuộn và trang được vẽ chồng lên bản ghi hình, trong tối đa 14 ngày.
Qua API:
GET Mở chế độ xem trực tiếp
Một WebSocket xem trực tiếp cho một phiên đang chạy (hãy mở nó trong vòng 60 s). Message nhị phân là các khung hình JPEG, message văn bản là {"url","title","tabs"}. Với control=1, phản hồi sẽ có "interactive": true khi quyền điều khiển được cấp. Xem tại đây mở chế độ xem ngay trên trang này. Mỗi sự kiện trong dòng thời gian cũng được gửi ngay khi xảy ra, dưới dạng {"ev": …} (xem Bản ghi).
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/live' \ -H "authorization: Bearer cc_live_..."
POST Chia sẻ chế độ xem trực tiếp
Một liên kết mà bất kỳ ai cũng mở được mà không cần tài khoản: quyền điều khiển là tùy chọn, từ 1 đến 240 phút (mặc định 30), không bao giờ kéo dài quá thời điểm phiên kết thúc. Hãy giữ kín liên kết có quyền điều khiển như API key của bạn. Với replay: true (và không kèm quyền điều khiển), đó là liên kết xem + phát lại: trực tiếp khi phiên đang chạy, sau đó là bản phát lại của nó, từ 1 đến 20160 phút (mặc định 10080, 7 ngày).
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/share' \ -H "authorization: Bearer cc_live_..." \ -H "content-type: application/json" \ -d '{"control":false,"minutes":60}'
Khi có quyền điều khiển, hãy gửi các message văn bản dạng JSON trên cùng WebSocket đó. Tọa độ là phân số (0 đến 1) của khung hình bạn đang xem; mọi thứ khác đều bị bỏ qua.
| Message | Tác dụng |
|---|---|
{"t":"mouse", | Nhấn (down), nhả (up) hoặc di chuyển (move); n là số lần nhấp, m là phím bổ trợ (Alt 1, Ctrl 2, Meta 4, Shift 8). |
{"t":"wheel", | Cuộn theo số pixel tại một điểm. |
{"t":"key", | Một phím được nhấn xuống hoặc nhả ra, đúng như bàn phím gửi đi. |
{"t":"text", | Chèn văn bản như thể được gõ vào (tối đa 5000 ký tự). |
{"t":"nav",, forward, reload, hoặc {"t":"nav", | Lịch sử, tải lại, hoặc mở một địa chỉ http(s). |
GET /api/v1/browsers/<id> có kèm traffic: 20 site tốn nhiều byte nhất của phiên đó.
Quản lý phiên
GET Một phiên
Trạng thái, lưu lượng, số giây và chi phí của phiên tính đến lúc này. Các trường được mô tả bên dưới các request.
curl 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..."
GET Các phiên của bạn
Số dư và các phiên của bạn, mới nhất xếp trước: mặc định 20 phiên, tối đa 100 với limit. Lọc theo trạng thái và theo nội dung note; để lùi về các phiên cũ hơn, đặt before bằng createdAt của phiên cuối cùng bạn nhận được. Nhấn Dùng trên một dòng để làm việc với phiên đó trong các request khác.
curl 'https://www.clearcotelabs.com/api/v1/browsers' \ -H "authorization: Bearer cc_live_..."
PATCH Gắn nhãn cho phiên
Đặt hoặc đổi note (tối đa 256 ký tự); null sẽ xóa nó.
curl -X PATCH 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..." \ -H "content-type: application/json" \ -d '{"note":"shop-de nightly"}'
DELETE Dừng phiên
Một phiên chưa có ai kết nối sẽ kết thúc ngay; còn trình duyệt đang chạy sẽ được máy chủ của nó đóng trong vòng một chu kỳ báo cáo, khoảng 15 giây.
curl -X DELETE 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E' \ -H "authorization: Bearer cc_live_..."
Đặt note cho phiên khi tạo để tìm lại nó trong danh sách và trên dashboard. Để khởi động một phiên trên cùng máy chủ với một phiên trước đó (cache còn nóng, cùng một máy), hãy truyền worker của phiên đó; khi máy chủ đó đã đầy hoặc ngoại tuyến, phiên sẽ khởi động trên một máy chủ khác và warnings của phiên sẽ cho biết điều đó.
Một phiên cũng kết thúc khi bạn đóng trình duyệt hoặc ngắt kết nối, và khi chạm một trong các giới hạn bên dưới. Yêu cầu dừng sẽ kết thúc ngay một phiên chưa có ai kết nối; còn trình duyệt đang chạy sẽ được máy chủ của nó đóng trong vòng một chu kỳ báo cáo, khoảng 15 giây. GET trả về:
{
"id": "bs_…",
"status": "active", // see the table below
"proxy": "managed", // or "custom"
"createdAt": "…", "startedAt": "…", "endedAt": null,
"endReason": null, // set once ended, e.g. "user", "balance", "launch_failed"
"stopRequested": false,
"usage": { "bytesUp": 120334, "bytesDown": 4812009, "gb": 0.0049, "seconds": 41 },
"traffic": [ { "site": "example.com", "bytesUp": 20400, "bytesDown": 3100000 }, … ], // top 20 sites
"costEur": 0.0050,
"pricing": { "eurPerGb": 1, "eurPerHour": 0 },
"queue": { "state": null, "position": null, "ahead": null, "etaSec": null, "updatedAt": "…" } // see below
}| status | Ý nghĩa |
|---|---|
pending | Created; nobody has connected yet. Counts towards the concurrency limit until it starts or expires (45 seconds after it was created; a run waits for its server instead). |
active | A browser is running and reporting usage. |
lost | No usage report for 5 minutes. Billed up to the last report; a late report puts it back to active. If none comes, it ends an hour after the longest a session may last (see Limits and errors): status ended, endReason worker_silent. If the server that ran it restarted, it ends as soon as that server is back: endReason worker_restarted, billed up to the last report. |
ended | Closed: you disconnected, stopped it, or a limit or the balance ended it. endReason says which. A launch its geo identity refused (geoIdentity strict) ends with endReason geo_refused:<code>, e.g. geo_refused:GEO_PROXY_COUNTRY_TIMEZONE_MISMATCH, and is not billed. |
expired | Nobody connected before expiresAt (45 seconds after creating it). Never billed. |
queue cho biết một trình duyệt đang khởi động đứng ở đâu trong hàng đợi khởi chạy của máy chủ, nên một lúc bận rộn hiện ra như một vị trí trong hàng chứ không phải một lần kết nối chậm. Phản hồi tạo phiên cũng có một ước tính: "queue": { "position": 3, "etaSec": 6 }, là vị trí trình duyệt sẽ vào hàng nếu bạn kết nối ngay bây giờ (cả hai là null khi máy chủ không báo có hàng đợi).
| Trường queue | Ý nghĩa |
|---|---|
state | waiting_for_client: created, nobody has connected yet. queued: you connected and the browser waits for a launch slot on its server. launching: it is starting now. null: running, ended, or the server reported no queue in the last 30 seconds. |
position | 1-based place in the server's waiting list while queued, else null. |
ahead | How many browsers start before this one: position - 1 while queued, 0 while launching, else null. |
etaSec | Estimated seconds until it starts while queued: the browsers ahead, launched as many at a time as the server allows, at its average launch time. Else null. |
updatedAt | When the server last reported its queue (ISO time), or null when it has not in the last 30 seconds. |
Lệnh liệt kê, GET /api/v1/browsers, trả về { balanceEur, sessions: [...] } với cùng các đối tượng phiên, mới nhất xếp trước.
Giữ trình duyệt mở và kết nối lại
Mặc định, phiên kết thúc khi client của bạn ngắt kết nối. Nếu khởi động với keepAlive: true, trình duyệt sẽ tiếp tục chạy, giữ nguyên các tab, cookie và IP đầu ra, để một script sau (hoặc chính script đó sau khi bị crash hay khi bạn gập laptop) có thể tiếp tục từ chỗ lần trước dừng lại:
POST Kết nối lại
Một connect URL mới, chỉ dùng được một lần, cho một phiên keepAlive đang chạy (hãy kết nối trong vòng 45 giây). Kết nối tiếp quản lại trình duyệt ngay từ trang này, giữ nguyên mọi tab.
curl -X POST 'https://www.clearcotelabs.com/api/v1/browsers/%3Cid%3E/connect' \ -H "authorization: Bearer cc_live_..."
- Để trình duyệt tiếp tục chạy bằng cách ngắt kết nối:
browser.close()của Playwright (quaconnectOverCDPnó chỉ ngắt kết nối),browser.disconnect()của Puppeteer, hoặc đơn giản là kết thúc process của bạn. - Kết thúc phiên bằng
DELETE /api/v1/browsers/<id>, hoặc bằng cách gửi lệnh CDPBrowser.close:browser.close()của Puppeteer làm việc này, còn trong Playwright thì dùngawait (await browser.newBrowserCDPSession()).send("Browser.close"). Cho đến lúc đó, trình duyệt vẫn chiếm một slot trong giới hạn đồng thời của bạn. - Mỗi lúc chỉ một client: kết nối lại trong khi đang có client khác gắn vào sẽ bị từ chối với
409, và kết nối lại vào một phiên được khởi động không cókeepAlivecũng vậy. - Các giới hạn vẫn áp dụng khi không có ai kết nối:
idleTimeoutSec(hãy tăng lên, tối đa 1800, cho trình duyệt mà bạn định quay lại dùng),timeoutSec,maxGbvà số dư của bạn. Một trang để mở vẫn tiếp tục tải lưu lượng nền, và phần này bị tính phí như mọi lưu lượng khác.