Esegui la migrazione a FedCM

Questa guida ti aiuta a comprendere le modifiche all'applicazione web introdotte dall'API Federated Credential Management (FedCM).

Quando FedCM è attivato, il browser mostra richieste all'utente e non vengono utilizzati cookie di terze parti.

Panoramica

FedCM consente flussi di accesso più privati senza richiedere l'uso di cookie di terze parti. Il browser controlla le impostazioni dell'utente, mostra le richieste all'utente e contatta un fornitore di servizi di identità come Google solo dopo che l'utente ha dato il suo consenso esplicito.

Per la maggior parte dei siti web, la migrazione avviene senza problemi tramite aggiornamenti compatibili con le versioni precedenti della libreria JavaScript dei Servizi di identità Google.

Suggerimento :durante gli esperimenti di Google e le prove dell'origine di Chrome, una certa percentuale del numero totale di utenti che accedono al tuo sito web utilizzerà l'API FedCM. La percentuale specifica varia e può cambiare senza preavviso. Prima che FedCM divento obbligatorio per tutti gli accessi, utilizza data-use_fedcm_for_prompt o use_fedcm_for_prompt per scegliere il flusso di accesso. In questo modo, potresti migliorare la tua capacità di eseguire il debug, raccogliere le metriche o passare tutti gli accessi a FedCM dopo aver completato la migrazione.

Aggiornamenti sulla funzionalità Accesso automatico

La versione beta di Federated Credential Management (FedCM) per i servizi di identità Google è stata lanciata ad agosto 2023. Molti sviluppatori hanno testato l'API e fornito un feedback prezioso.

Una risposta che Google ha sentito dagli sviluppatori riguarda il requisito dei gesti dell'utente per il flusso di accesso automatico di FedCM. Per migliorare la privacy, Chrome richiede agli utenti di riconfermare di voler accedere al sito web con l'Account Google in ogni istanza di Chrome, anche se l'utente ha approvato il sito web prima dell'implementazione di FedCM. Questa riconferma una tantum viene eseguita facendo clic sul prompt One Tap per dimostrare l'intenzione dell'utente di accedere. Questa modifica potrebbe causare un'interruzione iniziale dei tassi di conversione per l'accesso automatico per alcuni siti web.

Di recente, in M121, Chrome ha apportato una modifica all'esperienza utente del flusso di accesso automatico di FedCM. La riconferma è obbligatoria solo quando i cookie di terze parti sono soggetti a limitazioni. Ciò significa che:

1. L'accesso automatico FedCM non richiede una nuova conferma per gli utenti di ritorno. Se gli utenti confermano di nuovo con l'interfaccia utente di FedCM, questa conferma verrà conteggiata ai fini del requisito relativo al gesto dell'utente per l'era successiva al 3PCD.

2. L'accesso automatico a FedCM controllerà lo stato della riconferma quando i cookie di terze parti sono limitati manualmente dagli utenti oggi o per impostazione predefinita in Chrome in futuro.

Con questa modifica, consigliamo a tutti gli sviluppatori dell'accesso automatico di eseguire la migrazione a FedCM il prima possibile, per ridurre l'interruzione dei tassi di conversione dell'accesso automatico.

Per il flusso di accesso automatico, GIS JavaScript non attiverà FedCM su una versione precedente di Chrome (prima di M121), anche se il tuo sito web sceglie di attivare FedCM.

Differenze del percorso dell'utente

Le esperienze One Tap che utilizzano FedCM e quelle che non lo utilizzano sono simili, con alcune piccole differenze.

Nuovo utente per sessione singola

Se utilizzi FedCM, One Tap mostra il nome di dominio anziché il nome dell'applicazione.

Utilizzo di FedCM	Senza FedCM

Utente di ritorno con una singola sessione (con accesso automatico disattivato)

Se utilizzi FedCM, One Tap mostra il nome di dominio anziché il nome dell'applicazione.

Utilizzo di FedCM	Senza FedCM

Utente di ritorno per una singola sessione (con accesso automatico attivato)

Con FedCM, gli utenti possono fare clic su X per annullare l'accesso automatico entro 5 secondi anziché fare clic sul pulsante Annulla.

Utilizzo di FedCM	Senza FedCM

Multisessione

Se utilizzi FedCM, One Tap mostra il nome di dominio anziché il nome dell'applicazione.

Utilizzo di FedCM	Senza FedCM

Prima di iniziare

Verifica che le impostazioni e la versione del browser supportino l'API FedCM. È consigliabile eseguire l'aggiornamento alla versione più recente.

• L'API FedCM è disponibile in Chrome 117 o versioni successive.

• L'impostazione Accesso di terze parti è attivata in Chrome.

• Se la versione del browser Chrome è 119 o precedente, apri chrome://flags e attiva la funzionalità sperimentale FedCmWithoutThirdPartyCookies. Questo passaggio non è necessario con il browser Chrome versione 120 o successive.

Esegui la migrazione dell'app web

Per attivare FedCM, valutare il potenziale impatto della migrazione e, se necessario, apportare modifiche all'applicazione web esistente:

1. Aggiungi un flag booleano per abilitare FedCM durante l'inizializzazione utilizzando:

• HTML, imposta l'attributo data-use_fedcm_for_prompt su true.

• JavaScript, imposta use_fedcm_for_prompt su true nell'oggetto IdConfiguration.

2. Rimuovi l'utilizzo dei metodi isDisplayMoment(), isDisplayed(), isNotDisplayed() e getNotDisplayedReason() nel codice.

Per migliorare la privacy degli utenti, il callback google.accounts.id.prompt non restituisce più alcuna notifica relativa al momento di visualizzazione nell'oggetto PromptMomentNotication. Rimuovi qualsiasi codice che dipende dai metodi correlati al momento di visualizzazione. Si tratta dei metodi isDisplayMoment(), isDisplayed(), isNotDisplayed() e getNotDisplayedReason().

3. Rimuovi l'utilizzo del metodo getSkippedReason() nel codice.

Anche se il momento di salto, isSkippedMoment(), viene comunque chiamato dal callback google.accounts.id.prompt nell'oggetto PromptMomentNotication, non viene fornito il motivo dettagliato. Rimuovi dal codice qualsiasi codice che dipende dal metodo getSkippedReason().

Tieni presente che la notifica relativa al momento ignorato, isDismissedMoment(), e il metodo del motivo dettagliato correlato, getDismissedReason(), rimangono invariati quando è attiva la funzionalità FedCM.

4. Rimuovi gli attributi di stile position da data-prompt_parent_id e intermediate_iframes.

Il browser controlla le dimensioni e la posizione delle richieste dell'utente. Le posizioni personalizzate per One Tap su computer non sono supportate.

5. Aggiorna il layout della pagina, se necessario.

Il browser controlla le dimensioni e la posizione delle richieste all'utente. A seconda del layout delle singole pagine, alcuni contenuti potrebbero essere sovrapposti perché le posizioni personalizzate per One Tap su computer non sono supportate in alcun modo, ad esempio l'attributo style, data-prompt_parent_id, intermediate_iframes, iframe personalizzati e altri modi creativi.

Modifica il layout della pagina per migliorare l'esperienza utente quando le informazioni importanti sono coperte. Non basare l'esperienza utente sulla richiesta One Tap anche se supponi che sia nella posizione predefinita. Poiché l'API FedCM è mediata dal browser, i diversi fornitori di browser potrebbero posizionare la richiesta in modo leggermente diverso.

6. Aggiungi l'attributo allow="identity-credentials-get" al frame principale se la tua app web chiama l'API One Tap da iframe cross-origin.

Un iframe è considerato interorigine se la sua origine non è esattamente uguale all'origine principale. Ad esempio:

• Domini diversi: https://example1.com e https://example2.com
• Domini di primo livello diversi: https://example.uk e https://example.jp

• Sottodomini: https://example.com e https://login.example.com

  Per migliorare la privacy dell'utente, quando l'API One Tap viene chiamata da iframe multiorigine, devi aggiungere l'attributo allow="identity-credentials-get" in ogni tag iframe del frame principale:

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

  Se la tua app utilizza un iframe che contiene un altro iframe, devi assicurarti che l'attributo venga aggiunto a ogni iframe, inclusi tutti gli iframe secondari.

  Ad esempio, considera il seguente scenario:

• Il documento principale (https://www.example.uk) contiene un iframe denominato "Iframe A", che incorpora una pagina (https://logins.example.com).

• Questa pagina incorporata (https://logins.example.com) contiene anche un iframe denominato "Iframe B", che incorpora ulteriormente una pagina (https://onetap.example2.com) che ospita One Tap.

  Per garantire che One Tap possa essere visualizzato correttamente, l'attributo deve essere aggiunto a entrambi i tag iframe A e B.

  Nota: l'API Iframe intermedio supporta gli iframe cross-origin di FedCM. Non è necessario alcun attributo aggiuntivo. Tuttavia, se incorpori una pagina utilizzando l'API Iframe intermedio all'interno di un altro iframe, devi aggiungere l'attributo allow="identity-credentials-get" a tutti gli iframe principali. Abilita FedCM per testare e garantire la configurazione corretta dei criteri di autorizzazione su tutti i livelli.

  Preparati per le richieste relative al prompt One Tap non visualizzato. Altri siti con origini diverse potrebbero incorporare le tue pagine che ospitano One Tap nei propri iframe. Potresti ricevere un numero maggiore di richieste di assistenza relative alla mancata visualizzazione di One Tap da parte di utenti finali o altri proprietari di siti. Anche se gli aggiornamenti possono essere apportati solo dai proprietari delle pagine, puoi fare quanto segue per attenuare l'impatto:

• Aggiorna la documentazione per gli sviluppatori in modo da includere la procedura per configurare correttamente l'iframe per chiamare il tuo sito. Puoi inserire un link a questa pagina nella documentazione.

• Aggiorna la pagina delle domande frequenti per gli sviluppatori, se applicabile.

• Informa il tuo team di assistenza di questo imminente cambiamento e preparati per tempo a rispondere alla richiesta.

• Contatta in modo proattivo i partner, i clienti o i proprietari di siti interessati per una transizione senza problemi a FedCM.

  Nota: nella pagina interessata dovrebbe essere visualizzato il messaggio di errore nella console degli Strumenti per sviluppatori del browser Chrome: [GSI_LOGGER]: FedCM get() rejects with NotAllowedError: The 'identity-credentials-get' feature is not enabled in this document.

7. Aggiungi queste indicazioni ai tuoi criteri di sicurezza del contenuto (CSP, Content Security Policy).

Questo passaggio è facoltativo perché non tutti i siti web scelgono di definire un CSP.

• Se il CSP non viene utilizzato nel tuo sito web, non sono necessarie modifiche.

• Se il tuo fornitore di servizi di pagamento funziona per l'attuale One Tap e non utilizzi connect-src, frame-src, script-src, style-src o default-src, non sono necessarie modifiche.

• In caso contrario, segui questa guida per configurare il tuo CSP. Senza una corretta configurazione CSP, FedCM One Tap non verrebbe visualizzato sul sito.

  Nota: nella pagina interessata, dovresti vedere il messaggio di errore nella console degli Strumenti per sviluppatori del browser Chrome: [GSI_LOGGER]: FedCM get() rejects with NetworkError: Failed to execute 'get' on 'CredentialsContainer': Refused to connect to 'https://accounts.google.com/gsi/fedcm.json' because it violates the document's Content Security Policy.

8. Rimuovi il supporto di Accelerated Mobile Pages (AMP) per l'accesso.

Il supporto dell'accesso degli utenti per AMP è una funzionalità facoltativa di GIS che la tua app web potrebbe aver implementato. In questo caso,

Elimina eventuali riferimenti a:

• amp-onetap-google elemento personalizzato e

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

  Valuta la possibilità di reindirizzare le richieste di accesso da AMP al flusso di accesso HTML del tuo sito web. Tieni presente che Intermediate Iframe Support API correlato non è interessato.

Testare e verificare la migrazione

Dopo aver apportato le modifiche necessarie in base ai passaggi precedenti, puoi verificare che la migrazione sia riuscita.

1. Verifica che il tuo browser supporti FedCM e di avere già una sessione dell'Account Google.

2. Vai alle pagine One Tap nella tua applicazione.

3. Verifica che venga visualizzata la richiesta One Tap e che i contenuti sottostanti siano sovrapposti in modo sicuro.

4. Verifica che al tuo endpoint o metodo di callback venga restituita una credenziale corretta quando accedi alla tua applicazione utilizzando One Tap.

5. Se l'accesso automatico è abilitato, verifica che l'annullamento funzioni e che la credenziale corretta venga restituita all'endpoint o al metodo di callback.

Periodo di attesa di One Tap

Se fai clic su One Tap nell'angolo in alto a destra, la richiesta viene chiusa e viene attivato il periodo di attesa, che impedisce temporaneamente la visualizzazione della richiesta One Tap. In Chrome, se vuoi che la richiesta di One Tap venga visualizzata di nuovo prima del termine del periodo di attesa, puoi reimpostare lo stato del periodo di attesa facendo clic sull'icona a forma di lucchetto nella barra degli indirizzi e sul pulsante Reimposta autorizzazione.

Periodo di riposo per l'accesso automatico

Quando testi l'accesso automatico One Tap utilizzando FedCM, è presente un periodo di inattività di 10 minuti tra ogni tentativo di accesso automatico. Il periodo di silenzio non può essere reimpostato. Per attivare di nuovo l'accesso automatico, dovrai attendere 10 minuti o utilizzare un altro Account Google per i test.

Risorse utili

Privacy Sandbox Analysis Tool (PSAT) è un'estensione di Chrome DevTools che aiuta ad adottare API alternative come FedCM. Il suo funzionamento consiste nell'esaminare il sito per individuare le funzionalità interessate e fornire un elenco di modifiche consigliate.