Génération de liens d'action par e-mail

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 de distribution d'e-mails, cette page explique comment utiliser le SDK Admin Firebase pour générer par programmation les liens d'action pour les flux ci-dessus, que vous pouvez inclure dans les e-mails envoyés à vos utilisateurs.

Cette approche présente les avantages suivants :

  • Personnaliser des modèles d'e-mails. Vous pouvez ainsi ajouter de nouveaux styles et une image de marque personnalisée, modifier le texte et les logos, vous adresser aux 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 nécessaire dans le contenu de l'e-mail. Autre exemple : la connexion par lien dans un 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.
  • Localiser les modèles d'e-mails personnalisés.
  • Générer le lien à partir d'un environnement de serveur sécurisé.
  • Personnaliser la façon dont le lien doit être ouvert (via une application mobile ou un navigateur) et comment transmettre des informations d'état supplémentaires, etc.
  • Personnaliser le domaine de lien mobile utilisé pour les flux d'applications mobiles lors de la création du lien d'action par e-mail.

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. L'utilisateur peut également revenir à l'application une fois l'action terminée. De plus, vous pouvez spécifier si vous souhaitez gérer le lien d'action par e-mail directement à partir d'une application mobile lorsqu'elle est installée ou à partir d'un navigateur.

Pour les liens destinés à être ouverts via une application mobile, vous devez effectuer certaines tâches pour les détecter à partir de votre application mobile. Consultez les instructions sur la façon de configurer les liens mobiles 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 (état/URL de continuation) qui a différentes significations selon le contexte :

  • Lorsque le lien est géré dans les widgets d'action Web, il s'agit du lien profond dans le continueUrl paramètre de requête.
  • Lorsque le lien est géré directement dans l'application, il s'agit du continueUrl paramètre de requête dans le lien profond du Hosting lien.
iOS ({bundleId: string}|undefined) Définit l'ID de bundle iOS pour aider Firebase Authentication à déterminer s'il doit créer un lien Web uniquement ou un lien mobile qui s'ouvre sur un appareil Apple.
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) Définit le nom de package Android pour aider Firebase Authentication à déterminer s'il doit créer un lien Web uniquement ou un lien mobile qui s'ouvre sur un appareil Android.
handleCodeInApp (boolean|undefined) Indique si le lien d'action par e-mail s'ouvre d'abord dans une application mobile ou dans un lien Web. La valeur par défaut est "false" (inactif). Si la valeur est "true" (actif), le lien de code d'action est envoyé en tant que lien universel ou lien d'application Android, et il est ouvert par l'application si elle est installée. Si la valeur est "false" (inactif), le code est d'abord envoyé au widget Web, puis, en cas de continuation, il est redirigé vers l'application si elle est installée.
linkDomain (string|undefined) Lorsque des domaines de liens d'hébergement personnalisés sont définis pour un projet, spécifiez celui à utiliser lorsque le lien doit être ouvert par une application mobile spécifiée. Sinon, le domaine par défaut est automatiquement sélectionné (par exemple, PROJECT_ID.firebaseapp.com).
dynamicLinkDomain (string|undefined) Obsolète. Ne spécifiez pas ce paramètre.

L'exemple suivant montre comment envoyer un lien de validation d'e-mail qui s'ouvre d'abord dans une application mobile. Le lien profond contient la charge utile de l'URL de continuation https://www.example.com/checkout?cartId=1234. Le domaine de lien Hosting personnalisé utilisé est custom-domain.com, qui doit être configuré pour être utilisé avec 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',
  },
  // The domain must be configured in Firebase Hosting and owned by the project.
  linkDomain: 'custom-domain.com',
};

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",
    LinkDomain = "coolapp.page.link",
};

Pour en savoir plus, consultez 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 du 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 du 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 pour la réinitialisation du mot de passe et que vous créez votre propre gestionnaire personnalisé, consultez Créer des gestionnaires d'actions par e-mail personnalisés.

Générer un lien de validation d'e-mail

Pour générer un lien de validation d'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é, il peut être inséré dans l'e-mail de validation 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 pour la validation d'e-mail et que vous créez votre propre gestionnaire personnalisé, consultez Créer des gestionnaires d'actions par e-mail personnalisés.

Générer un lien d'e-mail pour la connexion

Avant de pouvoir authentifier les utilisateurs avec la connexion par lien dans un e-mail, vous devez activer cette fonctionnalité 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 requis dans ce cas pour fournir des informations sur l'endroit où rediriger l'utilisateur une fois qu'il a 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 d'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 inscrire de nouveaux utilisateurs à votre application via un lien dans un 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é, il peut être inséré dans l'e-mail de connexion personnalisé, puis envoyé à l'utilisateur correspondant à l'aide d'un serveur SMTP personnalisé.

En savoir plus sur l'authentification des utilisateurs avec Firebase à l'aide de liens dans des e-mails. Vous obtiendrez ainsi des informations sur la façon de terminer la connexion une fois que l'utilisateur a cliqué sur le lien et qu'il est redirigé vers l'application.