Social BrowserProfiles, IA e automação

Referência do desenvolvedor · API do navegador · SDK de automação

Controle Social Browser do código

Use o nível de integração adequado ao seu trabalho: conecte uma ferramenta externa por meio da superfície de depuração/API do navegador local, automatize a guia atual exata a partir de um script de usuário confiável ou execute o código real do Puppeteer no mesmo perfil Social Browser persistente.

CDP: Caminho do protocolo Chromium DevTools 1.3 Profiles: estado persistente do navegador Scope: controle do navegador local DevTools: DevTools padrão do Chromium disponíveis Docs: Atualizado em 11 de setembro de 2026
Configurações de clientes da API Social Browser
Configurações de clientes API dentro de Social Browser

Escolha a superfície de integração correta

Três maneiras de automatizar Social Browser

Essas superfícies resolvem problemas diferentes. Não os trate como intercambiáveis.

01

Cliente API/CDP externo

Use-o quando Node.js, Python, um IDE, executor de testes ou outra ferramenta de desktop precisar se conectar ao navegador em execução de fora da página.

Melhor para:automação externa, inspeção, controle de qualidade e ferramentas de desenvolvedor. Configure um cliente externo →
02

SOCIALBROWSER.page

Use isso dentro de um script de usuário Social Browser confiável quando a automação pertencer à página/perfil exato já aberto no navegador.

Melhor para:ações de página, formulários, esperas, extração, controle de mouse e teclado. Use a página SDK →
03

Ponte do Marionetista Real

Use runPuppeteer() quando um script de usuário confiável precisa de métodos Puppeteer reais no processo principal no mesmo espaço de trabalho/guia atual.

Melhor para:capturas de tela, trabalho DOM avançado e APIs Puppeteer não expostas por um auxiliar. Execute o Marionetista →

Architecture

Como funciona o fluxo do desenvolvedor

Um perfil Social Browser é um ambiente de navegador persistente. Sua navegação manual e sua automação podem operar no mesmo perfil, portanto, cookies, armazenamento local, estado de login, escolha de proxy e configurações de navegador compatíveis podem permanecer disponíveis entre as execuções.

Seu códigoNode.js/ferramenta/Script do usuário
→
API / SDKCDP · Titereiro · ajudantes de página
→
TargetPerfil → guia/janela
→
Websitemesmo estado persistente do navegador
Regra de identidade de destino: identificadores de tempo de execução, como CDP targetId ou interno webContentsId têm escopo de tempo de execução. Resolva o alvo novamente após reiniciar ou reconectar o navegador, em vez de armazenar esses IDs permanentemente.

Ferramentas externas

Configure um cliente API/CDP

  1. 1
    Clientes API abertos

    Dentro de Social Browser aberto browser://local/settings/api-clients. Esta é a fonte da verdade para o endpoint e as opções de segurança suportadas pela compilação instalada.

  2. 2
    Habilite apenas o acesso do cliente que você precisa

    Mantenha o acesso do desenvolvedor local, a menos que você configure deliberadamente um caminho de rede confiável. Trate qualquer chave/token de API como um segredo.

  3. 3
    Copie o endpoint local do navegador

    Os exemplos abaixo usam o endereço de depuração local padrão http://127.0.0.1:60101. Se a tela API Clients mostrar outro endpoint, use o valor mostrado pelo seu navegador.

  4. 4
    Descubra o navegador ativo e os alvos

    Consulte os endpoints de descoberta do Chromium ou conecte-se ao Puppeteer. Resolva alvos ativos sempre que você se conectar.

Verifique se o endpoint do navegador está disponível

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

/json/version descreve o endpoint de navegador/depuração em execução. /json/list retorna alvos atualmente detectáveis. Um destino é o estado do tempo de execução, não um identificador de perfil durável.

Não persista os IDs de destino. Se Social Browser for reiniciado, uma guia for recriada ou ocorrer uma reconexão em tempo de execução, resolva o destino novamente pelo contexto atual do perfil/guia, URL, título ou outra identidade de recurso durável disponível para sua integração.

Node.js

Conecte-se com o Marionetista

Social Browser usa a superfície de depuração do Chromium em execução, para que um processo Node.js externo possa ser anexado puppeteer-core. Set defaultViewport: null portanto, o Puppeteer não impõe sua janela de visualização normal de 800×600 em um espaço de trabalho Social Browser existente.

const puppeteer = require("puppeteer-core"); const browser = await puppeteer.connect({ browserURL: "http://127.0.0.1:60101", defaultViewport: null, }); const pages = await browser.pages(); for (const page of pages) { console.log(await page.title(), page.url()); } // Disconnect your client without closing Social Browser. await browser.disconnect();

Encontre a página que você realmente deseja

const pages = await browser.pages(); const page = pages.find(p => p.url().startsWith("https://example.com/") ); if (!page) { throw new Error("Target page is not currently open"); } console.log({ title: await page.title(), url: page.url(), });

Para fluxos de trabalho com vários perfis, não presuma que a primeira página retornada pertence ao perfil pretendido. Resolva e verifique o alvo antes de alterá-lo.

Exemplo simples de leitura + ação

await page.waitForSelector("#search", { visible: true }); await page.type("#search", "Social Browser"); await page.click('button[type="submit"]'); await page.waitForSelector(".results", { visible: true }); const titles = await page.$$eval(".result-card h2", nodes => nodes.map(node => node.textContent.trim()) ); console.log(titles);

User Scripts confiável

Use SOCIALBROWSER.page dentro da aba atual

Social Browser ZXQUSENSCRIPTSQXZ confiável recebe o reconhecimento global SOCIALBROWSER object. SOCIALBROWSER.page oferece ajudantes inspirados no Puppeteer somente em JavaScript para a guia exata onde o script está sendo executado. Você não precisa de um processo Node.js separado para esse caminho.

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, });
AreaAjudantes comunsUse
Ações da páginaclick, dblclick, rightClick, hover, focusInteraja com os elementos.
Inputtype, setValue, clear, selectOption, checkFormulários e controles editáveis.
WaitingwaitForSelector, waitForFunction, waitForTimeout, waitForGoneSincronize com o estado da página.
Querying$, $$, $eval, $$eval, findDeepEncontre e leia o conteúdo do DOM.
Scrollingscroll, scrollTo, scrollToElement, scrollHumanMova a janela de visualização.
Devicesmouse, keyboard, touchscreen, cursorControle de entrada de nível inferior.
Locatorlocator(...)Mantenha um alvo unido nas etapas de espera/preenchimento/foco/clique.

Ponte do Processo Principal

Execute o Puppeteer real na guia atual exata

SOCIALBROWSER.page.runPuppeteer() destina-se a ZXQUSENSCRIPTSQXZ confiáveis. O retorno de chamada é executado com o Puppeteer real no processo principal e Social Browser resolve o renderizador atual para o destino do Puppeteer correspondente.

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);

A ponte conecta Puppeteer com defaultViewport: null e resolve o destino exato usando as informações atuais do destino do depurador Chromium. O depurador incorporado é anexado por meio da versão do protocolo CDP 1.3 quando necessário.

Compatibility: este é o Puppeteer real, mas nem todos os recursos do Puppeteer são garantidos em todas as versões incorporadas do Chromium/Electron. Os recursos que dependem de domínios CDP não suportados podem estar indisponíveis.

Reliability

Regras de ciclo de vida e seleção de alvos

Resolver metas com atraso

Encontre o destino pretendido imediatamente antes de usar, em vez de armazenar em cache um destino de tempo de execução por um longo período.

Resolver novamente após reiniciar

Uma reinicialização/reconexão pode criar novos IDs de tempo de execução mesmo quando o perfil persistente é o mesmo.

Verifique antes de agir

Verifique o contexto do URL/título/perfil antes de enviar uma ação em uma sessão com vários perfis.

Espere mudanças de navegação

A navegação pode reconstruir um quadro renderizador/CDP. Seu código deve aguardar o novo estado da página em vez de assumir que o quadro antigo permanece válido.

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

Lidar com falhas explicitamente

Os auxiliares de página JavaScript são projetados para falhar com segurança em alvos/ações indisponíveis e geralmente resolvem para null. Guarde resultados importantes. A ponte Puppeteer real também pode retornar erros de automação estruturados, como solicitações inválidas, estado de ponte indisponível ou página correspondente ausente.

const saveButton = await SOCIALBROWSER.page.click("#save"); if (!saveButton) { console.warn("Save button was not available"); return null; }
ConditionResposta recomendada
O ponto final não respondeConfirme se Social Browser está em execução e se o acesso à API/depuração está ativado em clientes API.
Nenhuma meta correspondenteAtualize a lista de alvos ativos; não reutilize um ID de tempo de execução antigo.
O seletor não retorna nenhum elementoAguarde o estado esperado da página, use um seletor mais forte e proteja um null result.
A navegação substitui o renderizadorAguarde a prontidão da navegação/página e resolva a página novamente quando necessário.
Método de marionetista não suportadoUse um caminho auxiliar/Electron compatível ou outro método CDP disponível na compilação instalada.

Security

O acesso do desenvolvedor é poderoso – analise-o com cuidado

  • Mantenha o endpoint de depuração/API vinculado a 127.0.0.1 a menos que você proteja intencionalmente outro caminho de rede.
  • Não publique chaves de API, segredos de cliente ou pontos de extremidade de depuração remota no controle de origem.
  • Trate ZXQUSENSCRIPTSQXZ confiável como código privilegiado; revise-os antes de ativá-los.
  • Use a separação em nível de perfil para que a automação de uma conta/espaço de trabalho não atue acidentalmente em outra.
  • Não exponha IDs de tempo de execução internos como identificadores de banco de dados duráveis.
  • Use esses recursos apenas em sistemas, páginas e contas que você está autorizado a operar.

Exemplos completos

Padrões práticos de fluxo de trabalho

Ler um valor do painel

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() );

Aguarde um carregador e colete as linhas

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())) )) || [];

Verificação de controle de qualidade externo por meio do 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(); }

Troubleshooting

Problemas comuns de configuração

A conexão é recusada

Confirme se Social Browser está em execução, abra browser://local/settings/api-clientse verifique se o acesso do desenvolvedor/API está ativado. Em seguida, use o endpoint exato mostrado pela compilação instalada.

O Titereiro se conecta, mas vejo a página errada

Um navegador pode expor vários alvos ativos. Enumere páginas e verifique o contexto de URL/título/perfil. Nunca assuma pages()[0] é o perfil pretendido.

Meu targetId armazenado parou de funcionar

Isso é esperado após os limites do ciclo de vida, como reiniciar/reconectar. Os IDs de destino do tempo de execução não são duráveis. Descubra o alvo novamente.

Um auxiliar retorna nulo

O alvo pode ainda não existir, pode não estar visível/habilitado ou a ação pode não estar disponível. Aguarde o estado esperado e guarde o valor de retorno.

Uma API Puppeteer não está disponível

O navegador incorporado suporta os caminhos Puppeteer/CDP implementados pela compilação atual, mas nem todos os domínios CDP são garantidos. Prefira o auxiliar Social Browser documentado ou o caminho Electron suportado quando uma chamada direta do Puppeteer não estiver disponível.