Les applications mobiles doivent parfois interagir avec les utilisateurs et les inviter à effectuer certaines actions en leur envoyant des e-mails.
Les SDK clients Firebase permettent d'envoyer aux utilisateurs des e-mails contenant des liens qu'ils peuvent utiliser pour réinitialiser les mots de passe, valider l'adresse e-mail et se connecter par e-mail. Ces e-mails basés sur des modèles sont envoyés par Google et offrent une personnalisation limitée.
Si vous préférez utiliser vos propres modèles d'e-mails et votre propre service d'envoi d'e-mails, cette page explique comment utiliser le SDK Firebase Admin pour générer de manière programmatique les liens d'action des flux ci-dessus, que vous pouvez inclure dans les e-mails envoyés à vos utilisateurs.
Cela présente les avantages suivants:
- Personnalisez des modèles d'e-mails. Vous pouvez ainsi ajouter de nouveaux styles et des éléments de branding personnalisés, modifier le libellé et les logos, adresser les utilisateurs par leur prénom au lieu de leur nom complet, etc.
- Appliquer différents modèles en fonction du contexte Par exemple, si l'utilisateur valide son adresse e-mail pour s'abonner à une newsletter, le contexte peut être fourni dans le contenu de l'e-mail. Un autre exemple est la connexion via un lien e-mail: dans un scénario, elle peut être déclenchée par le même utilisateur ou par une invitation d'un autre utilisateur. Le contexte doit être inclus dans l'e-mail.
- Localisez les modèles d'e-mails personnalisés.
- Possibilité de générer le lien à partir d'un environnement serveur sécurisé.
- Possibilité de personnaliser la façon dont le lien doit être ouvert, via une application mobile ou un navigateur, et de transmettre des informations d'état supplémentaires, etc.
- Possibilité de personnaliser le domaine de lien dynamique utilisé pour les flux d'application mobile lors de la création du lien d'action par e-mail, et même de spécifier un domaine de lien dynamique différent en fonction du contexte ou de l'application mobile.
Initialiser ActionCodeSettings
Avant de pouvoir générer un lien d'action par e-mail, vous devrez peut-être initialiser une instance ActionCodeSettings.
ActionCodeSettings vous permet de transmettre un état supplémentaire via une URL de continuation accessible une fois que l'utilisateur a cliqué sur le lien de l'e-mail. Cela permet également à l'utilisateur de revenir à l'application une fois l'action terminée. En outre, vous pouvez spécifier si vous souhaitez gérer le lien d'action de l'e-mail directement depuis une application mobile lorsqu'elle est installée ou depuis un navigateur.
Pour les liens destinés à être ouverts via une application mobile, vous devez activer Firebase Dynamic Links et effectuer certaines tâches pour les détecter depuis votre application mobile. Consultez les instructions pour configurer Firebase Dynamic Links pour les actions par e-mail.
Pour initialiser une instance ActionCodeSettings, fournissez les données suivantes:
| Paramètre | Type | Description |
|---|---|---|
url |
chaîne | Définit le lien (URL d'état/de poursuite), qui a différentes significations selon le contexte:
|
iOS |
({bundleId: string}|undefined) | Définit l'ID du bundle. Le lien sera alors essayé dans une application Apple si elle est installée. L'application doit être enregistrée dans la console. |
android |
({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) | Définit le nom du package Android. Le lien sera alors essayé dans une application Android si elle est installée. Si installApp est transmis, il spécifie si l'application Android doit être installée si l'appareil est compatible avec celle-ci et si elle n'est pas déjà installée. Si ce champ est fourni sans packageName, une erreur s'affiche, expliquant que packageName doit être fourni avec ce champ.
Si minimumVersion est spécifié et qu'une ancienne version de l'application est installée, l'utilisateur est redirigé vers le Play Store pour mettre à niveau l'application. L'application Android doit être enregistrée dans la console. |
handleCodeInApp |
(boolean|undefined) | Indique si le lien d'action par e-mail doit s'ouvrir d'abord dans une application mobile ou dans un lien Web. La valeur par défaut est "false" (inactif). Si cette valeur est définie sur "true", le lien du code d'action sera envoyé en tant que lien universel ou Android App Link, et sera ouvert par l'application si elle est installée. Dans le cas contraire, le code sera d'abord envoyé au widget Web, puis le bouton "Continuer" redirige vers l'application si elle est installée. |
dynamicLinkDomain |
(chaîne|undefined) | Définit le domaine (ou sous-domaine) de lien dynamique à utiliser pour le lien actuel s'il doit être ouvert à l'aide de Firebase Dynamic Links. Étant donné que plusieurs domaines de liaison dynamique peuvent être configurés par projet, ce champ permet d'en choisir un explicitement. Si aucun n'est fourni, le domaine le plus ancien est utilisé par défaut. |
L'exemple suivant montre comment envoyer un lien de validation par e-mail qui s'ouvre d'abord dans une application mobile en tant que lien dynamique Firebase (application Apple com.example.ios ou application Android com.example.android où l'application s'installe si elle n'est pas déjà installée et que la version minimale est 12). Le lien profond contiendra la charge utile de l'URL de continuation https://www.example.com/checkout?cartId=1234. Le domaine de lien dynamique utilisé est coolapp.page.link, qui doit être configuré pour être utilisé avec 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();
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",
};
Pour en savoir plus, consultez la section Transmettre l'état dans les actions par e-mail.
Générer un lien d'e-mail de réinitialisation du mot de passe
Pour générer un lien de réinitialisation de mot de passe, fournissez l'adresse e-mail de l'utilisateur existant et un objet ActionCodeSettings facultatif. L'opération sera résolue avec le lien d'action par e-mail. L'adresse e-mail utilisée doit appartenir à un utilisateur existant.
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);
Une fois le lien généré, il peut être inséré dans l'e-mail de réinitialisation de mot de passe personnalisé, puis envoyé à l'utilisateur correspondant à l'aide d'un serveur SMTP personnalisé.
Si vous n'utilisez pas la page de destination par défaut de la réinitialisation de mot de passe et que vous créez votre propre gestionnaire personnalisé, consultez la section Créer des gestionnaires d'actions de messagerie personnalisés.
Générer un lien de validation par e-mail
Pour générer un lien de validation de l'adresse e-mail, fournissez l'adresse e-mail non validée de l'utilisateur existant et un objet ActionCodeSettings facultatif. L'opération sera résolue avec le lien d'action par e-mail.
L'adresse e-mail utilisée doit appartenir à un utilisateur existant.
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);
Une fois le lien généré, vous pouvez l'insérer dans l'e-mail de validation personnalisé, puis l'envoyer à l'utilisateur correspondant à l'aide d'un serveur SMTP personnalisé.
Si vous n'utilisez pas la page de destination de validation de l'adresse e-mail par défaut et que vous créez votre propre gestionnaire personnalisé, consultez la section Créer des gestionnaires d'actions de messagerie personnalisés.
Générer un lien par e-mail pour la connexion
Avant de pouvoir authentifier des utilisateurs avec la connexion par lien e-mail, vous devez activer la connexion par lien e-mail pour votre projet Firebase.
Pour générer un lien de connexion, fournissez l'adresse e-mail de l'utilisateur et un objet ActionCodeSettings. L'objet ActionCodeSettings est obligatoire dans ce cas pour fournir des informations sur l'emplacement où renvoyer l'utilisateur après avoir cliqué sur le lien pour terminer la connexion. L'opération sera résolue avec le lien d'action par e-mail.
Contrairement à la réinitialisation du mot de passe et à la validation de l'adresse e-mail, l'adresse e-mail utilisée n'a pas nécessairement besoin d'appartenir à un utilisateur existant, car cette opération peut être utilisée pour enregistrer de nouveaux utilisateurs dans votre application via un lien par 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);
Une fois le lien généré, vous pouvez l'insérer dans l'e-mail de connexion personnalisé, puis l'envoyer à l'utilisateur correspondant à l'aide d'un serveur SMTP personnalisé.
Découvrez comment authentifier les utilisateurs avec Firebase à l'aide de liens d'e-mail. Cela permet de fournir des informations sur la procédure de connexion une fois que l'utilisateur a cliqué sur le lien et a été redirigé vers l'application.