Como gerar links de ação de e-mail

Às vezes, os aplicativos para dispositivos móveis precisam interagir com os usuários e solicitar que eles realizem determinadas ações com o envio de e-mails.

Os SDKs de cliente do Firebase oferecem a capacidade de enviar e-mails aos usuários com links que eles podem usar para redefinições de senha, verificação de endereço de e-mail e login com base em e-mail. Esses e-mails são enviados pelo Google e têm personalização limitada.

Se você quiser usar modelos e serviços de entrega de e-mail próprios, pode usar o SDK Admin do Firebase para gerar programaticamente os links de ação para os fluxos acima, que podem ser incluídos em e-mails para seus usuários.

Os benefícios são os seguintes:

  • Personalizar modelos de e-mail. Isso inclui a capacidade de adicionar novos estilos e branding personalizado, alterar palavras e logotipos, chamar os usuários pelo primeiro nome em vez do nome completo e assim por diante.
  • Aplicar modelos diferentes dependendo do contexto. Por exemplo, se o usuário for verificar o e-mail para assinar uma newsletter, talvez seja necessário fornecer algum contexto no conteúdo do e-mail. Outro exemplo é o login com link de e-mail: em um cenário, ele pode ser acionado pelo próprio usuário ou como um convite de outro usuário. O contexto precisaria ser incluído no e-mail.
  • Localizar modelos de e-mail personalizados.
  • Capacidade de gerar o link a partir de um ambiente de servidor seguro.
  • Capacidade de personalizar como o link será aberto, por meio de um app ou de um navegador, e como transmitir informações adicionais sobre o estado, etc.
  • Capacidade de personalizar o domínio do link dinâmico usado para fluxos de aplicativos para dispositivos móveis ao criar o link de ações de e-mail e até mesmo especificar um domínio de link dinâmico diferente, dependendo do contexto ou do app.

Inicializar ActionCodeSettings

Antes de gerar um link de ações de e-mail, talvez seja necessário inicializar uma instância de ActionCodeSettings.

ActionCodeSettings permite que você transmita um estado adicional por meio de um URL de confirmação, que fica acessível depois que o usuário clica no link de e-mail. Isso também possibilita ao usuário retornar ao app após a conclusão da ação. Além disso, você pode especificar se é para processar o link de ação do e-mail diretamente de um aplicativo para dispositivos móveis quando ele for instalado ou de um navegador.

Para links que precisam ser abertos por meio de um aplicativo para dispositivos móveis, você precisará ativar o Firebase Dynamic Links e realizar algumas tarefas para detectar esses links no app. Consulte as instruções sobre como configurar o Firebase Dynamic Links para ações de e-mail.

Para inicializar uma instância de ActionCodeSettings, forneça os seguintes dados:

Parâmetro Tipo Descrição
url string

Define o link (estado/URL contínuo) que tem diferentes significados em contextos distintos:

  • Quando o link aparece nos widgets de ação da Web, este é o link direto no parâmetro de consulta continueUrl.
  • Quando o link aparece diretamente no app, este é o parâmetro de consulta continueUrl no link direto do Dynamic Links.
iOS ({bundleId: string}|undefined) Define o código do pacote iOS. Isso tentará abrir o link em um app iOS se ele estiver instalado. O app iOS precisa estar registrado no console.
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) Define o nome do pacote Android. Isso tentará abrir o link em um app Android se ele estiver instalado. Se o installApp for transmitido, ele especificará se é para instalar o app Android se o dispositivo for compatível com ele e o app ainda não estiver instalado. Se este campo for mostrado sem um packageName, um erro será lançado, explicando que o packageName precisa ser fornecido em conjunto com o campo. Se o atributo minimumVersion for especificado e uma versão mais antiga do app estiver instalada, o usuário será levado à Play Store para atualizar o app. O app para Android precisa estar registrado no console.
handleCodeInApp (boolean|undefined) Se o link de ação de e-mail será aberto em um aplicativo para dispositivos móveis ou em um link da Web primeiro. O valor padrão é "false". Quando definido como verdadeiro, o link do código de ação será enviado como um link universal ou um link do app Android e será aberto pelo app, se estiver instalado. Caso seja falso, o código será enviado primeiro ao widget da Web e, em seguida, redirecionará para o app, se estiver instalado.
dynamicLinkDomain (string|undefined) Define o domínio de link dinâmico (ou subdomínio) a ser usado para o link atual, se ele for aberto usando o Firebase Dynamic Links. Como é possível configurar vários domínios de links dinâmicos por projeto, esse campo oferece a capacidade de escolher explicitamente um. Se nenhum for fornecido, o domínio mais antigo é usado por padrão.

O exemplo a seguir ilustra como enviar um link de verificação de e-mail que será aberto em um aplicativo para dispositivos móveis primeiro como um link dinâmico do Firebase (com.example.ios do app iOS ou com.example.android do app Android em que ele será instalado, caso ainda não esteja, e a versão mínima é 12). O link direto conterá o payload do URL contínuo https://www.example.com/checkout?cartId=1234. O domínio de link dinâmico usado é coolapp.page.link, que precisa ser configurado para uso com o Firebase Dynamic Links.

Node.js

const actionCodeSettings = {
  // URL you want to redirect back to. The domain (www.example.com) for
  // this URL must be whitelisted in the Firebase Console.
  url: 'https://www.example.com/checkout?cartId=1234',
  // This must be true for email link sign-in.
  handleCodeInApp: true,
  iOS: {
    bundleId: 'com.example.ios'
  },
  android: {
    packageName: 'com.example.android',
    installApp: true,
    minimumVersion: '12'
  },
  // FDL custom domain.
  dynamicLinkDomain: 'coolapp.page.link'
};

Para saber mais, consulte Como transmitir o estado em ações de e-mail.

Para gerar um link de redefinição de senha, forneça o e-mail do usuário existente e um objeto ActionCodeSettings opcional. A operação será resolvida com o link de ação de e-mail. O e-mail usado precisa pertencer a um usuário existente.

Node.js

// Admin SDK API to generate the password reset link.
const email = 'user@example.com';
admin.auth().generatePasswordResetLink(email, actionCodeSettings)
  .then((link) => {
    // Construct password reset email template, embed the link and send
    // using custom SMTP server.
    return sendCustomPasswordResetEmail(email, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Depois que o link é gerado, ele pode ser inserido no e-mail de redefinição de senha personalizado e enviado ao usuário correspondente usando um servidor SMTP personalizado.

Se você não estiver usando a página de destino de redefinição de senha padrão e criar seu próprio manipulador personalizado, consulte Como criar manipuladores de ação de e-mail personalizados.

Para gerar um link de verificação de e-mail, forneça o e-mail não verificado do usuário existente e um objeto ActionCodeSettings opcional. A operação será resolvida com o link de ação de e-mail. O e-mail usado precisa pertencer a um usuário existente.

Node.js

// Admin SDK API to generate the email verification link.
const email = 'user@example.com';
admin.auth().generateEmailVerificationLink(email, actionCodeSettings)
  .then((link) => {
    // Construct email verification template, embed the link and send
    // using custom SMTP server.
    return sendCustomVerificationEmail(email, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Depois que o link é gerado, ele pode ser inserido no e-mail de verificação personalizado e enviado ao usuário correspondente usando um servidor SMTP personalizado.

Se você não estiver usando a página de destino de verificação de e-mail padrão e criar seu próprio manipulador personalizado, consulte Como criar manipuladores de ação de e-mail personalizados.

Antes de poder autenticar usuários com o login por link de e-mail, você precisará ativar o login por link de e-mail para seu projeto do Firebase.

Para gerar um link de login, forneça o e-mail do usuário e um objeto ActionCodeSettings. O objeto ActionCodeSettings é necessário neste caso para fornecer informações sobre o destino de retorno do usuário após o link ser clicado para a conclusão do login. A operação será resolvida com o link de ação de e-mail.

Ao contrário da redefinição de senha e da verificação de e-mail, o e-mail usado não precisa necessariamente pertencer a um usuário existente, porque essa operação pode ser usada para conectar novos usuários ao seu app por meio do link de e-mail.

Node.js

// Admin SDK API to generate the sign in with email link.
const email = 'user@example.com';
admin.auth().generateSignInWithEmailLink(email, actionCodeSettings)
  .then((link) => {
    // Construct sign-in with email link template, embed the link and
    // send using custom SMTP server.
    return sendSignInEmail(email, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Depois que o link é gerado, ele pode ser inserido no e-mail de login personalizado e enviado ao usuário correspondente usando um servidor SMTP personalizado.

Saiba mais sobre como autenticar usuários com o Firebase usando links de e-mail. Isso ajudará a fornecer informações sobre como realizar o login depois que o usuário clicar no link e for redirecionado de volta ao app.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.