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.

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

// 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 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.

// 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 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.

// 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 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.