Status in E-Mail-Aktionen übergeben

Sie können den Status über eine „continue“-URL übergeben, wenn Sie E-Mail-Aktionen zum Zurücksetzen von Passwörtern oder zum Bestätigen der E-Mail-Adresse eines Nutzers senden. Dadurch kann der Nutzer nach Abschluss der Aktion zur App zurückkehren. Außerdem können Sie festlegen, ob der E‑Mail-Aktionslink direkt über eine mobile App verarbeitet werden soll, wenn diese installiert ist, anstatt über eine Webseite.

Dies kann in den folgenden gängigen Szenarien äußerst nützlich sein:

  • Ein Nutzer, der derzeit nicht angemeldet ist, versucht möglicherweise, auf Inhalte zuzugreifen, für die eine Anmeldung erforderlich ist. Es kann jedoch sein, dass der Nutzer sein Passwort vergessen hat und daher den Ablauf zum Zurücksetzen des Passworts auslöst. Am Ende des Ablaufs erwartet der Nutzer, dass er zu dem Bereich der App zurückkehrt, auf den er zugreifen wollte.

  • Eine Anwendung darf nur Zugriff auf bestätigte Konten bieten. Bei einer Newsletter-App muss der Nutzer beispielsweise seine E-Mail-Adresse bestätigen, bevor er den Newsletter abonnieren kann. Der Nutzer durchläuft den E‑Mail-Bestätigungsvorgang und erwartet, dass er zur App zurückgeleitet wird, um sein Abo abzuschließen.

  • Wenn ein Nutzer in einer Apple-App einen Vorgang zum Zurücksetzen des Passworts oder zur E-Mail-Bestätigung startet, erwartet er in der Regel, dass er den Vorgang in der App abschließen kann. Die Möglichkeit, den Status über die Continue-URL zu übergeben, macht dies möglich.

Die Möglichkeit, den Status über eine „continue“-URL zu übergeben, ist eine leistungsstarke Funktion, die Firebase Auth bietet und die die Nutzerfreundlichkeit erheblich verbessern kann.

Status/URL zur Weiterleitung in E-Mail-Aktionen übergeben

Damit eine Weiterleitungs-URL sicher übergeben werden kann, muss die Domain für die URL in der Firebase-Konsole auf die Zulassungsliste gesetzt werden. Dies erfolgt im Bereich Authentifizierung, indem Sie diese Domain der Liste der Autorisierten Domains auf dem Tab Anmeldemethode hinzufügen, sofern sie dort noch nicht aufgeführt ist.

Beim Senden einer E-Mail zum Zurücksetzen des Passworts oder einer Bestätigungs-E-Mail muss eine ActionCodeSettings-Instanz angegeben werden. Diese Schnittstelle verwendet die folgenden Parameter:

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 continueUrl-Abfrageparameter im Deeplink des Dynamic Link.
iOSBundleId String Legt die Bundle-ID fest. Dadurch wird versucht, den Link in einer Apple-App zu öffnen, falls diese installiert ist. Die App muss in der Play Console registriert sein. Wenn keine Set-ID angegeben ist, wird der Wert dieses Felds auf die Set-ID des Haupt-Bundles der App festgelegt.
androidPackageName String Legt den Android-Paketnamen fest. Dadurch wird versucht, den Link in einer Android-App zu öffnen, sofern diese installiert ist.
androidInstallApp bool Gibt an, ob die Android-App installiert werden soll, wenn das Gerät sie unterstützt und die App noch nicht installiert ist. Wenn dieses Feld ohne packageName angegeben wird, wird ein Fehler ausgegeben, in dem erklärt wird, dass packageName zusammen mit diesem Feld angegeben werden muss.
androidMinimumVersion String Die Mindestversion der App, die in diesem Ablauf unterstützt wird. Wenn „minimumVersion“ angegeben ist und eine ältere Version der App installiert ist, wird der Nutzer zum Play Store weitergeleitet, um die App zu aktualisieren. Die Android-App muss in der Console registriert sein.
handleCodeInApp bool Gibt an, ob der E-Mail-Aktionslink zuerst in einer mobilen App oder als 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 „continue“ zur App weitergeleitet, sofern sie installiert ist.
dynamicLinkDomain String (Eingestellt, verwenden Sie `linkDomain`) Legt die Dynamic Link-Domain (oder ‑Subdomain) fest, die für den aktuellen Link verwendet werden soll, wenn er mit Firebase Dynamic Links geöffnet werden soll. Da pro Projekt mehrere dynamische Linkdomains konfiguriert werden können, kann in diesem Feld explizit eine ausgewählt werden. Wenn keine angegeben ist, wird standardmäßig die erste Domain verwendet. linkDomain String Die optionale benutzerdefinierte Firebase Hosting-Domain, die verwendet werden soll, wenn der Link über eine bestimmte mobile App geöffnet werden soll. Die Domain muss in Firebase Hosting konfiguriert sein und dem Projekt gehören. Dies darf keine Standard-Hosting-Domain (`web.app` oder `firebaseapp.com`) sein. Diese Einstellung ersetzt die eingestellte Einstellung `dynamicLinkDomain`.

Im folgenden Beispiel wird veranschaulicht, wie Sie einen Link zur E‑Mail-Bestätigung senden, der zuerst in einer mobilen App als Firebase Dynamic Link mit der benutzerdefinierten Dynamic Link-Domain example.page.link geöffnet wird (iOS-App com.example.ios oder Android-App com.example.android, wobei die App installiert wird, falls sie noch nicht installiert ist und die Mindestversion 12 ist). Der Deeplink enthält die Nutzlast der Continue-URL https://www.example.com/?email=user@example.com.

final user = FirebaseAuth.instance.currentUser;

final actionCodeSettings = ActionCodeSettings(
  url: "http://www.example.com/verify?email=${user?.email}",
  iOSBundleId: "com.example.ios",
  androidPackageName: "com.example.android",
);

await user?.sendEmailVerification(actionCodeSettings);

Firebase Auth verwendet Firebase Dynamic Links, wenn ein Link gesendet wird, der in einer mobilen App geöffnet werden soll. Damit Sie dieses Feature nutzen können, müssen Dynamic Links in der Firebase Console konfiguriert werden.

  1. Firebase Dynamic Links aktivieren:

    1. Öffnen Sie in der Firebase Console den Bereich Dynamic Links.

    2. Wenn Sie die Nutzungsbedingungen für Dynamic Links noch nicht akzeptiert und eine Dynamic Links-Domain erstellt haben, tun Sie dies jetzt.

    3. Wenn Sie bereits eine Dynamic Links-Domain erstellt haben, notieren Sie sie sich. Eine Dynamic Links-Domain sieht normalerweise so aus: 

      example.page.link

    4. Sie benötigen diesen Wert, wenn Sie Ihre Apple- oder Android-App so konfigurieren, dass sie den eingehenden Link abfängt.

  2. Android-Apps konfigurieren:

    1. Wenn Sie diese Links in Ihrer Android-App verarbeiten möchten, muss der Android-Paketname in den Projekteinstellungen der Firebase Console angegeben werden. Außerdem müssen der SHA‑1- und der SHA‑256-Fingerabdruck des Anwendungszertifikats angegeben werden.
    2. Außerdem müssen Sie den Intent-Filter für den Deeplink in Ihrer AndroidManifest.xml-Datei konfigurieren.
    3. Weitere Informationen finden Sie unter Anleitung zum Empfangen von dynamischen Android-Links.

  3. Apple-Anwendungen konfigurieren:

    1. Wenn Sie diese Links in Ihrer Anwendung verarbeiten möchten, muss die Bundle-ID in den Projekteinstellungen der Firebase Console angegeben werden. Außerdem müssen die App Store-ID und die Apple Developer-Team-ID angegeben werden.
    2. Außerdem müssen Sie die universelle Link-Domain für dynamische Links als zugehörige Domain in den Funktionen Ihrer Anwendung konfigurieren.
    3. Wenn Sie Ihre Anwendung für iOS-Versionen 8 und niedriger bereitstellen möchten, müssen Sie Ihre Bundle-ID als benutzerdefiniertes Schema für eingehende URLs festlegen.
    4. Weitere Informationen finden Sie unter Dynamische Links für Apple-Plattformen empfangen.

E-Mail-Aktionen in einer Webanwendung verarbeiten

Sie können festlegen, ob der Aktionscodelink zuerst von einer Webanwendung verarbeitet und dann nach erfolgreichem Abschluss zu einer anderen Webseite oder mobilen Anwendung weitergeleitet werden soll, sofern die mobile Anwendung verfügbar ist. Dazu wird handleCodeInApp im ActionCodeSettings-Objekt auf false gesetzt. Eine Bundle-ID oder ein Android-Paketname sind zwar nicht erforderlich, aber wenn Sie sie angeben, kann der Nutzer nach Abschluss des E-Mail-Aktionscodes zur angegebenen App zurückgeleitet werden.

Die hier verwendete Web-URL ist die, die im Abschnitt „E-Mail-Aktionsvorlagen“ konfiguriert ist. Für alle Projekte wird ein Standard-Servicekonto bereitgestellt. Weitere Informationen zum Anpassen des E‑Mail-Aktions-Handlers finden Sie unter E‑Mail-Handler anpassen.

In diesem Fall ist der Link im Abfrageparameter continueURL ein FDL-Link, dessen Nutzlast der im ActionCodeSettings-Objekt angegebene URL ist. Sie können den eingehenden Link von Ihrer App abfangen und verarbeiten, ohne dass zusätzliche Abhängigkeiten erforderlich sind. Wir empfehlen jedoch, die FDL-Clientbibliothek zu verwenden, um den Deeplink zu parsen.

Bei der Verarbeitung von E-Mail-Aktionen wie der E-Mail-Bestätigung muss der Aktionscode aus dem oobCode-Suchparameter des Deeplinks geparst und dann über applyActionCode angewendet werden, damit die Änderung wirksam wird, d.h. die E-Mail-Adresse bestätigt wird.

E‑Mail-Aktionen in einer mobilen Anwendung verarbeiten

Sie können festlegen, ob der Link zum Aktionscode zuerst in Ihrer mobilen Anwendung verarbeitet werden soll, sofern sie installiert ist. Bei Android-Anwendungen können Sie über die androidInstallApp auch angeben, dass die App installiert werden soll, wenn das Gerät sie unterstützt und sie noch nicht installiert ist. Wenn der Link auf einem Gerät angeklickt wird, das die mobile App nicht unterstützt, wird er stattdessen auf einer Webseite geöffnet. Dazu wird handleCodeInApp im ActionCodeSettings-Objekt auf true gesetzt. Außerdem muss der Android-Paketname oder die Bundle-ID der mobilen App angegeben werden.Die hier verwendete Fallback-Web-URL, wenn keine mobile App verfügbar ist, ist die, die im Abschnitt „E-Mail-Aktionsvorlagen“ konfiguriert ist. Für alle Projekte wird ein Standard-Servicekonto bereitgestellt. Weitere Informationen zum Anpassen des E‑Mail-Aktions-Handlers finden Sie unter E‑Mail-Handler anpassen.

In diesem Fall ist der an den Nutzer gesendete Link zur mobilen App ein FDL-Link, dessen Nutzlast die in der Console konfigurierte Aktionscode-URL mit den Abfrageparametern oobCode, mode, apiKey und continueUrl ist. Letzteres ist das ursprüngliche URL, das im ActionCodeSettings-Objekt angegeben ist. Sie können den eingehenden Link von Ihrer App ohne zusätzliche Abhängigkeit abfangen und verarbeiten. Wir empfehlen jedoch, die FDL-Clientbibliothek zu verwenden, um den Deeplink für Sie zu parsen. Der Aktionscode kann direkt über eine mobile App angewendet werden, ähnlich wie im Webflow, der im Abschnitt E-Mail-Handler anpassen beschrieben wird.

Bei der Verarbeitung von E-Mail-Aktionen wie der E-Mail-Bestätigung muss der Aktionscode aus dem oobCode-Suchparameter des Deeplinks geparst und dann über applyActionCode angewendet werden, damit die Änderung wirksam wird, d.h. die E-Mail-Adresse bestätigt wird.