Practical Social Browser automation examples

External tools

Set up an API / CDP client

1
Open API Clients
Inside Social Browser open browser://local/settings/api-clients. This is the source of truth for the endpoint and security options supported by the installed build.
2
Enable only the client access you need
Keep developer access local unless you deliberately configure a trusted network path. Treat any API key/token as a secret.
3
Copy the local endpoint from the browser
The examples below use the standard local debugging address http://127.0.0.1:60101. If the API Clients screen shows another endpoint, use the value shown by your browser.
4
Discover the live browser and targets
Query the Chromium discovery endpoints or connect with Puppeteer. Resolve live targets each time you connect.

Check that the browser endpoint is available

curl http://127.0.0.1:60101/json/version curl http://127.0.0.1:60101/json/list

PowerShell on Windows

$base = "http://127.0.0.1:60101" $version = Invoke-RestMethod "$base/json/version" $targets = Invoke-RestMethod "$base/json/list" $version $targets | Select-Object id, type, title, url

Node.js discovery without Puppeteer

const base = "http://127.0.0.1:60101"; const version = await fetch(`${base}/json/version`).then(r => r.json()); const targets = await fetch(`${base}/json/list`).then(r => r.json()); console.log("Browser:", version.Browser); console.table(targets.map(t => ({ id: t.id, type: t.type, title: t.title, url: t.url, })));

/json/version describes the running browser/debugging endpoint. /json/list returns currently discoverable targets. A target is runtime state, not a durable Profile identifier.

Do not persist target IDs. If Social Browser restarts, a tab is recreated, or a runtime reconnect occurs, resolve the target again by current Profile/tab context, URL, title or another durable resource identity available to your integration.

Trusted User Scripts

Use `SOCIALBROWSER.page` inside the current tab

Trusted Social Browser User Scripts receive the global SOCIALBROWSER object. SOCIALBROWSER.page gives you JavaScript-only, Puppeteer-inspired helpers for the exact tab where the script is running. You do not need a separate Node.js process for this path.

const page = SOCIALBROWSER.page; const email = await page.waitForSelector("#email", { visible: true, timeout: 10000, }); if (!email) return null; await page.type("#email", "name@example.com", { clear: true }); await page.type("#password", "placeholder-password", { clear: true }); await page.click('button[type="submit"]'); return await page.waitForSelector(".dashboard, .login-error", { visible: true, timeout: 15000, });

Area	Common helpers	Use
Page actions	`click`, `dblclick`, `rightClick`, `hover`, `focus`	Interact with elements.
Input	`type`, `setValue`, `clear`, `selectOption`, `check`	Forms and editable controls.
Waiting	`waitForSelector`, `waitForFunction`, `waitForTimeout`, `waitForGone`	Synchronize with page state.
Querying	`$`, `$$`, `$eval`, `$$eval`, `findDeep`	Find and read DOM content.
Scrolling	`scroll`, `scrollTo`, `scrollToElement`, `scrollHuman`	Move the viewport.
Devices	`mouse`, `keyboard`, `touchscreen`, `cursor`	Lower-level input control.
Locator	`locator(...)`	Keep a target together across wait/fill/focus/click steps.

See the complete SOCIALBROWSER.page method reference and examples →

Main Process bridge

Run real Puppeteer against the exact current tab

SOCIALBROWSER.page.runPuppeteer() is intended for trusted User Scripts. The callback runs with real Puppeteer in the Main Process and Social Browser resolves the current renderer to the matching Puppeteer target.

const result = await SOCIALBROWSER.page.runPuppeteer( async (browser, page, args) => { await page.screenshot({ path: args.path }); return { title: await page.title(), url: page.url(), heading: await page.$eval("h1", node => node.textContent.trim()), }; }, { path: "C:/temp/social-browser-page.png" }, ); console.log(result);

The bridge connects Puppeteer with defaultViewport: null and resolves the exact target using the current Chromium debugger target information. The embedded debugger attaches through CDP protocol version 1.3 when needed.

Compatibility: this is real Puppeteer, but not every Puppeteer feature is guaranteed in every embedded Chromium/Electron build. Features that depend on unsupported CDP domains can be unavailable.

Complete examples

Practical workflow patterns

Read a dashboard value

const page = SOCIALBROWSER.page; const dashboard = await page.waitForSelector(".dashboard", { visible: true, timeout: 15000, }); if (!dashboard) return null; return await page.$eval("[data-balance]", node => node.textContent.trim() );

Wait for a loader, then collect rows

const page = SOCIALBROWSER.page; await page.waitForGone(".loading-overlay", { timeout: 20000 }); return (await page.$$eval("table tbody tr", rows => rows.map(row => Array.from(row.cells, cell => cell.textContent.trim())) )) || [];

External QA check through Puppeteer

const puppeteer = require("puppeteer-core"); const browser = await puppeteer.connect({ browserURL: "http://127.0.0.1:60101", defaultViewport: null, }); try { const page = (await browser.pages()).find(p => p.url().includes("example.com") ); if (!page) throw new Error("Expected page is not open"); const result = { title: await page.title(), url: page.url(), hasMain: await page.$("main") !== null, }; console.log(result); } finally { await browser.disconnect(); }