À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 para dispositivos móveis usado para fluxos de apps para dispositivos móveis ao criar o link de ação do e-mail.
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, 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 com um app para dispositivos móveis, será necessário realizar algumas tarefas para detectá-los no app. Consulte as instruções sobre como configurar links para dispositivos móveis 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:
|
iOS |
({bundleId: string}|undefined) | Define o ID do pacote iOS para ajudar a Firebase Authentication a determinar se ela precisa criar um link somente para Web ou um link para dispositivos móveis que seja aberto em um dispositivo Apple. |
android |
({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) | Define o nome do pacote Android para ajudar o Firebase Authentication a determinar se ele precisa criar um link somente para Web ou um link para dispositivos móveis que seja aberto em um dispositivo Android. |
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 é falso. 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 "false", o código será enviado primeiro ao widget da Web e, em seguida, redirecionará para o app, se estiver instalado. |
linkDomain |
(string|undefined) | Quando os domínios de link de hospedagem personalizados são definidos para um projeto,
especifique qual deles usar quando o link for aberto por um app para dispositivos móveis
especificado. Caso contrário, o domínio padrão será selecionado automaticamente (por
exemplo,
PROJECT_ID.firebaseapp.com |
dynamicLinkDomain |
(string|undefined) | Obsoleto. Não especifique esse parâmetro. |
O exemplo a seguir ilustra como enviar um link de verificação de e-mail que
será aberto primeiro em um app para dispositivos móveis. O link direto conterá o payload do URL
de confirmação https://www.example.com/checkout?cartId=1234. O domínio de link Hosting
personalizado usado é custom-domain.com, que precisa ser configurado para uso com
Firebase Hosting.
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();
Python
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',
)
Go
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 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.
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());
}
Python
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)
Go
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 é 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.
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());
}
Python
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)
Go
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 é 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.
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());
}
Python
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)
Go
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 é 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.