Como transmitir o estado nas ações de e-mail

Você pode passar o estado por meio de um URL de confirmação ao enviar ações de e-mail para redefinição de senha ou verificar o e-mail de um usuário. Isso possibilita ao usuário retornar ao app após a conclusão da ação. Além disso, você pode especificar se é para processar o link de ação do e-mail diretamente de um aplicativo para dispositivos móveis quando ele for instalado, em vez de uma página da Web.

Isso pode ser extremamente útil nas seguintes situações comuns:

  • Um usuário que não está conectado no momento pode estar tentando acessar conteúdo que exija que o usuário faça login. No entanto, o usuário pode ter esquecido a senha e, por conta disso, acionou o fluxo de redefinição de senha. No final do fluxo, o usuário espera voltar para a seção do app que estava tentando acessar.

  • Um aplicativo pode oferecer acesso apenas a contas verificadas. Por exemplo, uma newsletter pode exigir que o usuário verifique o e-mail antes de se inscrever. O usuário passa pelo fluxo de verificação de e-mail e espera retornar ao app para concluir a inscrição.

  • Em outros casos, o usuário pode ter iniciado o fluxo de um dispositivo móvel e espera retornar ao aplicativo para dispositivos móveis, e não ao navegador, após a verificação.

A possibilidade de transmitir o estado usando um URL de confirmação é um recurso eficiente que o Firebase Authentication oferece e que pode melhorar significativamente a experiência do usuário.

Como transmitir estado/URL de confirmação em ações de e-mail

Para transmitir um URL de confirmação com segurança, o domínio do URL precisa estar na lista de permissões do Console do Firebase. Na seção Autenticação, verifique se esse domínio está na lista de Domínios autorizados da guia Método de login. Se não estiver, adicione-o.

Ao enviar um e-mail de redefinição de senha ou de verificação, é necessário fornecer uma instância de ActionCodeSettings. Ela pode ser criada com a classe ActionCodeSettings.Builder associada, que contém os seguintes métodos:

Método Descrição
setUrl(String url)

Define o link (estado/URL de confirmação) que tem diferentes significados em contextos distintos:

  • Quando o link aparece nos widgets de ação da Web, este é o link direto no parâmetro de consulta continueUrl.
  • Quando o link aparece diretamente no app, este é o parâmetro de consulta continueUrl no link direto do Dynamic Links.
setIOSBundleId(String iOSBundleId) Define o ID do pacote iOS. Isso tentará abrir o link em um app iOS, se estiver instalado. O app iOS precisa estar registrado no console.
setAndroidPackageName(String androidPackageName, boolean installIfNotAvailable, String minimumVersion) Define o nome do pacote Android. Isso tentará abrir o link em um app Android se ele estiver instalado. Se o atributo installIfNotAvailable for definido como true, ele especificará a necessidade de instalar o app Android caso isso ainda não tenha sido feito e o dispositivo seja compatível. Se o atributo minimumVersion for especificado e uma versão mais antiga do app estiver instalada, o usuário será levado à Play Store para fazer upgrade do app. O app Android precisa estar registrado no console.
setHandleCodeInApp(boolean status) Se o link de ação de e-mail for aberto primeiro em um app para dispositivos móveis ou em um link da Web. O valor padrão é falso. Quando definido como verdadeiro, o link do código de ação será enviado como um link universal ou um link do app Android e será aberto pelo app, se estiver instalado. Caso seja falso, o código será enviado primeiro ao widget da Web e, em seguida, redirecionará para o app se estiver instalado.
setDynamicLinkDomain(String dynamicLinkDomain) Define o domínio de link dinâmico (ou subdomínio) a ser usado para o link atual, se ele for aberto usando o Firebase Dynamic Links. Como é possível configurar vários domínios de links dinâmicos por projeto, esse campo oferece a capacidade de escolher explicitamente um. Se nenhum for fornecido, o primeiro domínio é usado por padrão.

Confira no exemplo a seguir como enviar um link de verificação de e-mail que será aberto primeiro em um app para dispositivos móveis como um Firebase Dynamic Link (app iOS com.example.ios ou app Android com.example.android). O link direto terá o payload https://www.example.com/?email=user@example.com do URL de confirmação.

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.")
        }
    }

MainActivity.kt

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.");
                }
            }
        });

MainActivity.java

O Firebase Auth usa o Firebase Dynamic Links ao enviar um link que deve ser aberto em um aplicativo para dispositivos móveis. Para usar esse recurso, o Dynamic Links precisa ser configurado no Console do Firebase.

  1. Ative o Firebase Dynamic Links:

    1. No Console do Firebase, abra a seção Dynamic Links.

    2. Caso ainda não tenha aceitado os termos do Dynamic Links e criado um domínio do Dynamic Links, faça isso agora.

      Anote o domínio do Dynamic Links se você já tiver criado um. Um domínio do Dynamic Links geralmente se parece com este exemplo:

      example.page.link

      Você vai precisar desse valor ao configurar o aplicativo Android ou Apple para interceptar o link recebido.

  2. Como configurar apps Android:

    1. Se você planeja processar esses links a partir do aplicativo para Android, o nome do pacote para Android precisa ser especificado nas configurações do projeto do Firebase console. Além disso, o SHA-1 e o SHA-256 do certificado do aplicativo precisam ser fornecidos.
    2. Você também precisará configurar o filtro de intent para o link direto no seu arquivo AndroidManifest.xml.
    3. Para mais informações, consulte as instruções para receber Dynamic Links no Android.

  3. Como configurar apps iOS:

    1. Se você planeja processar esses links com o app iOS, o ID do pacote do iOS precisa ser especificado nas configurações do projeto do Console do Firebase. Além disso, os IDs da App Store e da equipe de desenvolvedores da Apple também precisam ser especificados.
    2. Você também precisará configurar o domínio do link universal FDL como um domínio associado nos recursos do seu aplicativo.
    3. Se você pretende distribuir seu aplicativo para a versão 8 e anteriores do iOS, será necessário configurar o ID do pacote iOS como um esquema personalizado para URLs recebidos.
    4. Para mais informações, consulte as instruções para receber o Dynamic Links no iOS.

Processamento de ações de e-mail em um app da Web

Especifique se você quer processar o link do código de ação de um aplicativo da Web primeiro e, em seguida, redirecionar para outra página da Web ou app para dispositivos móveis após a conclusão, desde que esse app para dispositivos móveis esteja disponível. Para isso, chame setHandleCodeInApp(false) no objeto ActionCodeSettings.Builder. Não é necessário fornecer um ID do pacote iOS ou um nome do pacote Android, mas se você fizer isso, o usuário será redirecionado para o app especificado na conclusão do código de ação de e-mail.

O URL da Web usado aqui é o mesmo configurado na seção de modelos de ações de e-mail. Um padrão é provisionado para todos os projetos. Consulte Como personalizar gerenciadores de e-mail para saber mais sobre como personalizar o gerenciador de ações de e-mail.

Neste caso, o link dentro do parâmetro de consulta continueUrl será um link FDL com payload URL especificado no objeto ActionCodeSettings. Embora você possa interceptar e manipular o link recebido do seu app sem nenhuma dependência adicional, recomendamos o uso da biblioteca de cliente FDL para analisar o link direto para você.

Ao processar ações de e-mail como a verificação, o código de ação do parâmetro de consulta oobCode precisa ser analisado no link direto e aplicado via applyActionCode para que a alteração seja concluída, ou seja, para que o e-mail seja verificado.

Processamento de ações de e-mail em um app para dispositivos móveis

Especifique se você quer processar o link do código de ação no seu app para dispositivos móveis primeiro, desde que ele esteja instalado. Com aplicativos Android, você também pode especificar por meio do booleano installIfNotAvailable que o app deverá ser instalado se o dispositivo for compatível e ainda não estiver instalado. Se o link for clicado em um dispositivo não compatível com o aplicativo para dispositivos móveis, ele será aberto de uma página da Web. Para isso, chame setHandleCodeInApp(true) no objeto ActionCodeSettings.Builder. Também é necessário especificar o nome do pacote Android ou o ID do pacote iOS do app para dispositivos móveis.

O URL de fallback da Web usado aqui, quando nenhum aplicativo para dispositivos móveis está disponível, é o mesmo configurado na seção de modelos de ação de e-mail. Um padrão é provisionado para todos os projetos. Consulte Como personalizar gerenciadores de e-mail para saber mais sobre como personalizar o gerenciador de ações de e-mail.

Neste caso, o link do app para dispositivos móveis enviado ao usuário será um link FDL em que o payload é o URL do código de ação, configurado no console, com os parâmetros de consulta oobCodemode, apiKey e continueUrl. O último será o URL original especificado no objeto ActionCodeSettings. Embora seja possível interceptar e manipular o link recebido do seu app sem qualquer dependência adicional, recomendamos o uso da biblioteca de cliente FDL para analisar o link direto para você. É possível aplicar o código de ação diretamente a partir de um app para dispositivos móveis da mesma forma que ele é processado no fluxo da Web descrito na seção Como personalizar gerenciadores de e-mail.

Ao processar ações de e-mail como a verificação, o código de ação do parâmetro de consulta oobCode precisa ser analisado no link direto e aplicado via applyActionCode para que a alteração seja concluída, ou seja, para que o e-mail seja verificado.