Gerando links de ação de e-mail

Às vezes, os aplicativos móveis precisam interagir com os usuários e solicitar que eles executem determinadas ações enviando e-mails.

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

Se você quiser usar seus próprios modelos de e-mail e seu próprio serviço de entrega de e-mail, esta página explica como usar o SDK Admin do Firebase para gerar programaticamente os links de ação para os fluxos acima, que você pode incluir em e-mails para seus usuários.

Isso traz os seguintes benefícios:

  • Personalize modelos de e-mail. Isso inclui a capacidade de adicionar novos estilos e marcas personalizadas, alterar textos e logotipos, abordar os usuários pelo primeiro nome em vez do nome completo e assim por diante.
  • Aplique modelos diferentes dependendo do contexto. Por exemplo, se o usuário estiver verificando seu e-mail para assinar um boletim informativo, talvez seja necessário fornecer o contexto no conteúdo do e-mail. Outro exemplo é o login por link de e-mail: em um cenário, isso pode ser acionado pelo mesmo usuário ou como um convite de outro usuário. O contexto precisaria ser incluído no e-mail.
  • Localize 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 aplicativo móvel ou navegador, e como passar informações adicionais de estado, etc.
  • Capacidade de personalizar o domínio de link dinâmico usado para fluxos de aplicativos móveis ao construir o link de ação de email e até mesmo especificar um domínio de link dinâmico diferente dependendo do contexto ou do aplicativo móvel.

Inicializar ActionCodeSettings

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

ActionCodeSettings permite que você passe um estado adicional por meio de um URL de continuação que pode ser acessado depois que o usuário clica no link do e-mail. Isso também fornece ao usuário a capacidade de voltar ao aplicativo após a conclusão da ação. Além disso, você pode especificar se deseja manipular o link de ação de e-mail diretamente de um aplicativo móvel quando ele estiver instalado ou de um navegador.

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

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

Parâmetro Tipo Descrição
url corda

Define o link (URL de estado/continuação) que tem significados diferentes em contextos diferentes:

  • Quando o link é manipulado nos widgets de ação da web, esse é o link direto no parâmetro de consulta continueUrl .
  • Quando o link é manipulado diretamente no aplicativo, esse é o parâmetro de consulta continueUrl no link direto do link dinâmico.
iOS ({bundleId: string}|indefinido) Define o ID do pacote. Isso tentará abrir o link em um aplicativo da Apple, se estiver instalado. O aplicativo precisa ser registrado no Console.
android ({nomedopacote: string, installApp:boolean|indefinido, mínimoVersão: string|indefinido}|indefinido) Define o nome do pacote Android. Isso tentará abrir o link em um aplicativo Android, se estiver instalado. Se installApp for aprovado, ele especifica se o aplicativo Android deve ser instalado se o dispositivo for compatível e o aplicativo ainda não estiver instalado. Se este campo for fornecido sem packageName , será gerado um erro explicando que packageName deve ser fornecido em conjunto com este campo. Se minimumVersion for especificada e uma versão mais antiga do aplicativo estiver instalada, o usuário será levado à Play Store para atualizar o aplicativo. O aplicativo Android precisa ser registrado no Console.
handleCodeInApp (booleano | indefinido) Se o link de ação do e-mail será aberto primeiro em um aplicativo móvel ou em um link da web. O padrão é falso. Quando definido como verdadeiro, o link do código de ação será enviado como um link universal ou link do aplicativo Android e será aberto pelo aplicativo, se instalado. No caso falso, o código será enviado primeiro para o widget da web e, em seguida, continuará redirecionando para o aplicativo, se instalado.
dynamicLinkDomain (string | indefinido) Define o domínio (ou subdomínio) do link dinâmico a ser usado para o link atual se ele for aberto usando o Firebase Dynamic Links. Como vários domínios de link dinâmico podem ser configurados por projeto, este campo oferece a capacidade de escolher explicitamente um. Se nenhum for fornecido, o domínio mais antigo será usado por padrão.

O exemplo a seguir ilustra como enviar um link de verificação por e-mail que será aberto primeiro em um aplicativo móvel como um Firebase Dynamic Link (aplicativo Apple com.example.ios ou aplicativo Android com.example.android onde o aplicativo será instalado se ainda não estiver instalado e a versão mínima é 12). O link direto conterá a carga útil do URL de continuação https://www.example.com/checkout?cartId=1234 . O domínio de link dinâmico usado é coolapp.page.link , que deve ser configurado para uso com 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',
};

Java

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();

Pitão

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',
)

Ir

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",
}

C#

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 Passando estado em ações de email .

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

Node.js

// 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.
  });

Java

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());
}

Pitão

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)

Ir

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)

C#

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 for gerado, ele poderá ser inserido no e-mail de redefinição de senha personalizado e enviado por e-mail ao usuário correspondente usando um servidor SMTP personalizado.

Se você não estiver usando a página inicial de redefinição de senha padrão e criando seu próprio manipulador personalizado, consulte criação de 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 por e-mail. O email utilizado deve pertencer a um usuário existente.

Node.js

// 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.
  });

Java

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());
}

Pitão

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)

Ir

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)

C#

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 for gerado, ele poderá ser inserido no e-mail de verificação personalizado e enviado por e-mail ao usuário correspondente usando um servidor SMTP personalizado.

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

Antes de autenticar usuários com 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 email do usuário e um objeto ActionCodeSettings . O objeto ActionCodeSettings é necessário nesse caso para fornecer informações sobre para onde retornar o usuário depois que o link for clicado para a conclusão do login. A operação será resolvida com o link de ação por 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, pois esta operação pode ser usada para inscrever novos usuários em seu aplicativo por meio de link de e-mail.

Node.js

// 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.
  });

Java

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());
}

Pitão

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)

Ir

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)

C#

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 for gerado, ele poderá ser inserido no e-mail de login personalizado e enviado por e-mail 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 concluir o login depois que o usuário clicar no link e for redirecionado de volta ao aplicativo.