Migrar para o FedCM

Este guia ajuda a entender as mudanças no seu aplicativo da Web introduzidas pela API Federated Credential Management (FedCM, na sigla em inglês).

Quando o FedCM está ativado, o navegador exibe solicitações do usuário e nenhum cookie de terceiros é usado.

Visão geral

O FedCM permite fluxos de login mais privados sem exigir o uso de cookies de terceiros. O navegador controla as configurações do usuário, exibe solicitações do usuário e só entra em contato com um provedor de identidade, como o Google, após o consentimento explícito do usuário.

Para a maioria dos sites, a migração ocorre sem problemas com atualizações compatíveis com versões anteriores para a biblioteca JavaScript dos Serviços de Identificação do Google.

Atualizações no recurso de login automático

O Federated Credential Management (FedCM) Beta para os Serviços de Identificação do Google foi lançado em agosto de 2023. Muitos desenvolvedores testaram a API e enviaram feedback valioso.

Uma resposta que o Google recebeu dos desenvolvedores é sobre o requisito de gesto do usuário do fluxo de login automático do FedCM. Para melhorar a privacidade, o Chrome exige que os usuários confirmem novamente que querem fazer login no site com a Conta do Google em cada instância do Chrome, mesmo que tenham aprovado o site antes do lançamento da FedCM. Essa confirmação única é feita com um único clique no comando "Um toque" para demonstrar a intenção do usuário de fazer login. Essa mudança pode causar uma interrupção inicial nas taxas de conversão de login automático em alguns sites.

Recentemente, na M121, o Chrome fez uma mudança na UX do fluxo de login automático do FedCM. A nova confirmação é necessária apenas quando os cookies de terceiros são restritos. Isso significa que:

  1. O login automático do FedCM não exige nova confirmação para usuários recorrentes. Se os usuários confirmarem novamente com a interface do FedCM, essa reconfirmação contará para o requisito de gesto do usuário na era pós-3PCD.

  2. O login automático do FedCM vai verificar o status de nova confirmação quando os cookies de terceiros forem restritos manualmente pelos usuários hoje ou por padrão no Chrome no futuro.

Com essa mudança, recomendamos que todos os desenvolvedores de login automático migrem para o FedCM assim que possível para reduzir a interrupção das taxas de conversão de login automático.

Para o fluxo de login automático, o JavaScript do GIS não vai acionar o FedCM em um Chrome mais antigo (antes do M121), mesmo que seu site escolha ativar o FedCM.

Diferenças na jornada do usuário

As experiências do One Tap usando FedCM e sem FedCM são semelhantes, mas com pequenas diferenças.

Novo usuário de sessão única

Com o FedCM, o recurso Um toque mostra o nome de domínio em vez do nome do aplicativo.

Como usar o FedCM Sem FedCM
Novo usuário de sessão única usando o FedCM Novo usuário de sessão única sem o FedCM

Usuário recorrente de sessão única (com login automático desativado)

Ao usar o FedCM, o recurso Um toque mostra o nome de domínio em vez do nome do aplicativo.

Como usar o FedCM Sem FedCM
Jornada do usuário recorrente de sessão única usando o FedCM (com o login automático desativado) Jornada do usuário recorrente de sessão única sem FedCM (com login automático desativado)

Usuário recorrente de sessão única (com o login automático ativado)

Com o FedCM, os usuários podem clicar no X para cancelar o login automático em até cinco segundos em vez de clicar no botão Cancelar.

Como usar o FedCM Sem FedCM
Jornada do usuário recorrente de uma sessão usando o FedCM (com o login automático ativado) Jornada do usuário recorrente de uma única sessão sem FedCM (com login automático ativado)

Várias sessões

Usando o FedCM, um toque mostra o nome do domínio em vez do nome do aplicativo.

Como usar o FedCM Sem FedCM
Usuário com várias sessões usando o FedCM Usuário com várias sessões sem FedCM

Antes de começar

Verifique se as configurações e a versão do navegador têm suporte à API FedCM. É recomendável atualizar para a versão mais recente.

  • A API FedCM está disponível no Chrome 117 ou mais recente.

  • A configuração Fazer login de terceiros está ativada no Chrome.

  • Se a versão do navegador Chrome for 119 ou anterior, abra chrome://flags e ative o recurso experimental FedCmWithoutThirdPartyCookies. Essa etapa não é necessária com o navegador Chrome versão 120 ou mais recente.

Migrar seu app da Web

Siga estas etapas para ativar o FedCM, avaliar o possível impacto da migração e, se necessário, fazer alterações no seu aplicativo da Web atual:

1. Adicione uma flag booleana para ativar o FedCM ao inicializar usando:

2. Remova o uso dos métodos isDisplayMoment(), isDisplayed(), isNotDisplayed() e getNotDisplayedReason() no código.

Para melhorar a privacidade do usuário, o callback google.accounts.id.prompt não retorna mais nenhuma notificação de momento de exibição no objeto PromptMomentNotication. Remova qualquer código que dependa dos métodos relacionados ao momento de exibição. São eles os métodos isDisplayMoment(), isDisplayed(), isNotDisplayed() e getNotDisplayedReason().

3. Remova o uso do método getSkippedReason() no código.

Embora o momento de pular, isSkippedMoment(), ainda seja chamado pelo callback google.accounts.id.prompt no objeto PromptMomentNotication, o motivo detalhado não é fornecido. Remova qualquer código que dependa do método getSkippedReason() do seu código.

A notificação de momento dispensado, isDismissedMoment(), e o método de motivo detalhado relacionado, getDismissedReason(), não são alterados quando o FedCM está ativado.

4. Remova os atributos de estilo position de data-prompt_parent_id e intermediate_iframes.

O navegador controla o tamanho e a posição das solicitações do usuário. As posições personalizadas para um toque no computador não são compatíveis.

5. Atualize o layout da página se necessário.

O navegador controla o tamanho e a posição das solicitações do usuário. Dependendo do layout de páginas individuais, parte do conteúdo pode ser sobreposta como posições personalizadas para o recurso Um toque no computador não têm suporte de nenhuma forma, como atributo style, data-prompt_parent_id, intermediate_iframes, iframe personalizado e outras formas criativas.

Mude o layout da página para melhorar a experiência do usuário quando informações importantes estiverem obscurecidas. Não crie sua UX com base na solicitação de um toque, mesmo que você presuma que ela esteja na posição padrão. Como a API FedCM é mediada pelo navegador, diferentes fornecedores de navegadores podem posicionar o comando de maneira ligeiramente diferente.

6. Adicione o atributo allow="identity-credentials-get" ao frame pai se o app da Web chamar a API One Tap de iframes de origem cruzada.

Um iframe é considerado de origem cruzada quando origin não é exatamente igual à origem mãe. Por exemplo:

  • Domínios diferentes: https://example1.com e https://example2.com
  • Domínios de nível superior diferentes: https://example.uk e https://example.jp

  • Subdomínios: https://example.com e https://login.example.com

    Para melhorar a privacidade do usuário, quando a API One Tap for chamada de iframes de origem cruzada, adicione o atributo allow="identity-credentials-get" em cada tag iframe de frame pai:

    <iframe src="https://your.cross-origin/onetap.page" allow="identity-credentials-get"></iframe>

    Se o app usar um iframe que contém outro iframe, é necessário garantir que o atributo seja adicionado a todos os iframes, incluindo todos os subframes.

    Por exemplo, considere este cenário:

  • O documento principal (https://www.example.uk) contém um iframe chamado "Iframe A", que incorpora uma página (https://logins.example.com).

  • Essa página incorporada (https://logins.example.com) também contém um iframe chamado "Iframe B", que incorpora ainda mais uma página (https://onetap.example2.com) que hospeda um toque.

    Para garantir que um toque seja exibido corretamente, o atributo precisa ser adicionado às tags iframe A e B.

    Prepare-se para perguntas sobre o comando "Um toque" que não aparece. Outros sites com origens diferentes podem incorporar suas páginas que hospedam o recurso Um toque nos iframes deles. Você pode receber um aumento na quantidade de tíquetes de suporte relacionada à não exibição do recurso Um toque de usuários finais ou outros proprietários de sites. Embora as atualizações só possam ser feitas pelos proprietários do site nas páginas deles, você pode fazer o seguinte para reduzir o impacto:

  • Atualize a documentação para desenvolvedores e inclua como configurar o iframe corretamente para chamar seu site. Você pode vincular esta página na sua documentação.

  • Atualize a página de perguntas frequentes do desenvolvedor, se aplicável.

  • Informe sua equipe de suporte sobre essa mudança e prepare a resposta à consulta com antecedência.

  • Entre em contato de maneira proativa com parceiros, clientes ou proprietários de sites afetados para facilitar a transição do FedCM.

7. Adicione estas diretivas à sua Política de Segurança de Conteúdo (CSP).

Essa etapa é opcional, já que nem todos os sites definem uma CSP.

  • Se a CSP não for usada no seu site, não será necessário fazer mudanças.

  • Se o CSP funcionar para o One Tap atual e você não usar connect-src, frame-src, script-src, style-src ou default-src, nenhuma mudança será necessária.

  • Caso contrário, siga este guia para configurar o CSP. Sem a configuração adequada da CSP, o FedCM One Tap não seria exibido no site.

8. Remova o suporte para login nas Accelerated Mobile Pages (AMP).

O suporte ao login do usuário para AMP é um recurso opcional do GIS que seu app da Web pode ter implementado. Se esse for o caso,

Exclua todas as referências a:

  • Elemento personalizado amp-onetap-google

  • <script async custom-element="amp-onetap-google" src="https://cdn.ampproject.org/v0/amp-onetap-google-0.1.js"></script>

    Considere redirecionar as solicitações de login do AMP para o fluxo de login do HTML do seu site. O Intermediate Iframe Support API relacionado não é afetado.

Testar e verificar a migração

Depois de fazer as mudanças necessárias com base nas etapas anteriores, verifique se a migração foi bem-sucedida.

  1. Confirme se o navegador oferece suporte ao FedCM e se você tem uma sessão da Conta do Google.

  2. Acesse as páginas do One Tap no seu app.

  3. Confirme se a solicitação de um toque é exibida e se ela sobrepõe o conteúdo subjacente com segurança.

  4. Confirme se uma credencial correta é retornada ao endpoint ou método de callback ao fazer login no seu aplicativo usando o recurso One Tap.

  5. Se o login automático estiver ativado, verifique se o cancelamento funciona e se a credencial correta retorna ao endpoint ou método de callback.

Período de espera do recurso Um toque

Clicar em "Um toque" no canto superior direito fecha a solicitação e entra no período de espera, que impede a exibição temporária da solicitação. No Chrome, se você quiser que o comando de um toque seja mostrado novamente antes do término do período de espera, redefina o status de espera clicando no ícone de bloqueio na barra de endereço e no botão Redefinir permissão.

Período de silêncio do login automático

Ao testar o login automático com um toque usando o FedCM, ele tem um período de silêncio de 10 minutos entre cada tentativa de login automático. O período de silêncio não pode ser redefinido. Você precisaria aguardar 10 minutos ou usar uma Conta do Google diferente para o teste a fim de acionar o login automático novamente.

Recursos úteis

A Ferramenta de análise de dados do Sandbox de privacidade (PSAT, na sigla em inglês) é uma extensão do Chrome DevTools para ajudar na adoção de APIs alternativas, como o FedCM. Ele verifica o site em busca de recursos afetados e fornece uma lista de alterações recomendadas.