Puppeteer

Puppeteer connects to a Surfsky browser over the session’s WebSocket URL instead of launching one itself. The browser runs in Surfsky’s cloud, so you do not need Chrome on your machine.

Puppeteer has known leaks that anti-bot scripts can detect. On sites with bot protection, use a patched fork such as rebrowser-puppeteer.

Use human-emulation commands for clicks, typing, and scrolling. Keep Puppeteer for navigation, selectors, waiting, and page content.

Prerequisites

Set your API token and base URL, then install the package for your language below. Puppeteer provides a JavaScript/TypeScript API. The Java and .NET examples use the community ports Jvppeteer and Puppeteer Sharp. For Python, use async Playwright: the Python port Pyppeteer is unmaintained. The examples use your account’s default proxy pool. Proxy, fingerprint, and other start options are in the API reference.

Run an example

The examples use a one-time profile. To reuse a saved login, pass a persistent profile UUID to the session call instead.

JavaScript
Java (Jvppeteer)
.NET (Puppeteer Sharp)

Requires Node.js 24 or newer, or Bun, for await using. Puppeteer’s JavaScript API is asynchronous; the same calls work in TypeScript.

npm install surfsky puppeteer-core

Save as surfsky-puppeteer.mjs:

import puppeteer from "puppeteer-core";
import { Surfsky } from "surfsky";

const client = new Surfsky();
await using session = await client.session();
const browser = await puppeteer.connect({
  browserWSEndpoint: session.ws_url,
  defaultViewport: null,
});
try {
  const page = (await browser.pages())[0] ?? (await browser.newPage());
  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  await browser.disconnect();
}

Run it:

node surfsky-puppeteer.mjs

Requires Java 11 or newer. Add the dependency to your Maven project:

<dependency>
  <groupId>io.github.fanyong920</groupId>
  <artifactId>jvppeteer</artifactId>
  <version>3.6.5</version>
</dependency>

Start a browser with the REST quickstart and export its ws_url as SURFSKY_WS_URL:

import com.ruiyun.jvppeteer.api.core.Browser;
import com.ruiyun.jvppeteer.api.core.Page;
import com.ruiyun.jvppeteer.cdp.core.Puppeteer;
import com.ruiyun.jvppeteer.cdp.entities.ConnectOptions;
import com.ruiyun.jvppeteer.cdp.entities.Protocol;

public class SurfskyExample {
    public static void main(String[] args) throws Exception {
        ConnectOptions options = new ConnectOptions();
        options.setBrowserWSEndpoint(System.getenv("SURFSKY_WS_URL"));
        options.setProtocol(Protocol.CDP);
        options.setDefaultViewport(null);
        Browser browser = Puppeteer.connect(options);
        try {
            var pages = browser.pages();
            Page page = pages.isEmpty() ? browser.newPage() : pages.get(0);
            page.goTo("https://example.com");
            System.out.println(page.title());
        } finally {
            browser.close();
        }
    }
}

dotnet add package PuppeteerSharp

Start a browser with the REST quickstart and export its ws_url as SURFSKY_WS_URL. Put this in Program.cs:

using PuppeteerSharp;

var browser = await Puppeteer.ConnectAsync(new ConnectOptions
{
    BrowserWSEndpoint = Environment.GetEnvironmentVariable("SURFSKY_WS_URL"),
    DefaultViewport = null,
});
try
{
    var pages = await browser.PagesAsync();
    var page = pages.Length > 0 ? pages[0] : await browser.NewPageAsync();
    await page.GoToAsync("https://example.com");
    Console.WriteLine(await page.GetTitleAsync());
}
finally
{
    await browser.CloseAsync();
}

Run with dotnet run.

Expected output:

Example Domain

defaultViewport: null keeps the window size from the profile’s fingerprint. Without it Puppeteer forces its own 800x600 viewport.

Click, type, and scroll

Prefer human emulation over Puppeteer’s own click, type, and scroll. Human.* commands move the cursor and type with human timing, and they run through a page-level CDP session. Replace the selector with an input on your page:

const cdp = await page.createCDPSession();
await cdp.send("Human.click", { selector: "input[name='email']" });
await cdp.send("Human.type", { text: "[email protected]" });
await cdp.send("Human.scroll", { deltaY: 600, duration: 1.2 });

var cdp = page.createCDPSession();
cdp.send("Human.click", java.util.Map.of("selector", "input[name='email']"));
cdp.send("Human.type", java.util.Map.of("text", "[email protected]"));
cdp.send("Human.scroll", java.util.Map.of("deltaY", 600, "duration", 1.2));

var cdp = await page.CreateCDPSessionAsync();
await cdp.SendAsync("Human.click", new { selector = "input[name='email']" });
await cdp.SendAsync("Human.type", new { text = "[email protected]" });
await cdp.SendAsync("Human.scroll", new { deltaY = 600, duration = 1.2 });

Stop the session

In the JavaScript example, browser.disconnect() only drops the Puppeteer connection; the SDK stops the browser when the session scope exits, including on errors. The Java and .NET examples close the remote browser in finally. If you start a session through the API and the framework cannot connect, stop it using the internal_uuid from the start response:

curl --fail-with-body -X POST \
  "$SURFSKY_API_BASE_URL/profiles/INTERNAL_UUID/stop" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN"

Otherwise the browser stops after the inactivity timeout.

Get started

Connect your tools

Browser sessions

Browser actions

CAPTCHA guides

Debugging

Performance and limits

About Surfsky

Prerequisites

Run an example

Click, type, and scroll

Stop the session

​Prerequisites

​Run an example

​Click, type, and scroll

​Stop the session

Prerequisites

Run an example

Click, type, and scroll

Stop the session