Skip to main content
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.

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.

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.
A Private Key não é mais usada. Os links 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, e o arquivo private.key do seu Integration Package pode ficar sem uso.

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
Uma falha no envio não volta como emailSent: false — ela retorna code: 333 em vez disso. Então false significa que nenhum e-mail foi solicitado.

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.
  • iOSASWebAuthenticationSession 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.