Genera vínculos de acciones de correo electrónico

A veces, las apps para dispositivos móviles deben interactuar con los usuarios y les solicitan realizar ciertas acciones mediante correos electrónicos.

Los SDK de cliente de Firebase permiten enviar a los usuarios correos electrónicos con vínculos para restablecer sus contraseñas, verificar sus direcciones de correo electrónico y acceder a servicios. Google envía estos correos electrónicos basados en plantillas, que cuentan con personalización limitada.

Si quieres usar tus propias plantillas y servicios de entrega de correo electrónico, en esta página se explica cómo usar el SDK de Firebase Admin a fin de generar de manera programática los vínculos de acciones para los flujos mencionados anteriormente y, luego, incluirlos en los correos electrónicos que se envían a los usuarios.

Este proceso permite realizar lo siguiente:

Personalizar plantillas de correo electrónico. Esto incluye la posibilidad de agregar estilos nuevos y un desarrollo personalizado de la marca, cambiar palabras y logotipos, mencionar a los usuarios por su primer nombre en lugar de su nombre completo, entre muchas opciones más.
Aplicar plantillas distintas según el contexto. Por ejemplo, si el usuario verifica su correo electrónico para suscribirse a un boletín informativo, es posible que se deba agregar el contexto en el contenido del correo electrónico. Otro ejemplo es el acceso mediante vínculo. En una situación, el mismo usuario (o algún otro usuario con una invitación) puede activar el acceso. Se debería incluir el contexto en el correo electrónico.
Localizar plantillas de correo electrónico personalizadas.
Generar vínculos en un entorno de servidor seguro.
Personalizar la apertura del vínculo (mediante una app para dispositivos móviles o un navegador) y la entrega de información adicional sobre el estado, entre otros aspectos.
Personalizar el dominio del vínculo dinámico usado en los flujos de apps para dispositivos móviles durante la construcción del vínculo de acción de correo electrónico. Además, se puede especificar un dominio de vínculo dinámico distinto en función del contexto o la app.

Inicializa ActionCodeSettings

Para generar un vínculo de acción de correo electrónico, es posible que debas inicializar una instancia de ActionCodeSettings.

ActionCodeSettings te permite pasar un estado adicional mediante una URL de continuación accesible una vez que el usuario hace clic en el vínculo de correo electrónico. Esto le proporciona al usuario la posibilidad de volver a la app tras finalizar la acción. Además, puedes especificar si deseas manejar el vínculo de acción directamente en una aplicación para dispositivos móviles instalada o en un navegador.

En el caso de los vínculos que se abren en una app para dispositivos móviles, deberás habilitar Firebase Dynamic Links y realizar algunas tareas a fin de detectar los vínculos en tu app para dispositivos móviles. Consulta las instrucciones sobre cómo configurar Firebase Dynamic Links para las acciones de correo electrónico.

Para inicializar una instancia de ActionCodeSettings, proporciona los siguientes datos:

Parámetro	Tipo	Descripción
`url`	string	Establece el vínculo (estado/URL de continuación), que tiene significados diferentes según el contexto: Cuando el vínculo se maneja en los widgets de acción web, este es el vínculo directo en el parámetro de consulta `continueUrl`. Cuando el vínculo se maneja directamente en la app, este es el parámetro de búsqueda `continueUrl` en el vínculo directo de Dynamic Links.
`iOS`	({bundleId: string}\|no definido)	Establece el ID del paquete. Con esto, se intentará abrir el vínculo en una app para Android si está instalada. La app debe estar registrada en Console.
`android`	({packageName: string, installApp: booleano\|no definido, minimumVersion: string\|no definido}\|no definido)	Establece el nombre del paquete de Android. Con esto, se intentará abrir el vínculo en una app para Android si está instalada. Si se pasa `installApp`, especifica si se debe instalar la app para Android en caso de ser compatible con el dispositivo y de no estar instalada. Si se proporciona este campo sin un `packageName`, se genera un error que indica que se debe proporcionar el `packageName` con este campo. Si se especifica `minimumVersion` y hay una versión anterior de la app instalada, se dirigirá al usuario a Play Store para que actualice la app. La app para Android debe estar registrada en Console.
`handleCodeInApp`	(booleano\|no definido)	Indica si el vínculo de acción de correo electrónico debe abrirse primero en una app para dispositivos móviles o en un vínculo web. El valor predeterminado es falso. Cuando se configura como verdadero, el vínculo del código de acción se enviará como vínculo universal o vínculo de app para Android y se abrirá si la app está instalada. Si el valor es falso, el código se enviará primero al widget web y luego se redireccionará a la app si está instalada.
`dynamicLinkDomain`	(string\|no definido)	Establece el dominio (o subdominio) del vínculo dinámico actual en caso de que se deba abrir con Firebase Dynamic Links. Dado que se pueden configurar múltiples dominios de vínculos dinámicos por proyecto, este campo brinda la posibilidad de elegir uno de forma explícita. Si no se proporciona ninguno, se usa el dominio más antiguo según la configuración predeterminada.

En el siguiente ejemplo, se muestra cómo enviar un vínculo de verificación por correo electrónico que se abrirá primero en una app para dispositivos móviles como un vínculo de Firebase Dynamic Links (app para Apple com.example.ios o una app para Android com.example.android, que se instalará si aún no está en el dispositivo y la versión mínima es 12). El vínculo directo incluirá la carga útil https://www.example.com/checkout?cartId=1234 de la URL de continuación. El dominio del vínculo dinámico es coolapp.page.link, que debe configurarse con Firebase Dynamic Links antes de su uso.

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

Go

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

Para obtener más información, consulta Pasa estados en acciones de correo electrónico.

Genera un vínculo de correo electrónico de restablecimiento de contraseña

Para generar un vínculo de restablecimiento de contraseña, proporciona el correo electrónico del usuario y un objeto ActionCodeSettings opcional. La operación generará el vínculo de acción de correo electrónico. La dirección de correo electrónico debe pertenecer a un usuario existente.

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)

Go

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

Después de que se genere el vínculo, puedes insertarlo en tu correo electrónico de restablecimiento de contraseña y, a continuación, enviarlo al usuario correspondiente mediante un servidor SMTP personalizado.

Si no usas la página de destino predeterminada para el restablecimiento de la contraseña ni compilaste un controlador personalizado, consulta Crea controladores de acciones de correo electrónico personalizados.

Genera vínculos de verificación por correo electrónico

Para generar un vínculo de verificación por correo electrónico, proporciona el correo electrónico sin verificar de un usuario existente y un objeto ActionCodeSettings opcional. La operación generará el vínculo de acción de correo electrónico. La dirección de correo electrónico debe pertenecer a un usuario existente.

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)

Go

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

Después de que se genere el vínculo, puedes insertarlo en tu correo electrónico de verificación y, a continuación, enviarlo al usuario correspondiente mediante un servidor SMTP personalizado.

Si no usas la página de destino predeterminada para la verificación por correo electrónico ni compilaste un controlador personalizado, consulta Crea controladores de acciones de correo electrónico personalizados.

Genera vínculos de correo electrónico de acceso

Para autenticar usuarios con el acceso mediante vínculo de correo electrónico, debes habilitarlo en tu proyecto de Firebase.

Para generar un vínculo de acceso, proporciona el correo electrónico del usuario y un objeto ActionCodeSettings. En este caso el objeto ActionCodeSettings es obligatorio, ya que proporciona información sobre la página que se mostrará al usuario después de hacer clic en el vínculo para completar el acceso. La operación generará el vínculo de acción de correo electrónico.

A diferencia del restablecimiento de contraseña y la verificación de correo electrónico, no es necesario que la dirección de correo electrónico pertenezca a un usuario existente, ya que puedes usar esta operación para registrar usuarios nuevos en tu app mediante un vínculo de correo electrónico.

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)

Go

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

Después de que se genere el vínculo, puedes insertarlo en tu correo electrónico de acceso y, a continuación, enviarlo al usuario correspondiente mediante un servidor SMTP personalizado.

Obtén más información sobre cómo autenticar usuarios con Firebase mediante vínculos de correo electrónico. Descubrirás cómo completar el acceso después de que el usuario haga clic en el vínculo y se redireccione de vuelta a la app.