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 →
Reliability
Lifecycle and target-selection rules
Find the intended target immediately before use instead of caching a runtime target for a long time.
A restart/reconnect can create new runtime IDs even when the persistent Profile is the same.
Check URL/title/Profile context before sending an action in a multi-Profile session.
Navigation can rebuild a renderer/CDP frame. Your code should wait for the new page state instead of assuming the old frame remains valid.
async function findTargetPage(browser, expectedUrlPrefix) { const pages = await browser.pages(); const page = pages.find(p => p.url().startsWith(expectedUrlPrefix)); if (!page) throw new Error("Target is not available"); return page; } let page = await findTargetPage(browser, "https://example.com/"); await page.goto("https://example.com/dashboard"); // Resolve/validate again when your workflow crosses a restart or reconnect boundary. page = await findTargetPage(browser, "https://example.com/");Errors
Handle failures explicitly
The JavaScript page helpers are designed to fail safely for unavailable targets/actions and commonly resolve to null. Guard important results. The real Puppeteer bridge can also return structured automation errors such as invalid requests, unavailable bridge state, or a missing matching page.
const saveButton = await SOCIALBROWSER.page.click("#save"); if (!saveButton) { console.warn("Save button was not available"); return null; }| Condition | Recommended response |
|---|---|
| Endpoint does not answer | Confirm Social Browser is running and API/debugging access is enabled in API Clients. |
| No matching target | Refresh the live target list; do not reuse an old runtime ID. |
| Selector returns no element | Wait for the expected page state, use a stronger selector, and guard a null result. |
| Navigation replaces the renderer | Wait for navigation/page readiness and resolve the page again when necessary. |
| Puppeteer method unsupported | Use a supported helper/Electron path or another CDP method available in the installed build. |
Security
Developer access is powerful — scope it carefully
- Keep the debugging/API endpoint bound to
127.0.0.1unless you intentionally secure another network path. - Do not publish API keys, client secrets or remote debugging endpoints in source control.
- Treat trusted User Scripts as privileged code; review them before enabling them.
- Use Profile-level separation so automation for one account/workspace does not accidentally act in another.
- Do not expose internal runtime IDs as durable database identifiers.
- Use these capabilities only on systems, pages and accounts you are authorized to operate.
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(); }