Bermigrasi ke FedCM

Panduan ini membantu Anda memahami perubahan pada aplikasi web yang diperkenalkan oleh Federated Credentials Management API (FedCM).

Jika FedCM diaktifkan, browser akan menampilkan perintah pengguna dan tidak ada cookie pihak ketiga yang digunakan.

Ringkasan

FedCM memungkinkan alur login yang lebih pribadi tanpa memerlukan penggunaan cookie pihak ketiga. Browser mengontrol setelan pengguna, menampilkan perintah pengguna, dan hanya menghubungi Penyedia Identitas seperti Google setelah izin pengguna yang eksplisit diberikan.

Untuk sebagian besar situs, migrasi terjadi dengan lancar melalui update yang kompatibel dengan versi sebelumnya ke library JavaScript Google Identity Services.

Tips: Selama eksperimen Google dan uji coba origin Chrome, beberapa persen dari jumlah total pengguna yang login ke situs Anda akan menggunakan FedCM API. Persentase spesifiknya bervariasi dan dapat berubah tanpa pemberitahuan. Sebelum FedCM menjadi wajib untuk semua login, gunakan data-use_fedcm_for_prompt atau use_fedcm_for_prompt untuk memilih alur login. Tindakan ini dapat meningkatkan kemampuan Anda untuk men-debug, mengumpulkan metrik, atau mengalihkan semua login ke FedCM setelah menyelesaikan migrasi.

Pembaruan pada fitur Login Otomatis

Federated Credential Management (FedCM) Beta untuk Google Identity Services diluncurkan pada Agustus 2023. Banyak developer telah menguji API dan memberikan masukan yang berharga.

Salah satu respons yang diterima Google dari developer adalah tentang persyaratan gestur pengguna alur login otomatis FedCM. Untuk meningkatkan privasi, Chrome mengharuskan pengguna untuk mengonfirmasi ulang bahwa mereka ingin login ke situs dengan Akun Google di setiap instance Chrome meskipun pengguna menyetujui situs tersebut sebelum peluncuran FedCM. Konfirmasi ulang satu kali ini dilakukan dengan sekali klik perintah Satu Ketuk untuk menunjukkan niat pengguna untuk login. Perubahan ini dapat menyebabkan gangguan awal pada rasio konversi login otomatis untuk beberapa situs.

Baru-baru ini di M121, Chrome melakukan perubahan pada UX alur login otomatis FedCM. Konfirmasi ulang hanya diperlukan jika cookie pihak ketiga dibatasi. Artinya:

1. Login otomatis FedCM tidak memerlukan konfirmasi ulang untuk pengguna yang kembali. Jika pengguna mengonfirmasi ulang dengan UI FedCM, konfirmasi ulang ini akan dihitung sebagai persyaratan gestur pengguna untuk era pasca-3PCD.

2. Login otomatis FedCM akan memeriksa status konfirmasi ulang saat cookie pihak ketiga dibatasi secara manual oleh pengguna saat ini, atau secara default di Chrome mendatang.

Dengan perubahan ini, sebaiknya semua developer login otomatis bermigrasi ke FedCM segera mungkin, untuk mengurangi gangguan pada rasio konversi login otomatis.

Untuk alur login otomatis, JavaScript GIS tidak akan memicu FedCM di Chrome lama (sebelum M121), meskipun situs Anda memilih untuk ikut serta dalam FedCM.

Perbedaan perjalanan pengguna

Pengalaman Sekali Ketuk menggunakan FedCM dan tanpa FedCM hanya mirip dengan perbedaan kecil.

Pengguna baru sesi tunggal

Dengan menggunakan FedCM, One Tap menampilkan nama domain level teratas, bukan nama aplikasi.

Menggunakan FedCM	Tanpa FedCM

Pengguna yang kembali dalam satu sesi (dengan login otomatis dinonaktifkan)

Dengan menggunakan FedCM, One Tap menampilkan nama domain level teratas, bukan nama aplikasi.

Menggunakan FedCM	Tanpa FedCM

Pengguna yang kembali dalam satu sesi (dengan login otomatis diaktifkan)

Dengan FedCM, pengguna dapat mengklik X untuk membatalkan login otomatis dalam waktu 5 detik, bukan mengklik tombol Cancel.

Menggunakan FedCM	Tanpa FedCM

Multi-sesi

Dengan menggunakan FedCM, One Tap menampilkan nama domain level teratas, bukan nama aplikasi.

Menggunakan FedCM	Tanpa FedCM

Sebelum memulai

Pastikan setelan dan versi browser Anda mendukung FedCM API. Sebaiknya update ke versi terbaru.

• FedCM API tersedia di Chrome 117 atau yang lebih baru.

• Setelan Login pihak ketiga diaktifkan di Chrome.

• Jika versi browser Chrome Anda adalah 119 atau yang lebih lama, buka chrome://flags dan aktifkan fitur FedCmWithoutThirdPartyCookies eksperimental. Langkah ini tidak diperlukan dengan browser Chrome versi 120 atau yang lebih baru.

Memigrasikan aplikasi web

Ikuti langkah-langkah berikut untuk mengaktifkan FedCM, mengevaluasi potensi dampak migrasi, dan jika diperlukan, membuat perubahan pada aplikasi web yang ada:

1. Tambahkan flag boolean untuk mengaktifkan FedCM saat melakukan inisialisasi menggunakan:

• HTML, tetapkan atribut data-use_fedcm_for_prompt ke true.

• JavaScript, tetapkan use_fedcm_for_prompt ke true di objek IdConfiguration.

2. Hapus penggunaan metode isDisplayMoment(), isDisplayed(), isNotDisplayed(), dan getNotDisplayedReason() dalam kode Anda.

Untuk meningkatkan privasi pengguna, callback google.accounts.id.prompt tidak lagi menampilkan notifikasi momen tampilan apa pun di objek PromptMomentNotication. Hapus kode apa pun yang bergantung pada metode terkait momen tampilan. Metode tersebut adalah metode isDisplayMoment(), isDisplayed(), isNotDisplayed(), dan getNotDisplayedReason().

3. Hapus penggunaan metode getSkippedReason() dalam kode Anda.

Meskipun momen lewati, isSkippedMoment(), akan tetap dipanggil dari callback google.accounts.id.prompt dalam objek PromptMomentNotication, alasan mendetail tidak akan diberikan. Hapus kode apa pun yang bergantung pada metode getSkippedReason() dari kode Anda.

Perhatikan bahwa notifikasi momen yang ditutup, isDismissedMoment(), dan metode alasan mendetail terkait, getDismissedReason(), tidak berubah saat FedCM diaktifkan.

4. Hapus atribut gaya position dari data-prompt_parent_id dan intermediate_iframes.

Browser mengontrol ukuran dan posisi perintah pengguna, posisi kustom untuk Satu Ketuk di Desktop tidak didukung.

5. Perbarui tata letak halaman jika diperlukan.

Browser mengontrol ukuran dan posisi perintah pengguna. Bergantung pada tata letak setiap halaman, beberapa konten mungkin ditempatkan karena posisi kustom untuk Satu Ketuk di Desktop tidak didukung dengan cara apa pun seperti atribut gaya, data-prompt_parent_id, intermediate_iframes, iframe yang disesuaikan, dan cara kreatif lainnya.

Ubah tata letak halaman untuk meningkatkan pengalaman pengguna saat informasi penting disamarkan. Jangan buat UX Anda berdasarkan perintah Sekali Ketuk meskipun Anda mengasumsikan perintah tersebut berada di posisi default. Karena FedCM API dimediasi browser, vendor browser yang berbeda dapat menempatkan posisi perintah dengan sedikit perbedaan.

6. Tambahkan atribut allow="identity-credentials-get" ke frame induk jika aplikasi web Anda memanggil One Tap API dari iframe lintas origin.

Iframe dianggap sebagai lintas-asal jika asalnya tidak sama persis dengan asal induk. Misalnya:

• Domain yang berbeda: https://example1.com dan https://example2.com
• Domain level teratas yang berbeda: https://example.uk dan https://example.jp
• Subdomain: https://example.com dan https://login.example.com

Saat menggunakan Sekali Ketuk di iframe lintas origin, pengguna mungkin akan mengalami pengalaman yang membingungkan. Perintah Ketuk Sekali menampilkan nama domain level teratas, bukan nama iframe, sebagai langkah pengamanan untuk mencegah pengambilan kredensial. Namun, token ID diterbitkan ke origin iframe. Tinjau masalah GitHub ini untuk mengetahui detail selengkapnya.

Karena perbedaan ini dapat menyesatkan, hanya menggunakan Satu Ketuk di iframe lintas origin, tetapi situs yang sama adalah metode yang didukung. Misalnya, halaman di domain level teratas https://www.example.com menggunakan iframe untuk menyematkan halaman dengan Satu Ketuk di https://login.example.com. Perintah Sekali Ketuk akan menampilkan "Login ke example.com dengan google.com".

Semua kasus lainnya seperti domain yang berbeda tidak didukung. Sebagai gantinya, pertimbangkan metode integrasi alternatif seperti:

• Mengimplementasikan tombol Login dengan Google.
• Mengimplementasikan Sekali Ketuk di domain level teratas
• Menggunakan endpoint Google OAuth 2.0 untuk integrasi yang lebih disesuaikan.
• Jika menyematkan situs pihak ketiga dalam iframe dan tidak dapat mengubah penerapan Sekali Ketuk, Anda dapat mencegah perintah Sekali Ketuk muncul dalam iframe. Untuk melakukannya, hapus atribut allow="identity-credentials-get" dari tag iframe di frame induk. Tindakan ini akan menyembunyikan perintah, dan Anda dapat langsung memandu pengguna ke halaman login situs tersemat.

Saat One Tap API dipanggil dari iframe lintas origin, Anda harus menambahkan atribut allow="identity-credentials-get" di setiap tag iframe frame induk:

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

Jika aplikasi Anda menggunakan iframe yang berisi iframe lain, Anda harus memastikan bahwa atribut ditambahkan ke setiap iframe, termasuk semua sub-iframe.

Misalnya, perhatikan skenario berikut:

• Dokumen teratas (https://www.example.uk) berisi iframe bernama "Iframe A", yang menyematkan halaman (https://logins.example.com).

• Halaman tersemat ini (https://logins.example.com) juga berisi iframe bernama "Iframe B", yang selanjutnya menyematkan halaman (https://onetap.example2.com) yang menghosting One Tap.

  Untuk memastikan bahwa Satu Ketuk dapat ditampilkan dengan benar, atribut harus ditambahkan ke tag Iframe A dan Iframe B.

  Catatan: Intermediate Iframe API mendukung iframe lintas origin FedCM. Tidak diperlukan atribut tambahan. Namun, jika menyematkan halaman menggunakan Intermediate Iframe API dalam iframe lain, Anda harus menambahkan atribut allow="identity-credentials-get" ke semua iframe induk. Aktifkan FedCM untuk menguji dan memastikan penyiapan kebijakan izin yang tepat di semua lapisan.

  Bersiaplah untuk pertanyaan tentang perintah Sekali Ketuk yang tidak ditampilkan. Situs lain dengan asal yang berbeda dapat menyematkan halaman Anda yang menghosting Satu Ketuk dalam iframe-nya. Anda mungkin menerima peningkatan jumlah tiket dukungan terkait One Tap yang tidak muncul dari pengguna akhir atau pemilik situs lainnya. Meskipun pembaruan hanya dapat dilakukan oleh pemilik situs di halaman mereka, Anda dapat melakukan hal berikut untuk mengurangi dampaknya:

• Perbarui dokumentasi developer Anda untuk menyertakan cara menyiapkan iframe dengan benar untuk memanggil situs Anda. Anda dapat menautkan ke halaman ini dalam dokumentasi Anda.

• Perbarui halaman FAQ developer Anda jika ada.

• Beri tahu tim dukungan Anda tentang perubahan mendatang ini dan siapkan respons terhadap pertanyaan tersebut terlebih dahulu.

• Hubungi secara proaktif partner, pelanggan, atau pemilik situs yang terpengaruh untuk melakukan transisi FedCM yang lancar.

  Catatan: Di halaman yang terpengaruh, Anda akan melihat pesan error di konsol Developer Tools browser Chrome: [GSI_LOGGER]: FedCM get() rejects with NotAllowedError: The 'identity-credentials-get' feature is not enabled in this document.

7. Tambahkan perintah ini ke Kebijakan Keamanan Konten (CSP) Anda.

Langkah ini bersifat opsional karena tidak semua situs memilih untuk menentukan CSP.

• Jika CSP tidak digunakan di situs Anda, tidak perlu melakukan perubahan.

• Jika CSP Anda berfungsi untuk fitur Sekali Ketuk saat ini dan Anda tidak menggunakan connect-src, frame-src, script-src, style-src, atau default-src, tidak ada perubahan yang diperlukan.

• Jika tidak, ikuti panduan ini untuk menyiapkan CSP Anda. Tanpa penyiapan CSP yang tepat, FedCM One Tap tidak akan ditampilkan di situs.

  Catatan: Di halaman yang terpengaruh, Anda akan melihat pesan error di konsol Developer Tools 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. Hapus dukungan Accelerated Mobile Pages (AMP) untuk login.

Dukungan login pengguna untuk AMP adalah fitur opsional GIS yang mungkin telah diterapkan oleh aplikasi web Anda. Jika demikian,

Hapus semua referensi ke:

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

  Pertimbangkan untuk mengalihkan permintaan login dari AMP ke alur login HTML situs Anda. Perhatikan bahwa Intermediate Iframe Support API terkait tidak terpengaruh.

Menguji dan memverifikasi migrasi

Setelah melakukan perubahan yang diperlukan berdasarkan langkah-langkah sebelumnya, Anda dapat memverifikasi migrasi berhasil.

1. Pastikan browser Anda mendukung FedCM dan Anda memiliki sesi Akun Google yang sudah ada.

2. Buka halaman Sekali Ketuk di aplikasi Anda.

3. Pastikan perintah Ketuk Sekali ditampilkan dan menempatkan konten yang mendasarinya dengan aman.

4. Konfirmasi kredensial yang benar ditampilkan ke endpoint atau metode callback Anda saat login ke aplikasi menggunakan One Tap.

5. Jika login otomatis diaktifkan, pastikan pembatalan berfungsi dan kredensial yang benar ditampilkan ke endpoint atau metode callback Anda.

Periode tunggu Sekali Ketuk

Mengklik Sekali Ketuk di pojok kanan atas akan menutup perintah dan memasuki periode tunggu yang mencegah perintah Sekali Ketuk ditampilkan untuk sementara. Di Chrome, jika Anda ingin perintah Sekali Ketuk ditampilkan lagi sebelum periode tunggu berakhir, Anda dapat mereset status tunggu dengan mengklik ikon gembok di kolom URL dan mengklik tombol Reset Izin.

Periode tenang login otomatis

Saat menguji login otomatis One Tap menggunakan FedCM, periode tunggunya adalah 10 menit di antara setiap upaya login otomatis. Periode tenang tidak dapat direset. Anda harus menunggu selama 10 menit atau menggunakan Akun Google lain untuk pengujian agar dapat memicu login otomatis lagi.

Sumber daya bermanfaat

Privacy Sandbox Analysis Tool (PSAT) adalah ekstensi Chrome DevTools untuk membantu penerapan API alternatif seperti FedCM. Alat ini berfungsi dengan memindai situs Anda untuk menemukan fitur yang terpengaruh dan memberikan daftar perubahan yang direkomendasikan.