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.3Profiles: estado persistente do navegadorScope: controle do navegador localDevTools: DevTools padrão do Chromium disponíveisDocs: Atualizado em 11 de setembro de 2026
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.
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
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
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
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
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
/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.
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.
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.
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; }
Condition
Resposta recomendada
O ponto final não responde
Confirme se Social Browser está em execução e se o acesso à API/depuração está ativado em clientes API.
Nenhuma meta correspondente
Atualize a lista de alvos ativos; não reutilize um ID de tempo de execução antigo.
O seletor não retorna nenhum elemento
Aguarde o estado esperado da página, use um seletor mais forte e proteja um null result.
A navegação substitui o renderizador
Aguarde a prontidão da navegação/página e resolva a página novamente quando necessário.
Método de marionetista não suportado
Use 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.
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.