Chuyển đến nội dung

Ví dụ

Các đoạn code mẫu copy-paste được ngay cho những workflow Clearcote phổ biến. Hãy bắt đầu từ mẫu nhỏ nhất khớp với công việc của bạn, rồi chỉ thêm tùy chọn khi thực sự cần.

Các mẫu có sẵn cho SDK Python, Node và .NET (pip install clearcote / npm install clearcote / dotnet add package Clearcote). SDK .NET hỗ trợ các workflow cốt lõi — launch, persistent context, serve, proxy, geoip (Geoip = true) và canvas bridge, còn thao tác nhập giống người thật (humanized input) là các lệnh gọi tường minh HumanClickAsync / HumanTypeAsync thay vì một cờ khi launch; profile đã lưu, Widevine và agent trong trình duyệt hiện chỉ có trên Python & Node.

Mọi mẫu đều chạy bản build mở trừ khi bạn đặt khóa giấy phép; khi có khóa (clearcote login, CLEARCOTE_LICENSE_KEY hoặc license_key=), cùng đoạn code đó sẽ chạy bản build có giấy phép mới nhất. Gói “Miễn phí với GitHub” chạy mỗi lúc một trình duyệt. Một điều khiến nhiều người bất ngờ: engine không bao giờ chuyển tiếp các sự kiện console hay lỗi trang, nên theo thiết kế page.on("console") không nhận được gì — hãy thu thập output trong trang rồi đọc lại bằng page.evaluate().

1. Khởi động trình duyệt đã xác minh từ SDK

Ở lần dùng đầu tiên, SDK tải trình duyệt về và xác minh SHA-256 — mặc định là bản build mở, còn khi có đặt khóa thì là bản build có giấy phép mới nhất. SDK trả về các đối tượng Playwright bình thường, nên phần còn lại của code automation vẫn quen thuộc như cũ. (Từ 0.23, launch() trong Python sync và Node chạy trên một profile tạm, dùng xong là bỏ, và new_context() trả về chính profile đó; hãy truyền ephemeral_profile=False / ephemeralProfile: false nếu bạn cần các context tách biệt.)

from clearcote import launch

browser = launch(fingerprint="demo:user-1", platform="windows", headless=False)
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

2. Chạy một CDP endpoint stealth cho mọi framework

serve() chạy Clearcote như một CDP endpoint thường trực và trả về một cdp_url. Nó khởi chạy trực tiếp binary — không có --enable-automation — và mọi client Playwright, Puppeteer, browser-use, Crawl4AI hay Stagehand đều gắn vào qua CDP mà không phải sửa code. Mở trang trong contexts[0] để dùng profile đang được serve; new_page() trên browser sẽ tạo một context riêng, tách biệt. Với AI agent, hãy trỏ Claude / Cursor / Cline tới server clearcote-mcp (pip install clearcote-mcp, hoặc npx -y clearcote-mcp, cách này cần Python 3.10+). Từ shell, clearcote serve chạy cùng endpoint đó và có thể cấp cho mỗi kết nối một danh tính riêng — xem Triển khai.

from clearcote import serve
from playwright.sync_api import sync_playwright

srv = serve(fingerprint="demo:user-1", platform="windows")   # same persona options as launch()
print(srv.cdp_url)                                           # http://127.0.0.1:<port>

browser = sync_playwright().start().chromium.connect_over_cdp(srv.cdp_url)
page = browser.contexts[0].new_page(); page.goto("https://example.com"); print(page.title())
srv.close()

3. Mỗi tài khoản một danh tính ổn định

Dùng một seed cố định (deterministic) và một thư mục user-data lưu lâu dài. Seed giữ cho danh tính trình duyệt ổn định; thư mục profile giữ cookie, local storage, quyền (permissions) và trạng thái phiên.

from clearcote import launch_persistent_context

account_id = "acct_42"

ctx = launch_persistent_context(
    rf"C:\clearcote\profiles\{account_id}",
    fingerprint=f"acct:{account_id}",
    platform="windows",
    timezone="America/New_York",
    accept_language="en-US,en",
    humanize=True,
)
page = ctx.new_page()
page.goto("https://example.com/dashboard")
ctx.close()

4. Khớp múi giờ, ngôn ngữ, vị trí và WebRTC với proxy

Khi bật geoip, Clearcote tìm IP đầu ra của proxy thông qua chính proxy đó, rồi điền múi giờ, ngôn ngữ, vị trí và địa chỉ WebRTC còn chưa đặt từ một cơ sở dữ liệu GeoIP (tải về ở lần dùng đầu, khoảng 50 MB). Nhờ vậy bạn không phải tự khớp múi giờ cho từng proxy. Nếu không xác định được khu vực trong vòng CLEARCOTE_GEOIP_TIMEOUT_SECONDS (mặc định 20), lần launch sẽ dừng với GeoipError thay vì khởi động với đồng hồ và ngôn ngữ của máy này; hãy đặt cả timezone và accept_language nếu vẫn muốn launch. Trong .NET, đặt Geoip = true.

from clearcote import launch

browser = launch(
    fingerprint="proxy:nyc:001",
    platform="windows",
    proxy={"server": "http://host:8080", "username": "user", "password": "pass"},
    geoip=True,
)
page = browser.new_page()
page.goto("https://browserleaks.com/webrtc")
browser.close()

5. Lưu và dùng lại một profile có tên

Profile đã lưu hữu ích khi bạn muốn có một persona có tên để nhiều script dùng chung. Đừng đưa bí mật vào source control: file profile là plaintext.

from clearcote import Profile, launch

Profile("support-agent", {
    "fingerprint": "support-agent",
    "platform": "windows",
    "timezone": "America/Chicago",
    "accept_language": "en-US,en",
    "storage_quota": 120000,
}).save()

browser = launch(profile="support-agent", headless=False)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

6. Chỉ dùng canvas bridge ở nơi cần thiết

Chế độ bridge có thể giới hạn theo registrable domain. Ví dụ dưới đây chỉ bridge các readback canvas/WebGL trên những origin được liệt kê và render cục bộ ở mọi nơi khác. Đặt chuỗi GPU theo GPU dùng để render (renderer mà bridge server in ra), để GPU được báo cáo khớp với các pixel được bridge. Bật bridge sẽ chạy renderer không có sandbox của Chromium (SDK thêm --no-sandbox cho toàn bộ trình duyệt, bất kể chế độ nào), nên chỉ bật bridge trong những phiên thực sự cần.

from clearcote import launch

browser = launch(
    fingerprint="gpu:nvidia:seat-1",
    gpu_vendor="Google Inc. (NVIDIA)",                          # as printed by the bridge server
    gpu_renderer="ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 (0x00002504) Direct3D11 vs_5_0 ps_5_0, D3D11)",
    canvas_bridge={
        "url": "ws://127.0.0.1:8443",
        "auth": "user:secret",
        "mode": "allow",
        "allow": ["example.com", "browserleaks.com"],
        "fallback": "local",
    },
)
page = browser.new_page()
page.goto("https://browserleaks.com/canvas")
browser.close()

Hãy khởi động bridge host trước. Xem Canvas bridge để biết lệnh chạy server, hướng dẫn về mạng và cách fallback hoạt động.

7. Phát video DRM với Widevine

Clearcote có sẵn phần hạ tầng EME nhưng không bao giờ đi kèm CDM độc quyền của Google. widevine tải Widevine CDM một lần từ component server của Google, xác minh nó, nạp sẵn vào profile rồi bật lên — nhờ đó requestMediaKeySystemAccess('com.widevine.alpha') resolve thành công và các luồng DRM phát được, giống như một Chrome thật.

from clearcote import launch_persistent_context

ctx = launch_persistent_context("C:\\clearcote\\profile-drm", widevine=True)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://example.com")
# requestMediaKeySystemAccess('com.widevine.alpha') now resolves; DRM playback works
ctx.close()

Được thiết kế theo kiểu opt-in — package không bao giờ phân phối CDM của Google; chính bạn kích hoạt lần tải duy nhất đó (được cache tại ~/.clearcote/WidevineCdm). Hoạt động với launch() và launch_persistent_context() trong Python sync; trong Node, hãy dùng launchPersistentContext() như trên (kiểu TypeScript của launch() chưa khai báo widevine). Không dùng được với launch() async của Python, vốn chạy ở chế độ incognito, và cũng không dùng được trong .NET. Mức bảo mật bằng phần mềm (L3). Một trình duyệt tự nhận là Google Chrome nhưng không trả lời được truy vấn Widevine thì bất kỳ trang nào cũng đọc ra được, và đó là lý do nên bật tính năng này. Xem Widevine & DRM.

8. Tải trước trình duyệt trong CI

Làm nóng cache trình duyệt đã xác minh trước khi bộ test chạy. Nhờ vậy lỗi sẽ lộ ra sớm, trước khi các job song song bắt đầu. Không có khóa, bước này tải bản build mở; khi đã đặt CLEARCOTE_LICENSE_KEY, nó tải bản build có giấy phép. Khóa của gói “Miễn phí với GitHub” chỉ chạy một trình duyệt tại một thời điểm, vì vậy hãy chạy tuần tự các test trình duyệt hoặc dùng Pro.

- name: Install dependencies
  run: |
    python -m pip install clearcote

- name: Prefetch verified Clearcote
  run: |
    clearcote install
    clearcote info --quick

- name: Run tests
  run: |
    pytest

9. Chạy một tác vụ agent và giữ lại trace

Agent trong trình duyệt là tính năng opt-in. Hãy cung cấp cho nó một thư mục profile lưu lâu dài, một endpoint/key tương thích OpenAI và một số bước giới hạn, để lần chạy có thể tái lập và dễ xem lại.

import os
from clearcote import launch_agent, run_agent_task

ctx = launch_agent(
    os.path.expanduser("~/.clearcote/agent-demo"),   # the profile directory
    fingerprint="agent-demo",
    agent_llm_key="sk-or-...",
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(page, "Find the contact page and summarize the email address", max_steps=12)
print(result["success"])
print(result["finalText"])
print(result["stepsJson"])
ctx.close()

10. Playwright thuần khi bạn không muốn dùng SDK

SDK là cách tiện nhất, nhưng bản build mở là một binary Chromium bình thường mà bạn có thể launch trực tiếp từ Playwright hoặc Puppeteer. Bản build có giấy phép thì cần SDK — SDK giữ token giấy phép mà engine kiểm tra khi khởi động. Các tham số bổ sung bên dưới chính là những giá trị mặc định mà SDK lẽ ra sẽ tự thêm cho bạn.

javascript
import { chromium } from "playwright";

const browser = await chromium.launch({
  executablePath: "C:\\clearcote\\chrome.exe",
  headless: false,
  ignoreDefaultArgs: ["--enable-automation", "--enable-unsafe-swiftshader"],   // the SDK strips these two by default
  args: [
    "--fingerprint=raw-playwright-demo",
    "--fingerprint-platform=windows",
    "--fingerprint-brand=chrome",
    "--timezone=America/New_York",
    "--accept-lang=en-US,en",
    "--lang=en-US",
    "--webrtc-ip-handling-policy=disable_non_proxied_udp",
    "--ignore-gpu-blocklist",   // the SDK pairs this with the SwiftShader strip so WebGL keeps working
  ],
});

const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();
Trước hết hãy giữ mẫu thật nhỏ gọn. Chỉ thêm import profile, canvas bridge, chế độ agent hay ghi đè GPU thủ công khi workflow của bạn thực sự cần đến.