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

Às vezes, os apps 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 podem ser usados para redefinições de senha, verificação de endereço de e-mail e login com base no e-mail. Esses e-mails baseados em modelos 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, esta página explica como usar o SDK Admin do Firebase para gerar programaticamente os links de ação para os fluxos acima, que podem ser incluídos nos e-mails para os usuários.

Os benefícios estão listados a seguir:

• 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, entre outras.
• 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 por 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, com um app ou um navegador, e como transmitir outras informações 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 do e-mail. Isso também possibilita ao usuário retornar ao app após a conclusão da ação. Além disso, é possível 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 com um app para dispositivos móveis, será necessário 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:

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

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',
};

ActionCodeSettings actionCodeSettings = ActionCodeSettings.builder()
    .setUrl("https://www.example.com/checkout?cartId=1234")
    .setHandleCodeInApp(true)
    .setIosBundleId("com.example.ios")
    .setAndroidPackageName("com.example.android")
    .setAndroidInstallApp(true)
    .setAndroidMinimumVersion("12")
    .setDynamicLinkDomain("coolapp.page.link")
    .build();

action_code_settings = auth.ActionCodeSettings(
    url='https://www.example.com/checkout?cartId=1234',
    handle_code_in_app=True,
    ios_bundle_id='com.example.ios',
    android_package_name='com.example.android',
    android_install_app=True,
    android_minimum_version='12',
    dynamic_link_domain='coolapp.page.link',
)

actionCodeSettings := &auth.ActionCodeSettings{
	URL:                   "https://www.example.com/checkout?cartId=1234",
	HandleCodeInApp:       true,
	IOSBundleID:           "com.example.ios",
	AndroidPackageName:    "com.example.android",
	AndroidInstallApp:     true,
	AndroidMinimumVersion: "12",
	DynamicLinkDomain:     "coolapp.page.link",
}

var actionCodeSettings = new ActionCodeSettings()
{
    Url = "https://www.example.com/checkout?cartId=1234",
    HandleCodeInApp = true,
    IosBundleId = "com.example.ios",
    AndroidPackageName = "com.example.android",
    AndroidInstallApp = true,
    AndroidMinimumVersion = "12",
    DynamicLinkDomain = "coolapp.page.link",
};

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

Gerar link por e-mail para redefinir a senha

Para gerar um link para redefinir a senha, forneça o e-mail do usuário 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.

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

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generatePasswordResetLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

email = 'user@example.com'
link = auth.generate_password_reset_link(email, action_code_settings)
# Construct password reset email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

email := "user@example.com"
link, err := client.PasswordResetLinkWithSettings(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct password reset template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GeneratePasswordResetLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

Depois que o link é gerado, ele pode ser inserido no e-mail para 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 para redefinição de senha padrão e criar seu próprio manipulador personalizado, consulte Criar gerenciadores de ação de e-mail personalizados.

Gerar link de verificação de e-mail

Para gerar um link de verificação de e-mail, forneça o e-mail não verificado do usuário 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.

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

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generateEmailVerificationLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

email = 'user@example.com'
link = auth.generate_email_verification_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

email := "user@example.com"
link, err := client.EmailVerificationLinkWithSettings(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct email verification template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GenerateEmailVerificationLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

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 gerenciador personalizado, consulte Criar gerenciadores de ação de e-mail personalizados.

Gerar link por e-mail para fazer login

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, porque essa operação pode ser usada para conectar novos usuários ao seu app por meio do link por e-mail.

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

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generateSignInWithEmailLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

email = 'user@example.com'
link = auth.generate_sign_in_with_email_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

email := "user@example.com"
link, err := client.EmailSignInLink(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct sign-in with email link template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GenerateSignInWithEmailLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

Depois que o link é gerado, ele poderá 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 por 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.