Перейти к содержимому
Browsa
  1. Руководства
  2. Playwright и Puppeteer

Подключите Playwright или Puppeteer к облачному браузеру по CDP.

Облачный браузер с CDP: настоящий браузер, который работает на чужом сервере и говорит на Chrome DevTools Protocol, поэтому ваш код на Playwright или Puppeteer управляет им так же, как локальным браузером. В Browsa один вызов API запускает браузер и возвращает его CDP-адрес; вы меняете строку запуска браузера, а остальной скрипт остаётся прежним.

Время
Около 5 минут
Стоимость
1 кредит за каждые начатые 12 минут браузера, 5 за целый час
Работает с
Playwright (Python, Node), Puppeteer, любой CDP-клиент

Как запустить Playwright в облаке?

  1. Запустите браузер. POST /v1/agents (или create_agent() в SDK) запускает браузер Phantom в облаке Browsa и возвращает его id, адрес cdp_http и live_url, по которому можно смотреть браузер.
  2. Подключитесь. Замените chromium.launch() на chromium.connect_over_cdp(cdp_http, headers={"X-API-Key": API_KEY}) или puppeteer.launch() на puppeteer.connect({ browserURL, headers }). У браузера уже есть контекст и открытая страница: используйте их.
  3. Освободите ресурсы. Вызовите destroy_agent(), когда закончите, или дайте браузеру завершиться по истечении TTL. Списывается 1 кредит за каждые начатые 12 минут работы, остальной резерв возвращается.

Нужен API-ключ Browsa (начинается с agt_live_). Зарегистрируйтесь и получите 100 бесплатных кредитов после подтверждения email, без карты. Устанавливать Chrome на машину или в Docker-образ не нужно.

Подключите клиент

Playwright на Python

Терминал
pip install browsa playwright

playwright install не нужен: браузер работает в Browsa.

cloud_playwright.py
import os

from browsa import Client
from playwright.sync_api import sync_playwright

API_KEY = os.environ["BROWSA_API_KEY"]
client = Client(api_key=API_KEY)
agent = client.create_agent(ttl="10m")  # a cloud browser, up to 10 minutes

try:
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(
            agent["cdp_http"], headers={"X-API-Key": API_KEY}
        )
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        print(page.title())
        # the rest is plain Playwright
finally:
    client.destroy_agent(agent["id"])

Playwright на TypeScript или Node

Терминал
npm i browsa playwright
cloud-playwright.ts
import { Client } from "browsa";
import { chromium } from "playwright";

const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "10m" });

try {
  const browser = await chromium.connectOverCDP(agent.cdp_http, {
    headers: { "X-API-Key": apiKey },
  });
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  await client.destroyAgent(agent.id);
}

Puppeteer

Используйте puppeteer-core. У него тот же API, что у puppeteer, но он не скачивает браузер, который вам больше не нужен.

Терминал
npm i browsa puppeteer-core
cloud-puppeteer.ts
import { Client } from "browsa";
import puppeteer from "puppeteer-core";

const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "5m" });

try {
  const browser = await puppeteer.connect({
    browserURL: agent.cdp_http,
    headers: { "X-API-Key": apiKey },
  });
  const [page] = await browser.pages();
  await page.goto("https://example.com");
  console.log(await page.title());
  await browser.disconnect();
} finally {
  await client.destroyAgent(agent.id);
}

Чистый CDP и другие клиенты

Ответ на создание содержит два адреса. cdp_http: HTTP-эндпоинт браузера, его ждут Playwright и Puppeteer. cdp_url: WebSocket одной страницы, для клиентов, которые работают с CDP напрямую. Обоим нужен ваш ключ в заголовке X-API-Key. Тот же адрес подойдёт любой библиотеке, которая умеет подключаться к запущенному браузеру по CDP с собственным заголовком; так работают руководства по browser-use и Stagehand.

Без SDK запустите браузер обычным HTTP-запросом:

curl
curl https://browsa.io/v1/agents \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl": "10m", "initial_url": "https://example.com"}'

# -> { "id": "agt_…", "status": "running", "cdp_http": "https://browsa.io/api/v1/cdp/…",
#      "cdp_url": "wss://browsa.io/api/v1/cdp/…/ws/page/…", "live_url": "…", "cost_credits": 5 }

cost_credits показывает, сколько браузер резервирует, пока работает: 1 кредит для TTL до 5 минут, 5 для более долгого. Когда он завершается, неиспользованные блоки по 12 минут возвращаются на баланс.

Что работает иначе, чем в локальном браузере?

Размер окна и user agent

Размер экрана, user agent, часовой пояс, язык, геолокация и число ядер CPU задаются вместе при запуске браузера. Команды эмуляции CDP, которые меняют что-то одно, возвращают успех и ничего не меняют, поэтому page.set_viewport_size(), page.setViewport() и page.setUserAgent() не действуют.

Что делатьПередайте screen_resolution и os_type в POST /v1/agents. Чтобы управлять эмуляцией самим, добавьте cdp_overrides=allow в query CDP-адреса; за согласованность отпечатка тогда отвечаете вы.

Контексты и страницы

Браузер запускается с контекстом и открытой страницей.

Что делатьИспользуйте browser.contexts[0] и его первую страницу, а не создавайте новый контекст.

Загрузка файлов

Скачанные файлы остаются в облачном браузере, а событие download в Playwright сообщает canceled.

Что делатьПолучите файл внутри страницы (см. ниже), с cookies и IP-адресом браузера.

Время жизни

Браузер работает до конца TTL, максимум 1 час, или пока вы его не удалите. Из-за простоя он не завершается.

Что делатьЗапрашивайте нужный TTL (от "5m" до "1h"). Для долгих задач запускайте новый браузер или используйте сохранённый профиль, чтобы логины сохранялись между ними.

Сеть

Без прокси трафик выходит из дата-центра Browsa с IP-адресом дата-центра.

Что делатьПередайте сеть Browsa в proxy ({"network": "residential"}), свой HTTP-, HTTPS- или SOCKS5-прокси или сохранённый прокси в proxy_id.

Признаки автоматизации

Playwright и Puppeteer при подключении включают домен Runtime в CDP, и некоторые проверки на ботов это видят.

Что делатьЕсли сайт помечает ваш клиент, попробуйте чистый CDP-клиент без Runtime.enable или собственного агента Browsa (POST /v1/tasks). Результаты с датами есть на странице бенчмарков.

Параллельные браузеры

6 слотов для браузеров на рабочее пространство. Запрос при занятых слотах возвращает 429 с Retry-After: 30 и не оплачивается.

Что делатьСтавьте задачи в очередь на своей стороне или напишите на support@browsa.io, чтобы получить больше слотов.

Как переподключиться после обрыва?

Закрытие соединения Playwright или Puppeteer не останавливает браузер. Он работает до конца TTL, так что к нему может подключиться другой процесс. Получите его адрес снова через GET /v1/agents/{id}/cdp (или get_agent(agent_id) в Python, getAgent(agentId) в TypeScript) и подключитесь с тем же заголовком X-API-Key. Если браузер уже не работает, эндпоинт возвращает 409.

Как скачать файл?

Получите его изнутри страницы и верните байты:

Python
import base64

b64 = page.evaluate("""async (url) => {
  const buf = new Uint8Array(await (await fetch(url)).arrayBuffer());
  let s = ""; for (const b of buf) s += String.fromCharCode(b);
  return btoa(s);
}""", "https://example.com/report.pdf")
open("report.pdf", "wb").write(base64.b64decode(b64))

Как использовать свой прокси?

Добавьте объект proxy при запуске браузера. Браузер будет использовать IP-адрес прокси, а если задан country, его часовой пояс и язык подстроятся под эту страну. Трафик через прокси в Browsa ничего дополнительно не стоит.

curl
curl https://browsa.io/v1/agents \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": "10m",
    "proxy": {"type": "http", "host": "proxy.example.com", "port": 8080,
              "username": "your-proxy-user", "password": "your-proxy-password"},
    "country": "de"
  }'

Браузер запускается, даже если прокси недоступен, поэтому сначала проверьте его. У сохранённого прокси есть эндпоинт проверки, и его можно передать как proxy_id.

Как сохранять логины между запусками?

Используйте постоянный профиль вместо одноразового браузера. Он хранит cookies, local storage и отпечаток между сессиями. Создайте его один раз с "mode": "persistent", а затем открывайте сессию, когда она нужна скрипту: POST /v1/agents/{id}/sessions возвращает то же, что и новый браузер, включая cdp_http, и подключение работает точно так же. Профиль стоит 50 кредитов каждые 30 дней, а каждая сессия 1 кредит. См. Открытие сессии.

Сколько это стоит?

Что вы запускаетеКредиты
Браузер, работающий до 12 минут1
Браузер, работающий целый час5
Постоянный профиль, каждые 30 дней50
Сессия на постоянном профиле (до 1 часа)1
Браузер, который не запустилсяВозврат

Один кредит стоит $0.10 в пакете Starter за $20 и дешевле в больших пакетах. Кредиты не сгорают. Все цены.

Решение проблем

401 Unauthorized при подключении

Заголовок X-API-Key не дошёл до Browsa, или ключ неверный. Передавайте его при подключении точно как в примерах и проверьте, что ключ начинается с agt_.

402 при запуске браузера

INSUFFICIENT_CREDIT значит, что баланса не хватает на запрошенный TTL; BUDGET_REACHED значит, что достигнут месячный лимит расходов. Проверьте GET /v1/credits и GET /v1/budget.

Соединение обрывается через несколько минут

Браузер дошёл до конца TTL. Запросите более долгий, до "1h".

Вопросы

Почему set_viewport_size() не меняет браузер?

Размер экрана, user agent, часовой пояс, язык и геолокация браузера Browsa задаются вместе при его создании, чтобы страница видела одну согласованную машину. Команды эмуляции CDP, которые меняют что-то одно, возвращают успех и ничего не меняют. Задайте screen_resolution и os_type при создании браузера или добавьте cdp_overrides=allow к CDP-адресу, если хотите управлять эмуляцией сами.

Как скачать файл из облачного браузера?

Файлы, которые скачивает страница, остаются в облачном браузере, а Playwright сообщает, что загрузка отменена. Получите файл изнутри страницы через page.evaluate(), с cookies и IP-адресом браузера, и верните байты в base64.

Сколько браузеров может работать одновременно?

У рабочего пространства 6 слотов для браузеров. Каждый работающий браузер занимает один, как и каждый сохранённый профиль. Новый браузер при занятых слотах возвращает 429 TOO_MANY_REQUESTS с Retry-After: 30, и ничего не списывается. Если нужно больше, напишите на support@browsa.io.

Browsa предоставляет прокси?

Да. Прокси дата-центра стоят 5 кредитов за ГБ, резидентные 50 кредитов за ГБ. Или передайте свой HTTP-, HTTPS- или SOCKS5-прокси для каждого браузера, бесплатно. Без прокси браузер использует IP-адрес дата-центра Browsa.

Что дальше

Запустите свой скрипт в облачном браузере.

100 бесплатных кредитов. Без карты и подписки.