Aller au contenu

Exemples

Des recettes à copier-coller pour les workflows Clearcote les plus courants. Partez de la plus simple qui correspond à votre cas, puis n’ajoutez des options que lorsqu’elles deviennent nécessaires.

Les recettes sont données pour les SDK Python, Node et .NET (pip install clearcote / npm install clearcote / dotnet add package Clearcote). Le SDK .NET couvre les workflows essentiels — lancement, contextes persistants, serve, proxy, geoip (Geoip = true) et canvas bridge, avec les saisies humanisées sous forme d’appels explicites HumanClickAsync / HumanTypeAsync plutôt que d’une option de lancement ; les profils enregistrés, Widevine et l’agent intégré au navigateur sont pour l’instant réservés à Python & Node.

Chaque recette exécute le build ouvert, sauf si une clé de licence est définie ; avec une clé (clearcote login, CLEARCOTE_LICENSE_KEY ou license_key=), le même code exécute le dernier build sous licence. Le plan Gratuit avec GitHub fait tourner un navigateur à la fois. Un point qui surprend souvent : le moteur ne transmet jamais les événements de console ni les erreurs de page, si bien que page.on("console") ne reçoit rien, et c’est voulu — collectez la sortie dans la page et relisez-la avec page.evaluate().

1. Lancer un navigateur vérifié depuis le SDK

À la première utilisation, le SDK télécharge le navigateur et en vérifie le SHA-256 — le build ouvert par défaut, le dernier build sous licence quand une clé est définie. Il renvoie des objets Playwright ordinaires : vous restez en terrain connu pour tout le reste de votre automatisation. (Depuis la version 0.23, launch() en Python synchrone et en Node s’exécute sur un profil jetable et new_context() renvoie ce même profil ; passez ephemeral_profile=False / ephemeralProfile: false si vous avez besoin de contextes isolés.)

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. Exposer un endpoint CDP furtif pour n’importe quel framework

serve() fait tourner Clearcote comme un endpoint CDP permanent et renvoie un cdp_url. Il lance directement le binaire — sans --enable-automation — et n’importe quel client Playwright, Puppeteer, browser-use, Crawl4AI ou Stagehand s’y attache via CDP sans modification de code. Ouvrez les pages dans contexts[0] pour utiliser le profil servi ; new_page() sur le navigateur crée un contexte distinct et isolé. Pour un agent IA, faites pointer Claude / Cursor / Cline vers le serveur clearcote-mcp (pip install clearcote-mcp, ou npx -y clearcote-mcp, qui nécessite Python 3.10+). Depuis un shell, clearcote serve expose le même endpoint et peut donner à chaque connexion sa propre identité — voir Déploiement.

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. Une identité stable par compte

Utilisez un seed déterministe et un répertoire user-data persistant. Le seed garde l’identité du navigateur stable ; le répertoire de profil conserve les cookies, le local storage, les permissions et l’état de session.

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. Aligner fuseau horaire, langue, localisation et WebRTC sur un proxy

Quand geoip est activé, Clearcote détermine l’IP de sortie du proxy en passant par ce proxy, puis renseigne le fuseau horaire, la langue, la localisation et l’adresse WebRTC laissés vides à partir d’une base GeoIP (téléchargée à la première utilisation, environ 50 Mo). Plus besoin d’associer à la main un fuseau horaire à chaque proxy. Si la région ne peut pas être déterminée dans le délai fixé par CLEARCOTE_GEOIP_TIMEOUT_SECONDS (20 par défaut), le lancement s’arrête avec GeoipError au lieu de démarrer avec l’horloge et la langue de cette machine ; définissez à la fois timezone et accept_language pour lancer malgré tout. En .NET, définissez 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. Enregistrer et réutiliser un profil nommé

Un Profile enregistré est utile quand vous voulez une persona nommée que plusieurs scripts peuvent partager. Gardez les secrets hors du contrôle de version : les fichiers de profil sont stockés en clair.

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. N’utiliser le canvas bridge que là où il compte

Le mode bridge peut être restreint par domaine enregistrable. L’exemple ci-dessous fait passer par le bridge les lectures canvas/WebGL uniquement sur les origines listées, et sert le rendu local partout ailleurs. Réglez les chaînes GPU sur celles du GPU de rendu (le renderer qu’affiche le serveur bridge), pour que le GPU annoncé corresponde aux pixels passés par le bridge. Activer le bridge fait tourner le renderer sans la sandbox de Chromium (le SDK ajoute --no-sandbox pour tout le navigateur, quel que soit le mode) : n’activez donc le bridge que dans les sessions qui en ont besoin.

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()

Démarrez d’abord l’hôte du bridge. Consultez Canvas bridge pour la commande du serveur, les recommandations réseau et le comportement de repli.

7. Lire des vidéos DRM avec Widevine

Clearcote embarque la plomberie EME, mais jamais le CDM propriétaire de Google. widevine récupère une seule fois le CDM Widevine depuis le serveur de composants de Google, le vérifie, l’installe dans le profil et l’active — si bien que requestMediaKeySystemAccess('com.widevine.alpha') aboutit et que les flux DRM se lisent, comme dans un vrai Chrome.

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()

À activer explicitement, par choix de conception — le paquet ne distribue jamais le CDM de Google ; c’est vous qui déclenchez le téléchargement unique (mis en cache sous ~/.clearcote/WidevineCdm). Fonctionne avec launch() et launch_persistent_context() en Python synchrone ; en Node, utilisez launchPersistentContext() comme ci-dessus (le type TypeScript de launch() ne déclare pas encore widevine). Pas avec le launch() asynchrone de Python, qui est en navigation privée, ni en .NET. Sécurité logicielle (L3). N’importe quelle page peut repérer un navigateur qui se présente comme Google Chrome mais ne sait pas répondre à la requête Widevine : c’est la raison de l’activer. Voir Widevine & DRM.

8. Précharger le navigateur en CI

Préchauffez le cache du navigateur vérifié avant le démarrage de votre suite de tests. Les échecs surviennent ainsi tôt, avant le lancement des jobs parallèles. Sans clé, cette étape récupère le build ouvert ; avec CLEARCOTE_LICENSE_KEY défini, elle récupère le build sous licence. Une clé du plan Gratuit avec GitHub fait tourner un navigateur à la fois : sérialisez les tests navigateur ou utilisez 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. Exécuter une tâche d’agent et en conserver la trace

L’agent intégré au navigateur s’active explicitement. Donnez-lui un répertoire de profil persistant, un endpoint et une clé compatibles OpenAI, et un nombre d’étapes borné, pour que l’exécution soit reproductible et vérifiable.

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 brut, quand vous ne voulez pas du SDK

Le SDK est la voie la plus confortable, mais le build ouvert est un binaire Chromium normal que vous pouvez lancer directement depuis Playwright ou Puppeteer. Le build sous licence nécessite le SDK — c’est lui qui détient le jeton de licence que le moteur vérifie au démarrage. Les arguments supplémentaires ci-dessous sont les valeurs par défaut que le SDK ajouterait sinon pour vous.

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();
Commencez par une recette minimale. N’ajoutez l’import de profil, le canvas bridge, le mode agent ou les surcharges GPU manuelles que lorsque votre workflow cible en a réellement besoin.