Trasferimento dello stato nelle azioni email

Puoi trasmettere lo stato tramite un URL continuo quando invii azioni email per la reimpostazione della password o la verifica dell'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 all'azione email direttamente da un'applicazione mobile quando è installata anziché da una pagina web.

Questo può essere estremamente utile nei seguenti scenari comuni:

  • Un utente che non ha eseguito l'accesso potrebbe tentare di accedere a contenuti che richiedono l'accesso. Tuttavia, l'utente potrebbe aver dimenticato la password e quindi attivare il flusso di reimpostazione della password. Alla fine 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 di newsletter potrebbe richiedere all'utente di verificare la propria email prima di iscriversi. L'utente seguirà il flusso di verifica dell'email e si aspetta di tornare all'app per completare l'abbonamento.

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

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

Trasferimento dello stato/dell'URL continuo nelle azioni email

Per trasmettere in modo sicuro un URL continuo, devi aggiungere il dominio per l'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.

È necessario fornire un'istanza di ActionCodeSettings quando si invia un'email di reimpostazione della password o un'email di verifica. Questa interfaccia accetta i seguenti parametri:

Parametro Tipo Descrizione
url Stringa

Imposta il link (URL di stato/URL continuo) che ha significati diversi in contesti diversi:

  • Quando il link viene gestito nei widget di azioni web, questo è il link diretto nel parametro di query continueUrl.
  • Quando il link viene gestito direttamente nell'app, questo è il parametro di query continueUrl nel link diretto del Dynamic Link.
iOSBundleId Stringa Imposta l'ID pacchetto. In questo modo, il link verrà aperto 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 bundle principale dell'app.
androidPackageName Stringa Imposta il nome del pacchetto Android. In questo modo, il link verrà aperto in un'app Android, se installata.
androidInstallApp bool Specifica se installare l'app per Android se il dispositivo la supporta e l'app non è già installata. Se questo campo viene fornito senza un packageName, viene generato un errore che spiega che packageName deve essere fornito insieme a questo campo.
androidMinimumVersion Stringa La versione minima dell'app supportata in questo flusso. Se è specificato minimumVersion e viene installata una versione precedente dell'app, l'utente viene indirizzato al Play Store per eseguire l'upgrade dell'app. L'app per Android deve essere registrata in Play Console.
handleCodeInApp bool Se il link all'azione 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 azione verrà inviato come link universale o app link per Android e verrà aperto dall'app, se installata. Nel caso di esito negativo, il codice verrà inviato prima al widget web e poi, se l'app è installata, verrà reindirizzato all'app.
dynamicLinkDomain Stringa (Deprecato, utilizza `linkDomain`) Imposta il dominio (o il sottodominio) del link dinamico da utilizzare per il link corrente se deve essere aperto utilizzando Firebase Dynamic Links. Poiché è possibile configurare più domini di link dinamici per progetto, questo campo consente di sceglierne esplicitamente uno. Se non viene fornito alcun dominio, viene utilizzato il primo dominio 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 di hosting predefinito (`web.app` o `firebaseapp.com`). Questa impostazione sostituisce l'impostazione `dynamicLinkDomain` ritirata.

L'esempio seguente mostra come inviare un link di verifica email che si aprirà prima in un'app mobile come Firebase Dynamic Link utilizzando il dominio personalizzato dei dynamic link example.page.link (app per iOS com.example.ios o app per Android com.example.android in cui l'app verrà installata se non è già installata e la versione minima è 12). Il link diretto conterrà il payload dell'URL di continuazione 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 utilizza Firebase Dynamic Links quando invia un link che deve essere aperto in un'applicazione mobile. Per utilizzare questa funzionalità, è necessario configurare Dynamic Links nella console Firebase.

  1. Attiva Firebase Dynamic Links:

    1. Nella console Firebase, apri la sezione Dynamic Links.

    2. Se non hai ancora accettato i termini di Dynamic Links e creato un dominio Dynamic Links, fallo ora.

    3. Se hai già creato un dominio Dynamic Links, prendine nota. Un dominio Dynamic Links in genere è simile al seguente esempio: 

      example.page.link

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

  2. Configurazione delle applicazioni Android:

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

  3. Configurazione delle applicazioni Apple:

    1. Se prevedi di gestire questi link dalla tua applicazione, l'ID pacchetto deve essere specificato nelle impostazioni progetto della console Firebase. Inoltre, devono essere specificati anche l'ID App Store e l'ID team Apple Developer.
    2. Dovrai anche configurare il dominio dei link universali FDL come dominio associato nelle funzionalità dell'applicazione.
    3. Se prevedi di distribuire la tua applicazione 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.

Gestione delle azioni email in un'applicazione web

Puoi specificare se vuoi gestire prima il link del codice azione da un'applicazione web e poi reindirizzare a un'altra pagina web o applicazione mobile dopo il completamento, a condizione che l'applicazione mobile sia disponibile. A tale scopo, imposta handleCodeInApp su false nell'oggetto ActionCodeSettings. Sebbene un ID pacchetto o un nome pacchetto Android non siano obbligatori, se li fornisci, l'utente potrà tornare all'app specificata al termine del codice di azione email.

L'URL web utilizzato qui è quello configurato nella sezione Modelli di azioni email. Ne viene eseguito il provisioning di uno predefinito per tutti i progetti. Per saperne di più su come personalizzare il gestore di azioni email, consulta Personalizzazione dei gestori email.

In questo caso, il link all'interno del parametro di query continueURL sarà un link FDL il cui payload è URL specificato nell'oggetto ActionCodeSettings. Sebbene tu possa 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 deep link.

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

Gestione delle azioni email in un'applicazione mobile

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

In questo caso, il link all'app mobile inviato all'utente sarà un link FDL il cui payload è l'URL del codice 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 azione può essere applicato direttamente da un'applicazione mobile in modo simile a come viene gestito dal flusso web descritto nella sezione Personalizzazione dei gestori email.

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