E-Mail-Aktions-Links generieren

Mobile Apps müssen manchmal mit Nutzern interagieren und sie auffordern, bestimmte Aktionen auszuführen, indem sie E‑Mails senden.

Mit den Firebase-Client-SDKs können Sie Nutzern E-Mails mit Links zum Zurücksetzen von Passwörtern, zur Bestätigung der E-Mail-Adresse und zur Anmeldung per E-Mail senden. Diese vorlagenbasierten E-Mails werden von Google gesendet und können nur beschränkt angepasst werden.

Wenn Sie stattdessen Ihre eigenen E-Mail-Vorlagen und Ihren eigenen E-Mail-Zustelldienst verwenden möchten, wird auf dieser Seite erläutert, wie Sie mit dem Firebase Admin SDK programmatisch die Aktionslinks für die oben genannten Abläufe generieren können, die Sie in E-Mails an Ihre Nutzer einfügen können.

Das bietet folgende Vorteile:

  • E‑Mail-Vorlagen anpassen Dazu gehören die Möglichkeit, neue Stile und benutzerdefiniertes Branding hinzuzufügen, Formulierungen und Logos zu ändern und Nutzer mit Vornamen statt mit vollständigem Namen anzusprechen.
  • Je nach Kontext unterschiedliche Vorlagen anwenden Wenn der Nutzer beispielsweise seine E-Mail-Adresse bestätigen muss, um einen Newsletter zu abonnieren, muss der Kontext möglicherweise im E-Mail-Inhalt angegeben werden. Ein weiteres Beispiel ist die Anmeldung über einen E‑Mail-Link: In einem Szenario kann dies vom selben Nutzer ausgelöst werden, in einem anderen als Einladung von einem anderen Nutzer. Der Kontext muss in der E‑Mail enthalten sein.
  • Benutzerdefinierte E‑Mail-Vorlagen lokalisieren
  • Der Link kann in einer sicheren Serverumgebung generiert werden.
  • Sie können anpassen, wie der Link geöffnet werden soll – über eine mobile App oder einen Browser – und wie zusätzliche Statusinformationen übergeben werden sollen.
  • Die Möglichkeit, die für mobile App-Abläufe verwendete mobile Linkdomain beim Erstellen des E-Mail-Aktionslinks anzupassen.

ActionCodeSettings initialisieren

Bevor Sie einen E‑Mail-Aktionslink generieren können, müssen Sie möglicherweise eine ActionCodeSettings-Instanz initialisieren.

Mit ActionCodeSettings können Sie zusätzlichen Status über eine Continue-URL übergeben, auf die zugegriffen werden kann, nachdem der Nutzer auf den E-Mail-Link geklickt hat. Außerdem kann der Nutzer nach Abschluss der Aktion zur App zurückkehren. Außerdem können Sie angeben, ob der E‑Mail-Aktionslink direkt über eine mobile Anwendung (sofern installiert) oder über einen Browser verarbeitet werden soll.

Für Links, die über eine mobile App geöffnet werden sollen, müssen Sie einige Aufgaben ausführen, um diese Links in Ihrer mobilen App zu erkennen. Hier finden Sie eine Anleitung zum Konfigurieren von mobilen Links für E-Mail-Aktionen.

Geben Sie die folgenden Daten an, um eine ActionCodeSettings-Instanz zu initialisieren:

Parameter Typ Beschreibung
url String

Legt den Link (Status-/Fortsetzungs-URL) fest, der in verschiedenen Kontexten unterschiedliche Bedeutungen hat:

  • Wenn der Link in den Web-Aktions-Widgets verarbeitet wird, ist dies der Deeplink im Abfrageparameter continueUrl.
  • Wenn der Link direkt in der App verarbeitet wird, ist dies der Abfrageparameter continueUrl im Deeplink des Hosting-Links.
iOS ({bundleId: string}|undefined) Legt die iOS-Paket-ID fest, damit Firebase Authentication ermitteln kann, ob ein reiner Weblink oder ein mobiler Link erstellt werden soll, der auf einem Apple-Gerät geöffnet wird.
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) Legt den Android-Paketnamen fest, damit Firebase Authentication ermitteln kann, ob ein reiner Weblink oder ein mobiler Link erstellt werden soll, der auf einem Android-Gerät geöffnet wird.
handleCodeInApp (boolean|undefined) Gibt an, ob der E-Mail-Aktionslink zuerst in einer mobilen App oder einem Weblink geöffnet wird. Der Standardwert ist "false". Wenn der Wert auf „true“ gesetzt ist, wird der Aktionscode-Link als universeller Link oder Android-App-Link gesendet und von der App geöffnet, sofern sie installiert ist. Im Fall „false“ wird der Code zuerst an das Web-Widget gesendet und dann wird bei „Weiter“ zur App weitergeleitet, sofern sie installiert ist.
linkDomain (String|undefined) Wenn für ein Projekt benutzerdefinierte Hosting-Link-Domains definiert sind, geben Sie an, welche verwendet werden soll, wenn der Link von einer bestimmten mobilen App geöffnet werden soll. Andernfalls wird automatisch die Standarddomain ausgewählt (z. B. PROJECT_ID.firebaseapp.com).
dynamicLinkDomain (String|undefined) Verworfen. Geben Sie diesen Parameter nicht an.

Das folgende Beispiel zeigt, wie Sie einen Link zur E-Mail-Bestätigung senden, der zuerst in einer mobilen App geöffnet wird. Der Deeplink enthält die Nutzlast der Continue-URL https://www.example.com/checkout?cartId=1234. Die verwendete benutzerdefinierte Hosting-Linkdomain ist custom-domain.com. Sie muss für die Verwendung mit Firebase Hosting konfiguriert sein.

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

Weitere Informationen finden Sie unter Status in E-Mail-Vorgängen übergeben.

Link für E-Mail zum Zurücksetzen des Passworts generieren

Geben Sie die E-Mail-Adresse des vorhandenen Nutzers und ein optionales ActionCodeSettings-Objekt an, um einen Link zum Zurücksetzen des Passworts zu generieren. Der Vorgang wird mit dem E‑Mail-Aktionslink abgeschlossen. Die verwendete E‑Mail-Adresse muss einem bestehenden Nutzer gehören.

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

Nachdem der Link generiert wurde, kann er in die benutzerdefinierte E‑Mail zum Zurücksetzen des Passworts eingefügt und dann über einen benutzerdefinierten SMTP-Server an den entsprechenden Nutzer gesendet werden.

Wenn Sie nicht die Standard-Landingpage zum Zurücksetzen des Passworts verwenden und einen eigenen benutzerdefinierten Handler erstellen, lesen Sie den Abschnitt Benutzerdefinierte E-Mail-Aktions-Handler erstellen.

E-Mail-Bestätigungslink generieren

Um einen Link zur E‑Mail-Bestätigung zu generieren, geben Sie die nicht bestätigte E‑Mail-Adresse des vorhandenen Nutzers und ein optionales ActionCodeSettings-Objekt an. Der Vorgang wird mit dem Link für die E-Mail-Aktion abgeschlossen. Die verwendete E‑Mail-Adresse muss einem bestehenden Nutzer gehören.

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

Nachdem der Link generiert wurde, kann er in die benutzerdefinierte Bestätigungs-E-Mail eingefügt und dann über einen benutzerdefinierten SMTP-Server an den entsprechenden Nutzer gesendet werden.

Wenn Sie nicht die Standard-Landingpage für die E-Mail-Bestätigung verwenden und einen eigenen benutzerdefinierten Handler erstellen, lesen Sie den Abschnitt Benutzerdefinierte E-Mail-Aktions-Handler erstellen.

E‑Mail-Link zur Anmeldung generieren

Bevor Sie Nutzer mit der Anmeldung per E-Mail-Link authentifizieren können, müssen Sie die Anmeldung per E-Mail-Link für Ihr Firebase-Projekt aktivieren.

Geben Sie die E-Mail-Adresse des Nutzers und ein ActionCodeSettings-Objekt an, um einen Anmeldelink zu generieren. Das ActionCodeSettings-Objekt ist in diesem Fall erforderlich, um Informationen dazu zu liefern, wohin der Nutzer nach dem Klicken auf den Link zurückgeleitet werden soll, wenn die Anmeldung abgeschlossen ist. Der Vorgang wird mit dem E‑Mail-Aktionslink abgeschlossen.

Im Gegensatz zum Zurücksetzen des Passworts und zur E-Mail-Bestätigung muss die verwendete E-Mail-Adresse nicht unbedingt zu einem bestehenden Nutzer gehören, da mit diesem Vorgang neue Nutzer über einen E-Mail-Link in Ihrer App registriert werden können.

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

Nachdem der Link generiert wurde, kann er in die benutzerdefinierte Anmelde-E-Mail eingefügt und dann über einen benutzerdefinierten SMTP-Server an den entsprechenden Nutzer gesendet werden.

Weitere Informationen zum Authentifizieren von Nutzern mit Firebase über E-Mail-Links So können Sie Informationen dazu bereitstellen, wie die Anmeldung abgeschlossen wird, nachdem der Nutzer auf den Link geklickt und zur App zurückgeleitet wurde.