Qual superfície você quer

Frames incorporados: nossos tiles renderizados dentro do seu próprio layout, um slot por rede ou um slot para várias.

Seu próprio botão: você renderiza o botão, e um breve popup nosso cuida da rede.

Página de vinculação hospedada: uma página que nós hospedamos, com seu logotipo e cores, que seu usuário sai do seu app para usar.
init dá a você as duas: monte frames
onde quiser nossos botões e chame popup() a partir do seu próprio botão em todos os outros lugares. Elas
compartilham uma sessão e reportam nos mesmos handlers.O modo direto é o mesmo popup sem o nosso script — para
uma página com uma Content-Security-Policy rígida, uma página renderizada no servidor ou um app nativo. Ali
você mesmo abre e observa o popup.Adicione o script
Fixe uma versão e seu hash, ou acompanhe um canal sem hash. Nunca os dois — um atributointegrity
em uma URL móvel deixa de funcionar no nosso próximo release, porque o arquivo que ela nomeia mudou
legitimamente.
v1 é o canal a recomendar. Ele recebe correções, mas nunca cruza uma breaking change.
latest cruza versões major por definição, então em algum momento entregará à sua página uma versão cujo
comportamento você não revisou.
O hash de cada versão é publicado no
manifest.json, que também nomeia o que
cada canal serve atualmente:
Content-Security-Policy
Se a sua página envia uma Content-Security-Policy, ela precisa de duas entradas, ambas nomeando o host de onde você carrega o script:connect-src para nós — nossos frames alcançam nossa API de
dentro deles mesmos, não da sua página — e nenhuma entrada para popups, que são janelas de nível superior
que a sua política não governa. As duas entradas foram medidas: remover script-src bloqueia o script,
e remover frame-src bloqueia o frame.
Inicie uma instância
session é a única opção obrigatória. Ela é chamada uma vez por instância, não uma vez por mount, e
deve retornar a resposta do seu backend a
Criar uma Link Session com mode: "connect" —
{ sessionId, token, expiresAt } — exatamente como ela voltou.
network — ela autoriza todas as redes que sua conta permite, e
quais aparecem é decidido por mount, na sua página. Ela carrega, sim, um origin, que é a única
coisa que faz os frames renderizarem: um frame compara a página que o incorpora com esse valor
e se recusa a renderizar em qualquer outro lugar.
Chamamos session novamente antes de o token expirar, então o widget continua funcionando em uma página deixada aberta
o dia todo. Uma chamada que rejeita, ou que não retorna token, é repetida mais duas vezes — após 0.5s e depois 1s —
antes de desistirmos e emitirmos error. Então um refresh custa no máximo três chamadas ao seu endpoint.
Monte um slot
Ummount por slot. Peça uma rede, várias ou tudo o que a sessão permite — a
granularidade é sua, então um slot pode ser uma única linha em uma tabela existente ou um painel contendo
tudo.
mount recebe um seletor CSS ou um elemento, e retorna { unmount, element }. Ele lança uma exceção se o
alvo não corresponde a nada — o que quase sempre é um slot que ainda não existe, então monte depois que seu
markup estiver no documento.
Cada mount é um iframe. Ele reporta sua própria altura para nós e nós o redimensionamos para corresponder, então seu layout
se reorganiza conforme nosso conteúdo muda; além de maxHeight, o frame rola internamente em vez de escapar da
sua página. O slot mais estreito que suportamos é 300px.
As chaves de rede são as próprias da Ayrshare, e as grafias alternativas também funcionam: instagram e instagramapi
significam ambas instagramApi, e x significa twitter. Uma chave que não é uma rede não renderiza tile algum.
Seu próprio botão
Um cliente que prefere usar o próprio botão em vez de um dos nossos frames chamapopup em vez disso. Ele
executa o mesmo fluxo, na mesma sessão, e reporta nos mesmos handlers.
popup retorna { close(), network }, e sempre retorna um handle — inclusive depois de um popup
bloqueado, quando close() não faz nada — para que seu código nunca precise verificar null antes de chamar
close().
Todas as redes funcionam aqui, incluindo as que um frame conclui dentro do próprio painel: o Facebook mostra
sua tela explicativa de transição no popup, Bluesky e X mostram seu formulário de credenciais, e LinkedIn,
Pinterest, YouTube e Google Business vão até a rede e voltam.
Ele lança uma exceção de forma síncrona para as três coisas que são erros de programação — nenhum network, uma
instância destruída ou uma sessão que ainda não resolveu. Um popup bloqueado não é uma delas:
esse emite error com reason: "popupBlocked", porque seu usuário não fez nada de errado.
No máximo um popup fica aberto por vez. Uma segunda chamada fecha o primeiro e reporta cancelled com
reason: "superseded" nele. Um popup que um dos nossos frames abriu é outra coisa e nunca é
tocado, então seu botão não pode cancelar um fluxo em andamento dentro de um slot montado.
error. O script só verifica que uma rede foi nomeada.React
O script é livre de frameworks, então o React não precisa de nada especial de nós — mas quatro coisas sobre seu ciclo de vida valem acertar de primeira. Carregue o script uma vez, fora da sua árvore de componentes. No Next.js isso énext/script no seu
layout raiz; no Vite ou Create React App é uma tag no index.html. Carregá-lo por componente
o executa novamente a cada mount.
- Em desenvolvimento você verá o callback de session disparar duas vezes. O Strict Mode do React executa os effects mount → unmount → mount, então a instância é criada, destruída e criada de novo. O cleanup acima torna isso seguro; custa uma chamada extra ao seu backend em dev e nenhuma em produção.
- Mantenha as dependências do effect estáveis. Um array literal passado direto para
mounta partir do render de um pai é um valor novo a cada vez, então um effect que depende dele derruba o widget e o reconstrói a cada render. Memoize-o, ou mantenha-o constante como acima.
Eventos
Inscreva-se comon, que retorna uma função de cancelamento de inscrição. Os handlers recebem o payload do evento e
o mount de onde ele veio; off(name, handler) faz o mesmo trabalho quando você prefere nomear o
handler.
network, exceto ready e exceto o único tipo de error que
não tem relação com uma rede — consulte error tem duas origens abaixo.
success, unlinked, error e cancelled — e exatamente um
chega por tentativa. closed é um aviso de ciclo de vida que segue um desfecho, em vez de ser um.
click dispara antes de qualquer trabalho de vinculação começar, então ele reporta um clique que um popup bloqueado ou uma
sessão morta vai em seguida recusar. É o evento a usar para o seu próprio analytics; started é o que
significa que uma tentativa está realmente em execução.
Motivos
error tem duas origens
Apenas uma delas é uma falha de vinculação, e elas carregam campos diferentes.
- Um erro de vinculação carrega
network,codee o mount de onde veio. - Um erro de sessão — não conseguimos criar ou renovar sua sessão — carrega apenas
message, porque nada estava sendo vinculado naquele momento.
code e network são undefined no segundo tipo.
state poupa você do polling
state é o canal de dados, e não um relato sobre uma tentativa. Cada frame emite um por rede quando
é montado, carregando o estado atual daquela rede e o timestamp since desde quando ela o mantém, e
outro sempre que um estado muda — incluindo mudanças que se originam do nosso lado, como um token
que morre e vira relink obrigatório. Assim você pode dirigir toda a sua UI a partir do widget sem fazer polling de nada.
Os valores são o mesmo enum que
GET /profiles com include=state retorna: linked, unlinked,
identityVerificationRequired, restricted, rateLimited, suspended.
Desvinculação
Nossos tiles desvinculam além de vincular. Seu usuário clica em uma rede conectada, confirma, e a conta é removida:clickdispara comaction: "unlink".unlinkeddispara quando a remoção está salva.
error, e uma da qual seu usuário desiste na etapa de confirmação reporta
cancelled. Não há um evento separado de falha de desvinculação.
Aparência
A folha de estilos de um cliente não consegue alcançar o interior de um frame cross-origin, então o estilo viaja como dados que aplicamos dentro dele. Passeappearance ao init como propriedades personalizadas de CSS; cada uma que não
recebermos mantém nosso padrão.
appearance, todos os tokens mantêm seu padrão e um frame fica assim:

Tokens padrão: superfícies brancas, texto azul-marinho escuro, accent índigo, raio de 8px.

Os mesmos três tiles depois de os tokens acima serem aplicados.
prefers-color-scheme, de
propósito — o tema da sua página pode não corresponder ao sistema operacional do seu usuário, e uma media query
silenciosamente derrotaria as cores que você escolheu. Um dashboard escuro é tematizado fornecendo valores escuros.
Esta lista de tokens é um contrato suportado que mantemos entre versões.
Os tokens
8 sem unidade para --ayr-connect-spacing é uma
string perfeitamente inocente que invalidaria todo cálculo que a lê e colapsaria o
layout, sem erro em lugar nenhum. Dê unidade aos comprimentos.
Seu próprio nome na tela de transição
Antes de entregarmos seu usuário a uma rede, mostramos uma tela curta nomeando por meio de quem ele está conectando. Dois ganchos permitem que você a torne sua, e ambos são estáveis entre versões.--ayr-connect-partner-name define o rótulo. É o único token cujo valor é texto, então ele
precisa estar entre aspas como uma string CSS — um valor sem aspas é inválido e não renderiza nada:
background-image via css, como acima — um token que pudesse buscar uma imagem de dentro do nosso
documento não é algo que aceitamos, então a requisição vem de uma regra que você escreveu em vez de um
valor que você nos passou.
[data-ayr-connect-partner-mark] e [data-ayr-connect-partner-name] são a exceção à
ressalva sobre CSS personalizado abaixo: esses dois seletores fazem parte do contrato e nós os mantemos entre
versões.CSS personalizado
css recebe uma string aplicada dentro de cada frame, para os casos que os tokens não cobrem.
appearance e o css da instância exatamente como os frames, então seu usuário não
vê nossos padrões neutros aparecerem no meio de um fluxo.
Vale saber antes de lançar
Um popup cuja sessão expirou reporta cancelled, não error
Um popup cuja sessão expirou reporta cancelled, não error
popup() não pode ser informado do porquê de um token ter sido recusado — para dizer isso ele
teria de confiar em uma origem que ainda não validou, o que nosso modelo de segurança não permite. Então um
popup carregando um token morto fecha e aparece como cancelled com reason: "popupClosed"
em vez de error.Na prática isso é raro: um popup aberto antes de um refresh silencioso continua funcionando, porque ele
validou seu token quando abriu. Se você vê resultados popupClosed inexplicados, verifique se o
seu endpoint de session está retornando uma sessão nova.Uma sessão por instância, não uma por mount
Uma sessão por instância, não uma por mount
allowedSocial diferente em alguns deles — execute um segundo init
com a própria sessão dele, em vez de esperar que um mount a restrinja.Os frames só renderizam na origem que você declarou
Os frames só renderizam na origem que você declarou
origin em que a sua página roda, e um frame compara a página que o incorpora
com esse valor antes de renderizar qualquer coisa. Um frame incorporado em outro lugar permanece em branco e
não envia eventos. Não há allowlist para registrar nem nada para configurar — envie o origin
correto ao criar a sessão.A altura é tratada para você, e não é um evento
A altura é tratada para você, e não é um evento
Requisitos
- O Max Pack. Uma sessão de widget é uma sessão em modo connect, e
criar uma sem o Max Pack retorna
code: 504. Entre em contato com o suporte se você precisar do modo connect habilitado em uma conta sem ele. - Um
originem cada sessão — a origem exata em que a sua página roda. Omiti-lo retornacode: 505; um valor que não é uma origemhttps, um esquema personalizado ouhttp://localhostretornacode: 506. - Nenhum
networkna sessão. Esse parâmetro é o que torna uma sessão modo direto, e a URL de uma sessão em modo direto não é o que o script espera.