Profile-Key.
Nada é assinado do seu lado e não há chave privada no fluxo. A única exceção são integrações mais
antigas que assinam os próprios tokens. Veja Tokens autoassinados (legado).
Três formas de conectar
Três formatos, e os dois primeiros são a mesma integração. Escolha por fluxo — eles não são exclusivos, e muitas integrações usam a página hospedada para o onboarding e o widget dentro do app depois disso.As duas linhas do widget são uma integração, não duas. Um único
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.Em dúvida? Comece pela página de vinculação hospedada. Ela não precisa do Max Pack nem de parâmetros
extras, e é a rota mais rápida para algo funcionando — migrar para o widget depois não muda como
as sessões são criadas.Criando um link
Chame Criar uma Link Session com oProfile-Key do usuário no
cabeçalho. Para a página hospedada, essa é a requisição inteira:
cURL
url que carrega um token opaco e de curta duração:
Linking URL
Este vídeo de um minuto mostra a criação de um link. Ele foi gravado antes das link sessions, então ainda
mostra o envio de uma Private Key — esse passo não é mais necessário, e todo o resto que ele mostra
permanece igual.
Enviar a URL de vinculação
Abrir a URL de vinculação
Abra-a em uma nova aba do navegador, nova janela ou view controller. Você pode controlar o fechamento ou redirecionamento dessa janela.As redes sociais não permitem que a página de vinculação hospedada seja aberta dentro de um iFrame, nem que a
origem aprovada do parceiro
profile.ayrshare.com seja ofuscada. Se você quer que a vinculação aconteça
dentro da sua própria página, é para isso que existe o widget incorporado:
seus frames são servidos de uma origem Ayrshare e são a forma suportada de fazer isso.Saber quando terminou
Dois sinais, e você pode usar qualquer um deles:- Eventos de conclusão de vinculação — defina um
originao criar o link e a janela de vinculação enviaconnect:success,connect:erroreconnect:cancelledpara a sua página conforme acontecem. Sem polling. - Consultar uma Link Session — informa
completedAt,lastCompletedAtecompletedNetworks. Este é o sinal para apps nativos, e o único para o Telegram, que conclui fora do fluxo.
Expiração do link
Um link é válido por 5 minutos por padrão. Depois disso, crie um novo. Com o Max Pack, definaexpiresIn em minutos para ampliar essa janela — até 2880 minutos
(48 horas), que é o máximo que a API aceita:
Expires In
Segurança
O token da sessão viaja na query string da URL de vinculação. Tudo o que registra URLs pode registrá-lo: o histórico do navegador do usuário, logs de proxy e de servidor, ferramentas de analytics e serviços de redirecionamento. Para limitar o risco:- Não registre a URL completa nos logs dos seus próprios sistemas. Em vez disso, registre o perfil e o horário.
- Envie a URL direto para o usuário. Não a passe por encurtadores de links, rastreadores de redirecionamento ou rastreamento de cliques em e-mails. O e-mail de conexão de contas envia o link sem rastreamento de cliques.
- Mantenha a janela curta. Use o
expiresInmais curto que funcione para você (Max Pack). - Revogue um link que você suspeita ter vazado, usando Revogar uma Link Session.
Profile Key
OProfile-Key indica a qual User Profile o link se refere. Você o encontra no painel de
desenvolvedor da Ayrshare alternando para esse perfil.
Você não precisa da Private Key para criar links. Os links da API não são assinados, portanto
não há nada para ler de um arquivo nem para colar no seu código. O parâmetro legado
privateKey
continua sendo aceito e ignorado, então integrações existentes seguem funcionando.Se a sua integração assina os próprios tokens, guarde o seu arquivo private.key. Veja
Tokens autoassinados (legado).Alternar entre profiles
Se um profile já está logado, abrir o link de outro profile não troca de profile — isso é deliberado e mantém a experiência rápida para um usuário que já está lá. Para forçar a troca, consulte Logout automático de uma sessão de profile.Método de vinculação do Instagram
Contas do Instagram podem ser vinculadas de duas formas: diretamente via Instagram Login ou por meio de uma Página do Facebook conectada. Qual fluxo é iniciado quando um usuário clica no botão do Instagram normalmente é controlado pela configuração de Instagram Login em nível de conta. O parâmetro do corpoinstagramLinkMethod sobrescreve essa configuração para um único link:
Instagram Link Method
- Ele não altera sua configuração em nível de conta nem afeta nenhum outro link.
- Omita-o e a configuração em nível de conta se aplica, exatamente como antes.
- Um valor inválido retorna
400listando os valores válidos (instagram,facebook). - Revise as diferenças entre os recursos antes de escolher — alguns recursos do Instagram, como pesquisa de hashtag e colaborações, estão disponíveis apenas com a autenticação via Página do Facebook.
E-mail de conexão de contas
A Ayrshare pode enviar o link por e-mail ao seu usuário por você, para que ele chegue à sua página de vinculação sem visitar seu app. Combine com umexpiresIn mais longo — os cinco
minutos padrão raramente sobrevivem a uma caixa de entrada.
JSON de conexão de contas
Todos os campos dentro deemail são obrigatórios. Um campo ausente faz o envio falhar.
Example Contact Email Request
emailSent:
Example Contact Email Response
emailSent: false e um objeto emailError, para que você possa enviar o link ao seu usuário de outra forma:
Example Failed Email Response
emailError aparece sempre que você pediu um e-mail e ele não foi enviado: ou o envio falhou, ou faltava um campo obrigatório no objeto email, e nesse caso details indica os campos que faltam. emailSent: false sem emailError significa que nenhum e-mail foi solicitado. A falta de to é diferente: a requisição inteira é rejeitada com code: 188.
Exemplo de e-mail Connect Accounts
Aqui está um exemplo do e-mail que abre a página de vinculação social:
Social Connect Hub <connect@socialconnecthub.com>
Apps mobile
Abra a URL de vinculação no navegador do sistema, nunca em um webview incorporado: o Google rejeita o login em um deles comdisallowed_useragent, e a Meta o bloqueia de imediato. Seu usuário veria a página
de erro da própria rede, e nada do seu lado corrige isso.
- iOS —
ASWebAuthenticationSessionouSFSafariViewController. - Android — Chrome Custom Tabs.
origin como o seu esquema
personalizado (myapp://connected) para que a página tenha um caminho de volta para o seu app.
Exemplos de código para mobile
SubstitualinkingURL pela url retornada por
Criar uma Link Session.
Testando
É recomendado primeiro criar um link no Postman. Seu Integration Package — na página de API Key do Primary Profile no dashboard — inclui uma configuração de exemplo do Postman. Importe-a, preencha seu Profile Key no campo bodyprofileKey e clique em Send.
A configuração de exemplo ainda preenche privateKey e domain. privateKey é ignorado, e você pode
limpar domain a menos que sua conta tenha mais de um domínio de vinculação.
Você também pode gerar o código pelo Postman.
Bubble.io
Bubble linking URL
Legado: generateJWT
Gerar uma URL de vinculação (
generateJWT) faz o mesmo trabalho e está
obsoleto — totalmente suportado, sem data de remoção e sem alteração para os links que você já
distribuiu. A página dele documenta seus parâmetros, incluindo os três que agora são aceitos e
ignorados.Os dois endpoints executam o mesmo validador, então tudo nesta página se aplica a qualquer um dos dois. A
única diferença que vale conhecer ao migrar: o generateJWT tolera três coisas que Criar uma Link
Session rejeita — uma rede allowedSocial não reconhecida, uma credencial do X sozinha e um
redirect que não seja string.Tokens autoassinados (legado)
Algumas integrações mais antigas montam a URL de vinculação por conta própria. Elas assinam um token com o arquivoprivate.key do Integration Package e o passam como ?jwt=.
Isso continua funcionando, e não há data de remoção. Não é recomendado para novas integrações.
Use Criar uma Link Session em vez disso.
Se a sua integração assina os próprios tokens:
- Continue usando o seu arquivo
private.keye mantenha-o em segredo. - Links autoassinados não podem ser verificados nem revogados com os endpoints de link session.
- Não redefina o seu Integration Package. Uma redefinição desativa o seu domínio atual e as chaves dele, então os links que você já distribuiu param de funcionar e você não consegue assinar novos.
- Um link autoassinado só expira se o token definir um horário
exp.expiresIne a duração padrão de link session não se aplicam, então mantenha esse tempo curto. - Trate as URLs de links autoassinados como uma senha. Se alguma puder ter vazado, redefina a sua API Key na página API do dashboard e atualize a sua integração para usar a nova chave. Isso protege a sua conta, mas pode não impedir que o link vazado continue funcionando. Fale com o suporte para bloquear o link.