Pasa estados en acciones de correo electrónico

Puedes pasar el estado a través de una URL de continuación cuando envías acciones de correo electrónico para restablecer contraseñas o verificar el correo electrónico de un usuario. Esto le proporciona al usuario la posibilidad de volver a la app una vez finalizada la acción. Además, puedes especificar si deseas manejar el vínculo de acción de correo electrónico directamente en una aplicación para dispositivos móviles, en lugar de una página web, si es que la aplicación está instalada.

Esto puede ser extremadamente útil en las siguientes situaciones comunes:

  • Un usuario que no accedió a su cuenta puede estar intentando obtener contenido para el que debe acceder. Sin embargo, el usuario puede haber olvidado su contraseña y podría activar el flujo de restablecimiento de contraseña. Al final del flujo, el usuario espera volver a la sección de la app a la que estaba intentando acceder.

  • Una aplicación podría ofrecer acceso solo a cuentas verificadas. Por ejemplo, es posible que el usuario deba verificar su correo electrónico antes de suscribirse a un boletín informativo. El usuario pasaría por el flujo de verificación de correo electrónico y esperaría volver a la app para completar la suscripción.

  • En otros casos, es posible que el usuario haya iniciado el flujo desde su dispositivo móvil y espere volver a la app y no al navegador.

Tener la capacidad de pasar el estado a través de una URL de continuación es una característica importante que Firebase Auth proporciona y que puede mejorar significativamente la experiencia del usuario.

Pasa el estado y la URL de continuación en acciones de correo electrónico

Para pasar una URL de continuación de forma segura, el dominio de la URL debe estar incluido en la lista de elementos permitidos de Firebase console. Para ello, se debe agregar el dominio a la lista de Dominios autorizados de la pestaña Método de acceso en la sección Authentication, si aún no se ha hecho.

Se debe proporcionar una instancia de ActionCodeSettings cuando se envíe un correo electrónico de restablecimiento de contraseña o uno de verificación. Puede crearse con la clase ActionCodeSettings.Builder asociada, que incluye los siguientes métodos:

Método Descripción
setUrl(String url)

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 consulta continueUrl en el vínculo directo de Dynamic Links.
setIOSBundleId(String iOSBundleId) Establece el ID del paquete de iOS. Con esto, se intentará abrir el vínculo en una app para iOS, si está instalada. La app para iOS debe estar registrada la consola.
setAndroidPackageName(String androidPackageName, boolean installIfNotAvailable, String minimumVersion) Establece el nombre del paquete de Android. Con esto, se intentará abrir el vínculo en una app para Android, si está instalada. Si installIfNotAvailable se configura como true, especifica si se debe instalar la app para Android en caso de que sea compatible con el dispositivo y la app aún no esté instalada. 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 la consola.
setHandleCodeInApp(boolean status) Indica si el vínculo de acción de correo electrónico debe abrirse primero en una app para dispositivos móviles o 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.
setDynamicLinkDomain(String dynamicLinkDomain) 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 primer dominio 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 iOS: com.example.ios; app para Android: com.example.android). El vínculo directo incluirá la carga útil https://www.example.com/?email=user@example.com de la URL de continuación.

Kotlin+KTX

val auth = Firebase.auth
val user = auth.currentUser!!

val url = "http://www.example.com/verify?uid=" + user.uid
val actionCodeSettings = ActionCodeSettings.newBuilder()
    .setUrl(url)
    .setIOSBundleId("com.example.ios")
    // The default for this is populated with the current android package name.
    .setAndroidPackageName("com.example.android", false, null)
    .build()

user.sendEmailVerification(actionCodeSettings)
    .addOnCompleteListener { task ->
        if (task.isSuccessful) {
            Log.d(TAG, "Email sent.")
        }
    }

Java

FirebaseAuth auth = FirebaseAuth.getInstance();
FirebaseUser user = auth.getCurrentUser();

String url = "http://www.example.com/verify?uid=" + user.getUid();
ActionCodeSettings actionCodeSettings = ActionCodeSettings.newBuilder()
        .setUrl(url)
        .setIOSBundleId("com.example.ios")
        // The default for this is populated with the current android package name.
        .setAndroidPackageName("com.example.android", false, null)
        .build();

user.sendEmailVerification(actionCodeSettings)
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                if (task.isSuccessful()) {
                    Log.d(TAG, "Email sent.");
                }
            }
        });

Firebase Auth utiliza Firebase Dynamic Links cuando envía un vínculo que debe abrirse en una aplicación para dispositivos móviles. Para poder usar esta función, se debe configurar Dynamic Links en Firebase console.

  1. Habilita Firebase Dynamic Links:

    1. En Firebase console, abre la sección Dynamic Links.
    2. Si aún no aceptaste los términos ni creaste un dominio de Dynamic Links, deberás hacerlo ahora.

      Si ya creaste un dominio de Dynamic Links, anótalo. Estos dominios suelen ser como el siguiente ejemplo:

      example.page.link

      Necesitarás este valor cuando configures la app para Apple o Android a fin de interceptar el vínculo entrante.

  2. Configuración de aplicaciones para Android:

    1. Si planeas manejar estos vínculos desde la aplicación para Android, es necesario especificar el nombre del paquete de Android en la configuración del proyecto de Firebase console. Además, es necesario proporcionar el SHA-1 y el SHA-256 del certificado de aplicación.
    2. También deberás configurar el filtro de intents para el vínculo directo en el archivo AndroidManifest.xml.
    3. Para obtener más información al respecto, consulta las instrucciones para recibir Dynamic Links en Android.
  3. Configuración de aplicaciones para iOS:

    1. Si planeas manejar estos vínculos desde tu aplicación para iOS, es necesario especificar el ID del paquete de iOS en la configuración del proyecto de Firebase console. Además, es necesario especificar el ID de App Store y el ID del equipo de desarrolladores de Apple.
    2. También tendrás que configurar el dominio del vínculo universal FDL como un dominio asociado en las capacidades de tu aplicación.
    3. Si planeas distribuir la aplicación para la versión 8 de iOS o versiones previas, deberás configurar el ID del paquete de iOS como un esquema personalizado para las URLs entrantes.
    4. Para obtener más información al respecto, consulta las instrucciones para recibir Dynamic Links en iOS.

Manejo de acciones de correo electrónico en una aplicación web

Puedes especificar si deseas manejar el vínculo de código de acción desde una aplicación web primero y después redireccionar a otra página web o a una aplicación para dispositivos móviles cuando finalice el proceso, siempre y cuando la aplicación para dispositivos móviles esté disponible. Para ello, se debe llamar a setHandleCodeInApp(false) en el objeto ActionCodeSettings.Builder. Aunque no es obligatorio ingresar un ID de paquete de iOS o un nombre de paquete de Android, proporcionarlos permitirá que el usuario se redireccione de vuelta a la app especificada cuando termine de procesarse el código de acción de correo electrónico.

La URL web que se usa aquí es la que se configuró en la sección de plantillas de acción de correo electrónico. Se aprovisiona una opción predeterminada para todos los proyectos. Consulta cómo crear controladores de acciones de correo electrónico personalizados para obtener más información sobre el tema.

En este caso, el vínculo que se encuentra dentro del parámetro de consulta continueUrl será un vínculo FDL cuya carga útil es la URL que se especifica en el objeto ActionCodeSettings. Si bien puedes interceptar el vínculo entrante y manejarlo desde tu app sin ninguna dependencia adicional, te recomendamos utilizar la biblioteca cliente FDL para analizar el vínculo directo.

Cuando manejes acciones de correo electrónico, como la verificación, el código de acción del parámetro de consulta oobCode debe analizarse desde el vínculo directo y, luego, aplicarse mediante applyActionCode a fin de que el cambio surta efecto (es decir, para que se verifique la dirección de correo electrónico).

Maneja acciones de correo electrónico en una aplicación para dispositivos móviles

Puedes especificar si deseas manejar el vínculo de código de acción primero desde tu aplicación para dispositivos móviles, siempre y cuando esté instalada. En el caso de las aplicaciones para Android, también puedes usar el booleano installIfNotAvailable para especificar que la aplicación debe instalarse si es compatible con el dispositivo y aún no está instalada. Si se hace clic en el vínculo desde un dispositivo móvil que no es compatible con la aplicación, se abrirá en una página web. Para ello, se debe llamar a setHandleCodeInApp(true) en el objeto ActionCodeSettings.Builder. También deberás especificar el nombre del paquete de Android o el ID del paquete de iOS de la aplicación para dispositivos móviles.

La URL web de resguardo que se usa aquí, cuando no hay una app para dispositivos móviles disponible, es la configurada en la sección de plantillas de acciones de correo electrónico. Se aprovisiona una opción predeterminada para todos los proyectos. Consulta cómo crear controladores de acciones de correo electrónico personalizados para obtener más información sobre el tema.

En este caso, el vínculo de la app para dispositivos móviles enviado al usuario será un vínculo FDL cuya carga útil es la URL del código de acción configurada en la consola, con los parámetros de consulta oobCode, mode, apiKey y continueUrl. Esta última será la URL original especificada en el objeto ActionCodeSettings. Si bien puedes interceptar el vínculo entrante y manejarlo desde tu app sin ninguna dependencia adicional, te recomendamos utilizar la biblioteca cliente FDL para analizar el vínculo directo. El código de acción se puede aplicar directamente desde una aplicación para dispositivos móviles de manera similar a como se maneja desde el flujo web descrito en la sección sobre cómo crear controladores de acciones de correo electrónico personalizados.

Cuando manejes acciones de correo electrónico, como la verificación, el código de acción del parámetro de consulta oobCode debe analizarse desde el vínculo directo y, luego, aplicarse mediante applyActionCode a fin de que el cambio surta efecto (es decir, para que se verifique la dirección de correo electrónico).