Integrating with Puppeteer — Airtop

Puppeteer is a popular automation library for Node.js that allows you to control headless browsers. Airtop provides a Puppeteer connector that allows you to use Puppeteer to automate your browser.

Puppeteer is not supported in Python. We recommend using Playwright or Selenium instead.

Installation

You will need to install the puppeteer-core package to use Puppeteer with Airtop.

$ npm i puppeteer-core

Usage

Once you have created a session with Airtop, you can use the puppeteer-core package to control the browser by connecting Puppeteer to the CDP endpoint provided by Airtop.

1 import puppeteer from "puppeteer-core";
2 
3 const session = await client.sessions.create();
4 const puppeteerBrowser = await puppeteer.connect({
5   browserWSEndpoint: session.data?.cdpWsUrl,
6   headers: {
7     authorization: `Bearer YOUR_API_KEY`,
8   },
9 });
10 
11 // Navigate to a page
12 const page = await browser.newPage();
13 await page.goto('https://airtop.ai');
14 
15 // Get the page content
16 const content = await page.content();
17 console.log(content);

If you’re not already familiar with Puppeteer, you might want to check out their documentation to learn more about the library and its capabilities.

Combining Puppeteer and Airtop Window Management

You can use Airtop’s window management functions in combination with Puppeteer to automate your browser. For example, you might want to create a new window, load a URL in it, use our AI APIs, but use Puppeteer to push a few buttons on the page.

Once you create a window, you’ll be given a window ID, which you’ll use to interact with the window using Airtop’s SDK. But you’ll also be given a targetId, which you’ll use to connect Puppeteer to the window.

1 const windowResponse = await client.windows.create(session.data.id, { url: "https://www.airtop.ai", waitUntil: "load" });
2 
3 // Get the target ID from the window response
4 const { targetId } = windowResponse.data;
5 
6 // Connect to the session using Puppeteer
7 const puppeteerBrowser = await puppeteer.connect({
8   browserWSEndpoint: session.data?.cdpWsUrl,
9   headers: {
10     authorization: `Bearer YOUR_API_KEY`,
11   },
12 });
13 
14 
15 // Iterate through the pages to find the one that matches the target ID
16 const pages = await puppeteerBrowser.pages();
17 let matchingPage;
18 for (const page of pages) {
19   const pageTargetId = await (page.mainFrame() as any)._id;
20   if (pageTargetId === targetId) {
21     matchingPage = page;
22     break;
23   }
24 }
25 
26 // Once the page is found you can use Puppeteer to interact with it
27 if (matchingPage) {
28   await matchingPage.click("button");
29 }

Common Errors

Here are some common errors you might encounter when using Puppeteer with Airtop when you initially connect to the CDP endpoint:

Error Code	Common Cause
400	Bad request. Check that you specify the essential parts of the request. For example, is there an “Authorization: Bearer API_KEY” header with a valid airtop API key
401	Unauthorized. Check that you are using a valid API key.
404	Not found. Check that the session ID you specified in your request is correct, and that the url path is correct
422	Unprocessable Content. Check that your inputs are well-formed. For example, is your session ID a valid UUID?
503	Service Unavailable. The session is valid, but it cannot be connected to. Check whether the session has timed out or that you haven’t already terminated it.

1	import puppeteer from "puppeteer-core";
2
3	const session = await client.sessions.create();
4	const puppeteerBrowser = await puppeteer.connect({
5	browserWSEndpoint: session.data?.cdpWsUrl,
6	headers: {
7	authorization: `Bearer YOUR_API_KEY`,
8	},
9	});
10
11	// Navigate to a page
12	const page = await browser.newPage();
13	await page.goto('https://airtop.ai');
14
15	// Get the page content
16	const content = await page.content();
17	console.log(content);

1	const windowResponse = await client.windows.create(session.data.id, { url: "https://www.airtop.ai", waitUntil: "load" });
2
3	// Get the target ID from the window response
4	const { targetId } = windowResponse.data;
5
6	// Connect to the session using Puppeteer
7	const puppeteerBrowser = await puppeteer.connect({
8	browserWSEndpoint: session.data?.cdpWsUrl,
9	headers: {
10	authorization: `Bearer YOUR_API_KEY`,
11	},
12	});
13
14
15	// Iterate through the pages to find the one that matches the target ID
16	const pages = await puppeteerBrowser.pages();
17	let matchingPage;
18	for (const page of pages) {
19	const pageTargetId = await (page.mainFrame() as any)._id;
20	if (pageTargetId === targetId) {
21	matchingPage = page;
22	break;
23	}
24	}
25
26	// Once the page is found you can use Puppeteer to interact with it
27	if (matchingPage) {
28	await matchingPage.click("button");
29	}