Trasferimento dello stato nelle azioni email

Puoi passare lo stato tramite un URL continuo quando invii azioni via email per reimpostare le password o verificare l'indirizzo email di un utente. In questo modo, l'utente può tornare all'app dopo aver completato l'azione. Inoltre, puoi specificare se gestire il link dell'azione via email direttamente da un'app mobile quando è installata anziché da una pagina web.

Questa funzionalità può essere estremamente utile nei seguenti scenari comuni:

  • Un utente che non ha eseguito l'accesso potrebbe provare ad accedere a contenuti che richiedono l'accesso. Tuttavia, l'utente potrebbe aver dimenticato la password e quindi attivare il flusso di reimpostazione della password. Al termine del flusso, l'utente si aspetta di tornare alla sezione dell'app a cui stava cercando di accedere.

  • Un'applicazione può offrire l'accesso solo agli account verificati. Ad esempio, un'app per newsletter potrebbe richiedere all'utente di verificare il suo indirizzo email prima di abbonarsi. L'utente seguirà il flusso di verifica dell'indirizzo email e si aspetta di tornare all'app per completare l'abbonamento.

  • In generale, quando un utente inizia un flusso di reimpostazione della password o di verifica dell'indirizzo email su un'app Apple, si aspetta di completare il flusso all'interno dell'app. La possibilità di passare lo stato tramite l'URL continuo lo rende possibile.

La possibilità di passare lo stato tramite un URL continuo è una funzionalità potente fornita da Firebase Authentication che può migliorare notevolmente l'esperienza utente.

Passare lo stato/l'URL continuo nelle azioni via email

Per passare in modo sicuro un URL continuo, devi aggiungere il dominio dell'URL come dominio autorizzato:

  1. Nella console Firebase, vai alla scheda Sicurezza > Autenticazione > Impostazioni.

  2. Nella sezione Domini autorizzati, fai clic su Aggiungi dominio e aggiungi l'URL.

Quando invii un'email di reimpostazione della password o un'email di verifica, devi fornire un'istanza di ActionCodeSettings. Questa interfaccia accetta i seguenti parametri:

Parametro Tipo Descrizione
url Stringa

Imposta il link (stato/URL continuo) che ha significati diversi in base al contesto:

  • Quando il link viene gestito nei widget delle azioni web, si tratta del link diretto nel parametro di query continueUrl.
  • Quando il link viene gestito direttamente nell'app, si tratta del continueUrl parametro di query nel link diretto del link dinamico.
iOSBundleId Stringa Imposta l'ID pacchetto. Se è installata, verrà tentata l'apertura del link in un'app Apple se è installata. L'app deve essere registrata nella console. Se non viene fornito alcun ID pacchetto, il valore di questo campo viene impostato sull'ID pacchetto del pacchetto principale dell'app.
androidPackageName Stringa Imposta il nome del pacchetto Android. Se è installata, verrà tentata l'apertura del link in un 'app Android.
androidInstallApp bool Specifica se installare l'app Android se il dispositivo la supporta e non è già installata. Se questo campo viene fornito senza un nome del pacchetto, viene generato un errore che spiega che il nome del pacchetto deve essere fornito insieme a questo campo.
androidMinimumVersion Stringa La versione minima dell'app supportata in questo flusso. Se viene specificata una versione minima e ne è installata una precedente dell'app, l'utente viene indirizzato al Play Store per eseguire l'upgrade dell'app. L'app Android deve essere registrata nella console.
handleCodeInApp bool Indica se il link dell'azione via email verrà aperto prima in un'app mobile o in un link web. Il valore predefinito è false. Se impostato su true, il link del codice dell'azione verrà inviato come link universale o app link Android e verrà aperto dall'app, se installata. Se impostato su false, il codice verrà inviato prima al widget web e poi, se installata, verrà reindirizzato all'app.
dynamicLinkDomain Stringa (Obsoleto, utilizza `linkDomain`) Imposta il dominio (o il sottodominio) del link dinamico da utilizzare per il link corrente se deve essere aperto utilizzando i link dinamici Firebase. Poiché è possibile configurare più domini di link dinamici per progetto, questo campo consente di sceglierne uno in modo esplicito. Se non ne viene fornito nessuno, per impostazione predefinita viene utilizzato il primo dominio viene utilizzato per impostazione predefinita. linkDomain Stringa Il dominio Firebase Hosting personalizzato facoltativo da utilizzare quando il link deve essere aperto tramite un'app mobile specificata. Il dominio deve essere configurato in Firebase Hosting e di proprietà del progetto. Non può essere un dominio Hosting predefinito (`web.app` o `firebaseapp.com`). Sostituisce l'impostazione `dynamicLinkDomain` obsoleta.

L'esempio seguente illustra come inviare un link di verifica dell'indirizzo email che verrà aperto prima in un'app mobile come link dinamico Firebase utilizzando il dominio di link dinamico personalizzato example.page.link (app iOS com.example.ios o app Android com.example.android, dove l'app verrà installata se non è già installata e la versione minima è 12). Il link diretto conterrà il payload dell'URL continuo 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 Authentication utilizza i link dinamici Firebase quando invia un link che deve essere aperto in un'app mobile. Per utilizzare questa funzionalità, i link dinamici devono essere configurati nella console Firebase.

  1. Abilita i link dinamici Firebase:

    1. Nella console Firebase, apri la sezione Link dinamici.

    2. Se non hai ancora accettato i Termini di servizio dei link dinamici e creato un dominio di link dinamici, fallo ora.

    3. Se hai già creato un dominio di link dinamici, prendine nota. Un dominio di link dinamici in genere ha il seguente aspetto: 

      example.page.link

    4. Questo valore ti servirà quando configurerai l'app Apple o Android per intercettare il link in entrata.

  2. Configurare le app per Android:

    1. Se prevedi di gestire questi link dalla tua app per Android, il nome del pacchetto Android deve essere specificato nelle impostazioni del progetto della console Firebase. Inoltre, devono essere forniti l'SHA-1 e l'SHA-256 del certificato dell'applicazione.
    2. Dovrai anche configurare il filtro per intent per il link diretto nel file AndroidManifest.xml.
    3. Per saperne di più, consulta le istruzioni per la ricezione dei link dinamici Android.

  3. Configurare le app Apple:

    1. Se prevedi di gestire questi link dalla tua app, l'ID pacchetto deve essere specificato nelle impostazioni del progetto della console Firebase. Inoltre, devono essere specificati anche l'ID App Store e l'ID team sviluppatore Apple.
    2. Dovrai anche configurare il dominio del link universale FDL come dominio associato nelle funzionalità dell'app.
    3. Se prevedi di distribuire la tua app alle versioni di iOS 8 e precedenti, dovrai impostare l'ID pacchetto come schema personalizzato per gli URL in entrata.
    4. Per saperne di più, consulta le istruzioni per la ricezione dei link dinamici delle piattaforme Apple.

Gestire le azioni via email in un'applicazione web

Puoi specificare se vuoi gestire prima il link del codice dell'azione da un'applicazione web e poi reindirizzare a un'altra pagina web o app mobile dopo il completamento, a condizione che l'app mobile sia disponibile. Per farlo, imposta handleCodeInApp su false nell'oggetto ActionCodeSettings. Anche se non sono obbligatori, se fornisci un ID pacchetto o un nome del pacchetto Android, l'utente potrà essere reindirizzato all'app specificata al completamento del codice dell'azione via email.

L'URL web utilizzato qui è quello configurato nella sezione dei modelli di azioni via email. Per tutti i progetti viene fornito un URL predefinito. Per saperne di più su come personalizzare il gestore delle azioni via email, consulta Personalizzare i gestori delle email.

In questo caso, il link all'interno del parametro di query continueURL sarà un link FDL il cui payload è l'URL specificato nell'ActionCodeSettings oggetto. Anche se puoi intercettare e gestire il link in entrata dalla tua app senza alcuna dipendenza aggiuntiva, ti consigliamo di utilizzare la libreria client FDL per analizzare il link diretto.

Quando gestisci azioni via email come la verifica dell'indirizzo email, il codice dell'azione dal parametro di query oobCode deve essere analizzato dal link diretto e poi applicato tramite applyActionCode affinché la modifica abbia effetto, ovvero l'indirizzo email da verificare.

Gestire le azioni via email in un'app mobile

Puoi specificare se vuoi gestire prima il link del codice dell'azione all'interno della tua app mobile, a condizione che sia installata. Con le app per Android, puoi anche specificare tramite androidInstallApp che l'app deve essere installata se il dispositivo la supporta e non è già installata. Se fai clic sul link da un dispositivo che non supporta l'app mobile, il link viene aperto da una pagina web. Per farlo, imposta handleCodeInApp su true nell'oggetto ActionCodeSettings. Dovrai anche specificare il nome del pacchetto Android o l'ID pacchetto dell'app mobile.L'URL web di riserva utilizzato qui, quando non è disponibile un'app mobile, è quello configurato nella sezione dei modelli di azioni via email. Per tutti i progetti viene fornito un URL predefinito. Per saperne di più su come personalizzare il gestore delle azioni via email, consulta Personalizzare i gestori delle email.

In questo caso, il link dell'app mobile inviato all'utente sarà un link FDL il cui payload è l'URL del codice dell'azione, configurato nella console, con i parametri di query oobCode, mode, apiKey e continueUrl. Quest'ultimo sarà l'URL originale specificato nell'oggetto ActionCodeSettings. Anche se puoi intercettare e gestire il link in entrata dalla tua app senza alcuna dipendenza aggiuntiva, ti consigliamo di utilizzare la libreria client FDL per analizzare il link diretto. Il codice dell'azione può essere applicato direttamente da un'app mobile in modo simile a come viene gestito da flusso web descritto nella sezione Personalizzare i gestori delle email.

Quando gestisci azioni via email come la verifica dell'indirizzo email, il codice dell'azione dal parametro di query oobCode deve essere analizzato dal link diretto e poi applicato tramite applyActionCode affinché la modifica abbia effetto, ovvero l'indirizzo email da verificare.