Generazione di link ad azioni e-mail

A volte le app mobile devono interagire con gli utenti e chiedere loro di intraprendere determinate azioni inviando email.

Gli SDK client di Firebase consentono di inviare agli utenti email contenenti link che possono utilizzare per reimpostare le password, verificare l'indirizzo email e accedere tramite email. Queste email basate su modelli vengono inviate da Google e hanno una personalizzazione limitata.

Se invece vuoi utilizzare i tuoi modelli email e il tuo servizio di invio email, in questa pagina viene spiegato come utilizzare l'SDK Firebase Admin per generare in modo programmatico i link di azione per i flussi precedenti, che puoi includere nelle email inviate agli utenti.

Questa opzione offre i seguenti vantaggi:

  • Personalizzare i modelli email. Ciò include la possibilità di aggiungere nuovi stili e branding personalizzati, cambiare formulazioni e loghi, rivolgersi agli utenti per nome invece che per nome completo e così via.
  • Applica modelli diversi a seconda del contesto. Ad esempio, se l'utente sta verificando il proprio indirizzo email per iscriversi a una newsletter, il contesto potrebbe dover essere fornito nei contenuti dell'email. Un altro esempio è l'accesso tramite link email: in un scenario, questa operazione può essere attivata dallo stesso utente o come invito da parte di un altro utente. Il contesto deve essere incluso nell'email.
  • Localizzare i modelli email personalizzati.
  • Possibilità di generare il link da un ambiente server sicuro.
  • Possibilità di personalizzare la modalità di apertura del link, tramite un'app mobile o un browser, e di trasmettere ulteriori informazioni sullo stato e così via.
  • Possibilità di personalizzare il dominio del link dinamico utilizzato per i flussi delle app mobile durante la compilazione del link all'azione email e persino di specificare un dominio del link dinamico diverso a seconda del contesto o dell'app mobile.

Inizializza ActionCodeSettings

Prima di poter generare un link all'azione email, potrebbe essere necessario inizializzare un'istanza ActionCodeSettings.

ActionCodeSettings ti consentono di passare uno stato aggiuntivo tramite un URL di continuazione accessibile dopo che l'utente fa clic sul link dell'email. Inoltre, offre all'utente la possibilità di tornare all'app al termine dell'azione. Inoltre, puoi specificare se gestire il link all'azione email direttamente da un'applicazione mobile quando è installata o da un browser.

Per i link che devono essere aperti tramite un'app mobile, devi attivare Firebase Dynamic Links ed eseguire alcune attività per rilevare questi link dalla tua app mobile. Consulta le istruzioni su come configurare Firebase Dynamic Links per le azioni email.

Per inizializzare un'istanza ActionCodeSettings, fornisci i seguenti dati:

Parametro Tipo Descrizione
url stringa

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

  • Quando il link viene gestito nei widget di azioni web, si tratta del 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 link dinamico.
iOS ({bundleId: string}|undefined) Imposta l'ID pacchetto. Verrà tentato di aprire il link in un'app Apple, se è installata. L'app deve essere registrata nella console.
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) Imposta il nome del pacchetto Android. Verrà effettuato un tentativo di aprire il link in un'app per Android se è installata. Se viene passato installApp, 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 valore packageName, viene generato un errore che spiega che packageName deve essere fornito insieme a questo campo. Se viene specificato minimumVersion ed è 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 Console.
handleCodeInApp (booleano|undefined) Indica se il link all'azione email deve essere aperto prima in un'app mobile o in un link web. Il valore predefinito è false. Se impostato su true, il link al codice di azione verrà inviato come link universale o link app per Android e verrà aperto dall'app, se installata. In caso falso, il codice verrà inviato prima al widget web e poi, dopo continuare, reindirizzerà all'app, se installata.
dynamicLinkDomain (stringa|non definita) Imposta il dominio (o 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 uno esplicitamente. Se non viene fornito nessuno, per impostazione predefinita viene utilizzato il dominio più antico.

L'esempio seguente illustra come inviare un link di verifica email che si aprirà inizialmente in un'app mobile come link dinamico Firebase (app Apple com.example.ios o app Android com.example.android in cui verrà installata l'app se non è già installata e la versione minima è 12). Il link diretto conterrà il payload dell'URL di continuahttps://www.example.com/checkout?cartId=1234. Il dominio del link dinamico utilizzato è coolapp.page.link, che deve essere configurato per l'utilizzo con Firebase Dynamic Link.

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',
  },
  // FDL custom domain.
  dynamicLinkDomain: 'coolapp.page.link',
};

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',
)

Vai

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",
};

Per scoprire di più, consulta Passare lo stato nelle azioni email.

Per generare un link per la reimpostazione della password, fornisci l'indirizzo email dell'utente esistente e un oggetto ActionCodeSettings facoltativo. L'operazione verrà risolta con il link all'azione email. L'indirizzo email utilizzato deve appartenere a un utente esistente.

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)

Vai

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

Una volta generato, il link può essere inserito nell'email di reimpostazione della password personalizzata e inviato all'utente corrispondente utilizzando un server SMTP personalizzato.

Se non utilizzi la pagina di destinazione predefinita per la reimpostazione della password e stai creando il tuo gestore personalizzato, consulta la sezione sulla creazione di gestori di azioni email personalizzate.

Per generare un link di verifica email, fornisci l'email non verificata dell'utente esistente e un oggetto ActionCodeSettings facoltativo. L'operazione verrà risolta con il link all'azione email. L'indirizzo email utilizzato deve appartenere a un utente esistente.

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)

Vai

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

Una volta generato, il link può essere inserito nell'email di verifica personalizzata e inviato all'utente corrispondente utilizzando un server SMTP personalizzato.

Se non utilizzi la pagina di destinazione predefinita per la verifica email e stai creando il tuo gestore personalizzato, consulta la sezione sulla creazione di gestori di azioni email personalizzati.

Prima di poter autenticare gli utenti con l'accesso con link email, devi attivare l'accesso con link email per il tuo progetto Firebase.

Per generare un link di accesso, fornisci l'indirizzo email dell'utente e un oggetto ActionCodeSettings. In questo caso, l'oggetto ActionCodeSettings è obbligatorio per fornire informazioni su dove reindirizzare l'utente dopo aver fatto clic sul link per completare l'accesso. L'operazione verrà risolta con il link all'azione email.

A differenza della reimpostazione della password e della verifica email, l'indirizzo email utilizzato non deve necessariamente appartenere a un utente esistente, poiché questa operazione può essere utilizzata per registrare nuovi utenti nella tua app tramite link email.

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)

Vai

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

Una volta generato, il link può essere inserito nell'email di accesso personalizzata e inviato all'utente corrispondente utilizzando un server SMTP personalizzato.

Scopri di più su come autenticare gli utenti con Firebase utilizzando i link email. In questo modo, potrai fornire informazioni su come completare l'accesso dopo che l'utente fa clic sul link e viene reindirizzato all'app.