Pular para o conteúdo principal
Seus usuários conectam as próprias contas sociais eles mesmos — eles se autenticam diretamente em cada rede, e você nunca vê nem armazena as credenciais deles. Tudo nesta página trata de levá-los até esse momento e de descobrir como ele terminou. Uma coisa é comum a todas as rotas: uma link session, criada com Criar uma Link Session a partir da sua API Key e de um 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.
Chame Criar uma Link Session com o Profile-Key do usuário no cabeçalho. Para a página hospedada, essa é a requisição inteira:
cURL
Você recebe de volta uma url que carrega um token opaco e de curta duração:
Linking URL
Você também pode verificar se um link foi aberto e revogá-lo antes de expirar.
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

Uma URL de vinculação autentica o seu usuário no perfil dele, então trate-a como uma senha. Envie-a por um canal confiável, não a registre em logs e não a passe a terceiros. Ela continua utilizável durante toda a sua janela, então um recarregamento ou uma nova tentativa de OAuth funciona — mas envie cada link para um único usuário e crie um link separado por pessoa.

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 origin ao criar o link e a janela de vinculação envia connect:success, connect:error e connect:cancelled para a sua página conforme acontecem. Sem polling.
  • Consultar uma Link Session — informa completedAt, lastCompletedAt e completedNetworks. 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, defina expiresIn em minutos para ampliar essa janela — até 2880 minutos (48 horas), que é o máximo que a API aceita:
Expires In
Uma janela mais longa é o que torna prático enviar o link por e-mail — um usuário reconectando uma conta que caiu pode ir direto do seu e-mail para a rede, sem visitar seu app primeiro.
Revise com sua equipe de segurança por quanto tempo um link deve permanecer ativo. Uma janela mais longa é um período mais longo em que um link interceptado ainda funciona. Se um deles vazar, você pode revogá-lo em vez de esperar que expire.

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 expiresIn mais curto que funcione para você (Max Pack).
  • Revogue um link que você suspeita ter vazado, usando Revogar uma Link Session.

Profile Key

O Profile-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. 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 corpo instagramLinkMethod sobrescreve essa configuração para um único link:
Instagram Link Method
O override se aplica durante toda a vida desse link, inclusive ao longo do redirecionamento de autorização do Instagram/Facebook. Algumas coisas a saber:
  • 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 400 listando 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 um expiresIn mais longo — os cinco minutos padrão raramente sobrevivem a uma caixa de entrada.

JSON de conexão de contas

Todos os campos dentro de email são obrigatórios. Um campo ausente faz o envio falhar.
Example Contact Email Request
expiresIn é um parâmetro de nível superior, não parte do objeto email. Aninhado dentro de email, ele é ignorado, e seu usuário recebe um link que expira em cinco minutos.
A resposta informa o resultado em emailSent:
Example Contact Email Response
Se o e-mail não puder ser enviado, a requisição ainda é bem-sucedida e você recebe o link. A resposta traz 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: Connect Accounts email O e-mail virá do endereço: 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 com disallowed_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 — ASWebAuthenticationSession ou SFSafariViewController.
  • Android — Chrome Custom Tabs.
Como um app nativo não tem janela de navegador para receber eventos, obtenha o resultado com Consultar uma Link Session. Defina 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

Substitua linkingURL 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 body profileKey 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 arquivo private.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.key e 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. expiresIn e 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.