Chuyển đến nội dung

Tùy chọn và danh tính

Những gì bạn có thể đặt khi khởi động một trình duyệt hosted: các tùy chọn, mặc định stealth và danh tính, profile giữ trạng thái đăng nhập, bản phát hành được ghim và trang khởi đầu.

Tùy chọn

Tất cả đều không bắt buộc. Gửi chúng dưới dạng JSON body của lệnh tạo.

TrườngKiểuÝ nghĩa
identitystringOne label per account you run: the same device fingerprint AND the same residential IP, for as long as that IP stays online.
fingerprintstringDevice seed only (no IP pinning). The same seed gives the same device profile every time; with lightStealth on it picks from a small set of metadata profiles.
lightStealthbooleanDefault true: varies only the metadata axes the host can back up. Set false to turn it off.
platformwindowsAlways windows: the browsers run on Windows machines, and a persona of another system there reports GPU limits and fonts no such machine has. Another value starts a Windows session and warnings says so.
brandChrome | Edge | Opera | VivaldiBrowser brand the persona presents.
timezoneIANA namee.g. America/New_York. Omitted = the exit IP's. Given, it is kept as you wrote it and checked against the exit IP: under geoIdentity "strict" (the default) a time zone the exit's country does not use refuses the launch.
localestringAccept-Language, e.g. en-US,en. Omitted = a language of the exit IP's country. Given, it is kept and checked against the exit like timezone.
geoIdentity"strict" | "warn" | "auto" | "manual" | "off" | { mode?, acknowledge?, localePolicy? }Default "strict". Timezone, languages, Accept-Language, location and WebRTC address are resolved together from the exit IP, and checked against each other and against what you set, before the browser starts. strict: a contradiction refuses the launch: the connect answers 422 with the GEO_* code, and the session ends (not billed) with endReason geo_refused:<code>. warn and auto: the browser starts and the finding is reported. manual: your values as given, checked but never derived. off: the behaviour of geoip before geoIdentity. acknowledge: GEO_* codes you accept on purpose. localePolicy: "weighted" (the default: a fingerprint seed may draw any widely used language of the exit country) or "majority". The identity the browser presents is in the session.started event.
geoipbooleanOlder option, read only when geoIdentity is not set: true = geoIdentity "auto", false = "manual".
proxy"managed" | { server, username?, password? }Omitted = managed residential pool. Or your own proxy: http://, socks5:// or socks5h:// (rules below).
country2-letter codeManaged pool: exit country, e.g. us, de, gb.
stateregion codeManaged pool: exit state/region, e.g. ca, ny. Needs country.
citycity nameManaged pool: exit city, e.g. "los angeles". Needs state.
proxySessionstringManaged pool: sticky label. The same label returns the same exit IP later (kept for 24 hours).
timeoutSecnumberHard limit on the session length, in seconds (10 up to the account maximum below).
idleTimeoutSecnumberEnd the session after this long without a CDP command (10–1800).
maxGbnumberStop the session after this much traffic (0.001–1000).
headlessbooleanDefault true. With false the browser opens a real window on the server. Under the default lightStealth, the page then reports that server's own display (its whole screen, with the window maximized) instead of your identity's screen size; the identity still sets CPU cores, memory, colour depth and pixel ratio. Keep the default when the identity's screen should apply.
humanizebooleanDefault true. Your mouse moves along human paths: when a move or click lands far from the cursor, the server running the browser first walks there the way a hand would, pauses a moment before the press and holds each click for a human press time. A scroll of more than one wheel notch (100 px) arrives as whole notches at a human pace, and the page still scrolls exactly the distance you asked. Works for any client (Playwright, Puppeteer, raw CDP); drags, keys and touch are left as sent. false turns it off. See "Human input".
keepAlivebooleanDefault false. Keep the browser running when your client disconnects, until you end it (DELETE, or the CDP command Browser.close) or a limit does; reconnect with POST /api/v1/browsers/<id>/connect.
versionstringRun a specific Clearcote release, e.g. "152.0.7977.82-r21" or "r21". Omitted = the current release. See "Pinning a release".
profile"name" | { name, persist? }Load a saved profile (cookies + site storage). With persist: true, save it back when the session ends. See "Profiles".
urlhttp(s) URLOpened in the first tab before you connect: you find it already loading.
adblockbooleanRefuse known ad and tracker hosts before they load, so they are never billed. Default false.
solveSlidersbooleanDefault true. Slide-to-verify challenges are dragged for you, in any tab or frame; false leaves them to your script. See "Slider challenges".
solveCheckboxesbooleanDefault true. "Verify you are human" checkboxes are clicked for you, in any tab or frame; false leaves them to your script. See "Checkbox challenges".
solvePressHoldbooleanDefault true. "Press and hold" verification buttons are held for you until they report done, in any tab or frame; false leaves them to your script. See "Press-and-hold challenges".
challengeServicetrue | { categories?, sites?, key?, apiKey?, mode?, maxSolves?, maxSpendEur? }Default off. Challenges the free actions cannot clear go to a solving service, with your own key or ours (billed per solve). true (or no categories) auto-selects: every challenge it recognises, in token, clearance, block-page and image; or list categories and sites yourself. See "Challenge service".
recordbooleanDefault false. Record the session as an MP4; GET /api/v1/browsers/<id>/recording once it is ready (kept 14 days).
notestringYour label for the session (at most 256 characters). Shown in the dashboard; filter by it in the list.
workerstringPlace the session on the same server as an earlier one (its worker). If that server is full or offline, it starts on another one and warnings says so.

Mặc định stealth và danh tính

Mỗi phiên bắt đầu từ các thiết lập trên trang thiết lập khuyến nghị: một persona Windows (các trình duyệt chạy trên máy Windows, nên đó là hệ thống mà chúng có thể chứng thực), bật lightStealth, một seed, múi giờ và ngôn ngữ đi theo IP đầu ra dù bạn dùng proxy của mình hay của chúng tôi, module Widevine mà một Google Chrome có sẵn (nên requestMediaKeySystemAccess("com.widevine.alpha") thành công), và chuyển động chuột giống người (xem bên dưới). Với lightStealth (mặc định), seed chọn device profile từ một tập nhỏ có thay đổi số nhân CPU, bộ nhớ và pixel ratio; canvas, WebGL và audio được render bởi chính máy chạy phiên đó. Card đồ họa mà một phiên báo cho WebGL được chọn riêng cho từng phiên từ một dải các mẫu card thật cùng loại với card của máy đó, và cùng một identity sẽ báo cùng một card, nên các phiên trên cùng một máy báo các card khác nhau trong khi giới hạn WebGL và câu trả lời về codec video vẫn khớp với chúng. Đặt lightStealth: false để có persona đầy đủ theo từng seed: kết quả readback của canvas và WebGL nhận noise theo từng site từ seed, còn chuỗi GPU, màn hình và thiết lập audio (sample rate, latency) đi theo persona. Nếu không có identity hoặc fingerprint, mỗi phiên nhận một seed ngẫu nhiên và một IP mới.

Truyền identity: "account-42" để các phiên sau quay lại với cùng device profile, và cùng IP chừng nào IP dân cư đó còn online; đó chính là điều một tài khoản đã đăng nhập mong đợi. Danh tính là riêng tư trong tài khoản của bạn: một khách hàng khác dùng cùng nhãn sẽ nhận seed và IP của riêng họ. Bản thân danh tính không giữ cookie: muốn vậy, hãy dùng profile.

Nhập liệu giống người

Playwright và Puppeteer nguyên bản di chuyển chuột trong một bước nhảy: một lần di chuyển duy nhất đáp thẳng lên mục tiêu và cú click theo sau trong vòng một hai mili giây. Trình duyệt hosted làm mượt việc đó trên server, ngay cạnh trình duyệt, cho mọi client: khi một lần di chuyển hay một cú click rơi xa vị trí hiện tại của con trỏ, server trước hết đưa con trỏ tới đó theo cách một bàn tay sẽ làm (theo đường cong, với tốc độ và những chỉnh sửa nhỏ của một cử động thật), rồi mới gửi sự kiện của bạn. Thao tác nhấn đến sau khi con trỏ tới nơi một chút, như một bàn tay dừng lại cho vững, và mỗi cú click được giữ trong khoảng thời gian nhấn của người thật trước khi nhả ra. Một danh tính giữ một cách di chuyển. Script của bạn không cần thay đổi gì, và mỗi cú click chậm đi khoảng một giây.

Thao tác cuộn cũng được xử lý như vậy. Một lần cuộn dài hơn một nấc con lăn (100 px trên các máy Windows nơi trình duyệt chạy) được gửi thành các nấc trọn vẹn theo từng đợt ngắn, như một ngón tay xoay con lăn, sau khi con trỏ đã di chuyển tới điểm cuộn nếu nó đang ở chỗ khác. Trang cuộn đúng quãng đường bạn yêu cầu, nấc cuối cùng mang phần còn lại, và lệnh gọi của bạn trả về khi nấc đó đã được gửi đi.

Được giữ nguyên đúng như bạn gửi: các lần di chuyển vài pixel (một client vốn đã di chuyển theo từng bước nhỏ, như humanize của chính SDK), thao tác kéo khi đang giữ nút, lần cuộn từ một nấc con lăn trở xuống, cảm ứng và bàn phím. Truyền humanize: false khi bạn cần tốc độ gốc.

Profile: đăng nhập một lần

Profile lưu cookie, localStorage và IndexedDB của một phiên dưới một cái tên, để phiên tiếp theo dùng tên đó bắt đầu ở trạng thái đã đăng nhập. Truyền profile: { name: "shop-account", persist: true } để nạp profile và lưu lại khi phiên kết thúc, hoặc chỉ profile: "shop-account" để nạp ở chế độ chỉ đọc. Phiên đầu tiên với một tên mới sẽ bắt đầu trống và tạo ra profile đó.

javascript
// Every run: the same body. The first one starts signed out; sign in, then close the browser
// and the session saves the cookies and site storage. Every later run starts signed in.
const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
  method: "POST",
  headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
  body: JSON.stringify({ profile: { name: "shop-account", persist: true }, country: "de" }),
});
  • Cùng thiết bị, cùng IP. Một profile mang theo danh tính riêng (profile:<name>), nên site thấy cùng một fingerprint, và cùng IP dân cư chừng nào IP đó còn online, giống một khách hàng quay lại. Tự truyền identity hoặc fingerprint nếu bạn muốn chọn khác, và giữ nguyên quốc gia giữa các lần chạy.
  • Mỗi lúc chỉ một phiên được ghi. Chỉ một phiên đang chạy được lưu vào một profile; phiên thứ hai với persist: true sẽ nhận 409 PROFILE_IN_USE. Các phiên chỉ đọc có thể chạy song song và thấy trạng thái đã lưu gần nhất.
  • Được lưu khi phiên kết thúc, dù bạn đóng trình duyệt, ngắt kết nối, dừng phiên hay phiên kết thúc do chạm một giới hạn. Nếu trình duyệt bị crash, trạng thái đã lưu trước đó được giữ nguyên thay vì bị thay bằng một trạng thái không đầy đủ. Session cookie (cookie không có thời hạn) bị bỏ đi, giống như trình duyệt thật bỏ chúng khi khởi động lại.
  • Tối đa khoảng 3,5 MB sau khi nén. Nếu IndexedDB của một site khiến profile lớn hơn mức đó, IndexedDB sẽ bị bỏ ra; cookie và localStorage vẫn được lưu.
  • Riêng tư. Profile chỉ thuộc về bạn (“shop-account” của một khách hàng khác là một profile khác), được lưu dưới dạng mã hóa và chỉ được giao cho máy chủ đang chạy phiên của bạn. Liệt kê bằng GET /api/v1/browsers/profiles, xóa một profile bằng DELETE /api/v1/browsers/profiles/<name>, hoặc dùng dashboard.

Đã đăng nhập ở nơi khác rồi? Đồng bộ cookie sao chép các cookie đó vào một profile, nên ngay phiên đầu tiên cũng bắt đầu ở trạng thái đã đăng nhập.

Ghim một bản phát hành

Các phiên chạy bản phát hành Clearcote hiện tại. Để chạy một bản cũ hơn, hãy truyền version: bản phát hành đầy đủ ("156.0.8078.47-r51"), chỉ phần rebuild ("r51"), một phiên bản Chromium hoặc major ("155" chọn bản build mới nhất của major đó), hoặc "latest". Đây cũng chính là các bản phát hành mà tùy chọn version của SDK tải về, nên một phiên hosted và một lần chạy local ghim cùng một giá trị sẽ dùng cùng một bản build.

javascript
const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
  method: "POST",
  headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
  body: JSON.stringify({ identity: "account-1", version: "156.0.8078.47-r51" }),
});
const { connectUrl, engine, warnings } = await res.json();
// engine   -> { version: "156.0.8078.47", revision: "r51", pinned: true }
// warnings -> [ "This session runs 156.0.8078.47-r51, older than the current ... " ]
  • Kiểm tra warnings. Một bản phát hành cũ không có những gì các bản sau bổ sung. Các tùy chọn và bản sửa lỗi ra đời sau nó có thể bị thiếu, hoặc bị lặng lẽ bỏ qua thay vì bị từ chối, nên một thiết lập chạy được trên bản hiện tại có thể âm thầm không có tác dụng gì trên một bản đã ghim.
  • Trường engine trong response luôn cho biết phiên đang chạy bản phát hành nào, dù có ghim hay không.
  • Một bản phát hành không tồn tại sẽ trả về 400 với mã UNKNOWN_VERSION, và message liệt kê các bản phát hành bạn có thể chọn.
  • Phiên đầu tiên trên một bản phát hành mà máy chủ của chúng tôi chưa từng dùng có thể mất thêm tối đa một phút để khởi động trong lúc bản build được tải về. Các phiên sau trên bản đó khởi động nhanh như mọi phiên khác.

Trang khởi đầu và chặn quảng cáo

  • url mở một trang trong tab đầu tiên trước khi bạn kết nối, nên trang đã đang tải sẵn khi script của bạn gắn vào.
  • adblock: true từ chối các request tới những host quảng cáo, xác minh quảng cáo và analytics phổ biến trước khi chúng được gửi đi, nên chúng không bao giờ bị tính phí. Danh sách này được cố ý giữ ở mức thận trọng (tag manager, công cụ quản lý consent, SDK đăng nhập và CAPTCHA được để nguyên), nhưng một số ít site nhận ra việc thiếu quảng cáo; hãy tắt nó ở những nơi điều đó quan trọng.