Generazione di link ad azioni e-mail

A volte le app mobile devono interagire con gli utenti e invitarli a intraprendere determinate azioni inviando email.

Gli SDK client di Firebase consentono di inviare agli utenti email contenenti link che possono utilizzare per reimpostare la 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, questa pagina spiega 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.

Ciò comporta i seguenti vantaggi:

  • Personalizza i modelli email. Ciò include la possibilità di aggiungere nuovi stili e branding personalizzato, modificare la formulazione e i loghi, rivolgersi agli utenti per nome anziché per nome completo e così via.
  • Applica modelli diversi a seconda del contesto. Ad esempio, se l'utente sta verificando la sua email per iscriversi a una newsletter, il contesto potrebbe dover essere fornito nel contenuto dell'email. Un altro esempio è l'accesso tramite link email: in uno scenario questo può essere attivato dallo stesso utente o come invito da un altro utente. Il contesto deve essere incluso nell'email.
  • Localizza i modelli di 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 informazioni aggiuntive sullo stato e così via.
  • Possibilità di personalizzare il dominio del link mobile utilizzato per i flussi delle app mobile durante la costruzione del link di azione email.

Initialize ActionCodeSettings

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

ActionCodeSettings ti consentono di trasmettere uno stato aggiuntivo tramite un URL di continuazione accessibile dopo che l'utente fa clic sul link nell'email. Inoltre, l'utente può tornare all'app dopo il completamento dell'azione. Inoltre, puoi specificare se gestire il link di azione email direttamente da un'app mobile quando è installata o da un browser.

Per i link che devono essere aperti tramite un'app mobile, dovrai eseguire alcune attività per rilevarli dall'app mobile. Consulta le istruzioni su come configurare i link mobile per le azioni email.

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

Parametro Tipo Descrizione
url stringa

Imposta il link (URL di stato/continua) 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 link Hosting.
iOS ({bundleId: string}|undefined) Imposta l'ID bundle iOS per aiutare Firebase Authentication a determinare se deve creare un link solo web o mobile che viene aperto su un dispositivo Apple
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) Imposta il nome del pacchetto Android per aiutare Firebase Authentication a determinare se deve creare un link solo web o mobile che viene aperto su un dispositivo Android
handleCodeInApp (booleano|undefined) Se il link dell'azione email verrà aperto prima in un'app mobile o in un link web. Il valore predefinito è false. Se impostato su true, il link al codice azione verrà inviato come link universale o link app 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.
linkDomain (string|undefined) Quando vengono definiti domini di link di hosting personalizzati per un progetto, specifica quale utilizzare quando il link deve essere aperto da un'app mobile specifica. In caso contrario, viene selezionato automaticamente il dominio predefinito (ad esempio, PROJECT_ID.firebaseapp.com).
dynamicLinkDomain (string|undefined) Deprecato. Non specificare questo parametro.

Il seguente esempio mostra come inviare un link di verifica email che si aprirà prima in un'app mobile. Il link diretto conterrà il payload https://www.example.com/checkout?cartId=1234 dell'URL continua. Il dominio del link Hosting personalizzato utilizzato è custom-domain.com, che deve essere configurato per l'utilizzo con Firebase Hosting.

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

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 saperne di più, consulta Trasferimento dello stato nelle azioni email.

Genera il link dell'email di reimpostazione della password

Per generare un link di reimpostazione della password, fornisci l'email dell'utente esistente e un oggetto ActionCodeSettings facoltativo. L'operazione verrà risolta con il link dell'azione email. L'email utilizzata 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 personalizzata di reimpostazione della password e inviato all'utente corrispondente utilizzando un server SMTP personalizzato.

Se non utilizzi la pagina di destinazione predefinita per la reimpostazione della password e crei il tuo gestore personalizzato, consulta la sezione Creazione di gestori di azioni email personalizzati.

Generare il link di verifica dell'email

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'email utilizzata 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 dell'email e crei il tuo gestore personalizzato, consulta la sezione Creazione di gestori di azioni email personalizzati.

Generare un link email per l'accesso

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

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

A differenza del ripristino della password e della verifica dell'email, l'email utilizzata non deve necessariamente appartenere a un utente esistente, in quanto questa operazione può essere utilizzata per registrare nuovi utenti nella tua app tramite link via 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 poi inviato via email all'utente corrispondente utilizzando un server SMTP personalizzato.

Scopri di più sull'autenticazione degli 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.