Referensi Login dengan Google HTML API

Halaman referensi ini menjelaskan API atribut data HTML Login Dengan Google. Anda dapat menggunakan API untuk menampilkan perintah Sekali Ketuk atau tombol Login Dengan Google di halaman web Anda.

Elemen dengan ID "g_id_onload"

Anda dapat menempatkan atribut data Login Dengan Google di elemen yang terlihat atau tidak terlihat, seperti <div> dan <span>. Satu-satunya persyaratan adalah ID elemen ditetapkan ke g_id_onload. Jangan menempatkan ID ini di beberapa elemen.

Atribut data

Tabel berikut mencantumkan atribut data beserta deskripsinya:

Jenis atribut

Bagian berikut berisi detail tentang jenis dan contoh setiap atribut.

data-client_id

Atribut ini adalah client ID aplikasi Anda, yang ditemukan dan dibuat di konsol Google Cloud. Lihat tabel berikut untuk informasi lebih lanjut:

data-auto_prompt

Atribut ini menentukan apakah akan menampilkan Sekali ketuk atau tidak. Nilai defaultnya adalah true. Ketukan Google One tidak ditampilkan saat nilai ini adalah false. Lihat tabel berikut untuk informasi lebih lanjut:

data-auto_select

Atribut ini menentukan apakah akan menampilkan token ID secara otomatis atau tidak, tanpa interaksi pengguna, jika hanya satu sesi Google yang telah menyetujui aplikasi Anda. Nilai defaultnya adalah false. Lihat tabel berikut untuk informasi lebih lanjut:

data-login_uri

Atribut ini adalah URI endpoint login Anda.

Nilai harus sama persis dengan salah satu URI alihan yang diotorisasi untuk klien OAuth 2.0, yang Anda konfigurasi di Konsol API dan harus sesuai dengan Aturan validasi URI alihan kami.

Atribut ini dapat dihilangkan jika halaman saat ini adalah halaman login Anda, yang berarti kredensial akan diposting ke halaman ini secara default.

Respons kredensial token ID diposting ke endpoint login Anda jika tidak ada fungsi callback yang ditentukan dan pengguna mengklik tombol Login dengan Google atau Sekali Ketuk, atau login otomatis terjadi.

Lihat tabel berikut untuk informasi lebih lanjut:

Endpoint login Anda harus menangani permintaan POST yang berisi kunci credential dengan nilai token ID di dalam isi.

Berikut adalah contoh permintaan ke endpoint login Anda:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

data-callback

Atribut ini adalah nama fungsi JavaScript yang menangani token ID yang ditampilkan. Lihat tabel berikut untuk informasi lebih lanjut:

Salah satu dari atribut data-login_uri dan data-callback mungkin digunakan. Bergantung pada komponen dan konfigurasi mode UX berikut:

• Atribut data-login_uri diperlukan untuk mode UX tombol Sign In With Google redirect, yang mengabaikan atribut data-callback.

• Salah satu dari dua atribut ini harus ditetapkan untuk Google Sekali Ketuk dan mode UX tombol Login Google popup. Jika keduanya ditetapkan, atribut data-callback akan lebih diprioritaskan.

Fungsi JavaScript dalam namespace tidak didukung oleh HTML API. Sebagai gantinya, gunakan fungsi JavaScript global tanpa namespace. Misalnya, gunakan mylibCallback, bukan mylib.callback.

data-native_login_uri

Atribut ini adalah URL endpoint pengendali kredensial sandi Anda. Jika Anda menetapkan atribut data-native_login_uri atau atribut data-native_callback, library JavaScript akan kembali ke pengelola kredensial native saat tidak ada sesi Google. Anda tidak diizinkan untuk menetapkan atribut data-native_callback dan data-native_login_uri sekaligus. Lihat tabel berikut untuk informasi lebih lanjut:

callback_data-native

Atribut ini adalah nama fungsi JavaScript yang menangani kredensial sandi yang ditampilkan dari pengelola kredensial native browser. Jika Anda menetapkan atribut data-native_login_uri atau atribut data-native_callback, library JavaScript akan kembali ke pengelola kredensial native saat tidak ada sesi Google. Anda tidak diizinkan untuk menetapkan data-native_callback dan data-native_login_uri. Lihat tabel berikut untuk mengetahui informasi lebih lanjut:

Fungsi JavaScript dalam namespace tidak didukung oleh HTML API. Sebagai gantinya, gunakan fungsi JavaScript global tanpa namespace. Misalnya, gunakan mylibCallback, bukan mylib.callback.

data-native_id_param

Saat mengirimkan kredensial sandi ke endpoint pengendali kredensial sandi, Anda dapat menentukan nama parameter untuk kolom credential.id. Nama defaultnya adalah email. Lihat tabel berikut untuk informasi lebih lanjut:

data-native_password_param

Saat mengirimkan kredensial sandi ke endpoint pengendali kredensial sandi, Anda dapat menentukan nama parameter untuk nilai credential.password. Nama defaultnya adalah password. Lihat tabel berikut untuk informasi selengkapnya:

data-cancel_on_tap_outside

Atribut ini menetapkan apakah akan membatalkan permintaan Sekali Ketuk jika pengguna mengklik di luar perintah. Nilai default-nya adalah true. Untuk menonaktifkannya, tetapkan nilai ke false. Lihat tabel berikut untuk informasi selengkapnya:

data-prompt_parent_id

Atribut ini menetapkan ID DOM elemen penampung. Jika tidak ditetapkan, perintah Sekali Ketuk akan ditampilkan di sudut kanan atas jendela. Lihat tabel berikut untuk mengetahui informasi selengkapnya:

data-skip_prompt_cookie

Atribut ini melewati fitur Sekali Ketuk jika cookie yang ditentukan memiliki nilai yang tidak kosong. Lihat tabel berikut untuk informasi selengkapnya:

data-nonce

Atribut ini adalah string acak yang digunakan oleh token ID untuk mencegah serangan replay. Lihat tabel berikut untuk informasi lebih lanjut:

Panjang nonce dibatasi ke ukuran JWT maksimum yang didukung oleh lingkungan Anda, serta batasan ukuran HTTP server dan browser individual.

data-context

Atribut ini mengubah teks judul dan pesan yang ditampilkan di perintah Satu Ketuk. Lihat tabel berikut untuk informasi lebih lanjut:

Tabel berikut mencantumkan semua konteks yang tersedia dan deskripsinya:

data-moment_callback

Atribut ini adalah nama fungsi pemroses notifikasi status UI perintah. Untuk informasi selengkapnya, lihat jenis data PromptMomentNotification.

Lihat tabel berikut untuk informasi lebih lanjut:

Fungsi JavaScript dalam namespace tidak didukung oleh HTML API. Sebagai gantinya, gunakan fungsi JavaScript global tanpa namespace. Misalnya, gunakan mylibCallback, bukan mylib.callback.

data-state_cookie_domain

Jika Anda perlu menampilkan One Tap di domain induk dan subdomainnya, teruskan domain induk ke atribut ini sehingga satu cookie status bersama digunakan. Lihat tabel berikut untuk informasi lebih lanjut:

data-ux_mode

Atribut ini menetapkan alur UX yang digunakan oleh tombol Login dengan Google. Nilai defaultnya adalah popup. Atribut ini tidak memengaruhi UX Sekali Ketuk. Lihat tabel berikut untuk informasi selengkapnya:

Tabel berikut mencantumkan mode UX yang tersedia dan deskripsinya.

data-allowed_parent_origin

Asal yang diizinkan untuk menyematkan iframe perantara. Sekali Ketuk berjalan dalam mode iframe perantara jika atribut ini ditampilkan. Lihat tabel berikut untuk informasi lebih lanjut:

Tabel berikut mencantumkan jenis nilai yang didukung dan deskripsinya.

Jika nilai atribut data-allowed_parent_origin tidak valid, inisialisasi Satu Ketuk mode iframe perantara akan gagal dan berhenti.

Awalan karakter pengganti juga didukung. Misalnya, "https://*.example.com" cocok dengan example.com dan subdomainnya di semua tingkat (misalnya news.example.com, login.news.example.com). Hal yang perlu diingat saat menggunakan karakter pengganti:

• String pola tidak boleh hanya terdiri dari karakter pengganti dan domain level teratas. Misalnya, https://*.com dan https://*.co.uk tidak valid; Seperti disebutkan di atas, "https://*.example.com" cocok dengan example.com dan subdomainnya. Anda juga dapat menggunakan daftar yang dipisahkan koma untuk mewakili 2 domain berbeda. Misalnya, "https://example1.com,https://*.example2.com" cocok dengan domain example1.com, example2.com, dan subdomain example2.com
• Domain karakter pengganti harus diawali dengan skema https:// yang aman, sehingga "*.example.com" dianggap tidak valid.

data-intermediate_iframe_close_callback

Mengganti perilaku iframe perantara default saat pengguna menutup Sekali Ketuk secara manual dengan mengetuk tombol 'X' di UI Sekali Ketuk. Perilaku defaultnya adalah menghapus iframe perantara dari DOM secara langsung.

Kolom data-intermediate_iframe_close_callback hanya berlaku dalam mode iframe perantara. Dan hanya berdampak pada iframe perantara, bukan iframe Sekali Ketuk. UI Ketuk Sekali dihapus sebelum callback dipanggil.

Fungsi JavaScript dalam namespace tidak didukung oleh HTML API. Sebagai gantinya, gunakan fungsi JavaScript global tanpa namespace. Misalnya, gunakan mylibCallback, bukan mylib.callback.

data-itp_support

Kolom ini menentukan apakah UX Sekali Ketuk yang diupgrade harus diaktifkan di browser yang mendukung Intelligent Tracking Prevention (ITP). Nilai defaultnya adalah false. Lihat tabel berikut untuk informasi lebih lanjut:

petunjuk_login-data

Jika aplikasi Anda mengetahui lebih awal pengguna yang harus login, aplikasi tersebut dapat memberikan petunjuk login ke Google. Jika berhasil, pemilihan akun akan dilewati. Nilai yang diterima adalah: alamat email atau kolom sub token ID.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi OpenID Connect untuk login_hint.

data-hd

Jika pengguna memiliki beberapa akun dan sebaiknya hanya login dengan akun Workspace-nya, gunakan ini untuk memberikan petunjuk nama domain kepada Google. Jika berhasil, akun pengguna yang ditampilkan selama pemilihan akun akan dibatasi untuk domain yang diberikan. Nilai karakter pengganti: * hanya menawarkan akun Workspace kepada pengguna dan tidak menyertakan akun konsumen (pengguna@gmail.com) selama pemilihan akun.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi OpenID Connect untuk hd.

data-use_fedcm_for_prompt

Izinkan browser mengontrol perintah login pengguna dan memediasi alur login antara situs Anda dan Google. Nilai defaultnya adalah false (salah). Lihat halaman Migrasi ke FedCM untuk mengetahui informasi selengkapnya.

data-enable_redirect_uri_validation

Mengaktifkan alur pengalihan tombol yang mematuhi Aturan validasi URI pengalihan.

Elemen dengan class "g_id_signin"

Jika Anda menambahkan g_id_signin ke atribut class elemen, elemen tersebut akan dirender sebagai tombol Login Dengan Google.

Anda dapat merender beberapa tombol Login dengan Google di halaman yang sama. Setiap tombol dapat memiliki setelan visualnya sendiri. Setelan ditentukan oleh atribut data berikut.

Atribut Data Visual

Tabel berikut mencantumkan atribut data visual dan deskripsinya:

Jenis atribut

Bagian berikut berisi detail tentang jenis dan contoh setiap atribut.

data-type

Jenis tombol. Nilai default-nya adalah standard. Lihat tabel berikut untuk mengetahui informasi selengkapnya:

Tabel berikut mencantumkan semua jenis tombol yang tersedia beserta deskripsinya:

Jenis
standard
icon

data-theme

Tema tombol. Nilai default-nya adalah outline. Lihat tabel berikut untuk mengetahui informasi selengkapnya:

Tabel berikut mencantumkan tema yang tersedia dan deskripsinya:

Tema
outline
filled_blue
filled_black

data-size

Ukuran tombol. Nilai default-nya adalah large. Lihat tabel berikut untuk mengetahui informasi lebih lanjut:

Tabel berikut mencantumkan ukuran tombol yang tersedia dan deskripsinya.

Ukuran
large
medium
small

data-text

Teks tombol. Nilai default-nya adalah signin_with. Tidak ada perbedaan visual untuk teks tombol ikon yang memiliki atribut data-text yang berbeda. Satu-satunya pengecualian adalah saat teks dibaca untuk aksesibilitas layar.

Lihat tabel berikut untuk informasi lebih lanjut:

Tabel berikut mencantumkan teks tombol yang tersedia dan deskripsinya:

Teks
signin_with
signup_with
continue_with
signin

bentuk-data

Bentuk tombol. Nilai default-nya adalah rectangular. Lihat tabel berikut untuk informasi lebih lanjut:

Tabel berikut mencantumkan bentuk tombol yang tersedia dan deskripsinya:

Bentuk
rectangular
pill
circle
square

data-logo_alignment

Penyelarasan logo Google. Nilai default-nya adalah left. Atribut ini hanya berlaku untuk jenis tombol standard. Lihat tabel berikut untuk informasi lebih lanjut:

Tabel berikut mencantumkan perataan yang tersedia dan deskripsinya:

logo_alignment
left
center

data-width

Lebar tombol minimum, dalam piksel. Lebar maksimum yang tersedia adalah 400 piksel.

Lihat tabel berikut untuk informasi lebih lanjut:

lokal data

Opsional. Menampilkan teks tombol menggunakan lokalitas yang ditentukan. Jika tidak, secara default mengikuti setelan Akun Google atau browser pengguna. Tambahkan parameter hl dan kode bahasa ke perintah src saat memuat library, misalnya: gsi/client?hl=<iso-639-code>.

Jika tidak ditetapkan, lokalitas default browser atau preferensi pengguna sesi Google akan digunakan. Oleh karena itu, pengguna yang berbeda mungkin melihat versi tombol yang dilokalkan dan mungkin dengan ukuran yang berbeda.

Lihat tabel berikut untuk informasi lebih lanjut:

data-click_pemroses

Anda dapat menentukan fungsi JavaScript yang akan dipanggil saat tombol Login dengan Google diklik menggunakan atribut data-click_listener.

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

Dalam contoh ini, pesan Tombol Login dengan Google diklik... dicatat ke konsol saat tombol Login dengan Google diklik.

status data

Opsional, karena beberapa tombol Login dengan Google dapat dirender di halaman yang sama, Anda dapat menetapkan setiap tombol dengan string unik. String yang sama akan ditampilkan bersama dengan token ID, sehingga Anda dapat mengidentifikasi tombol mana yang diklik pengguna untuk login.

Lihat tabel berikut untuk informasi lebih lanjut:

Integrasi sisi server

Endpoint sisi server Anda harus menangani permintaan POST HTTP berikut.

Endpoint pengendali token ID

Endpoint pengendali token ID memproses token ID. Berdasarkan status akun yang sesuai, Anda dapat memproses login pengguna dan mengarahkannya ke halaman pendaftaran atau mengarahkannya ke halaman penautan akun untuk mendapatkan informasi tambahan.

Permintaan POST HTTP berisi informasi berikut:

kredensial

Saat didekode, token ID akan terlihat seperti contoh berikut:

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "elisa.g.beckett@gmail.com", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

Kolom sub adalah ID unik global untuk Akun Google. Hanya gunakan kolom sub sebagai ID untuk pengguna karena kolom ini unik di antara semua Akun Google dan tidak pernah digunakan kembali. Jangan gunakan alamat email sebagai ID karena Akun Google dapat memiliki beberapa alamat email pada waktu yang berbeda.

Dengan menggunakan kolom email, email_verified, dan hd, Anda dapat menentukan apakah Google menghosting dan memiliki otoritas untuk alamat email. Jika Google memiliki otoritas, pengguna akan dikonfirmasi sebagai pemilik akun yang sah.

Kasus saat Google bersifat otoritatif:

• email memiliki akhiran @gmail.com, ini adalah akun Gmail.
• email_verified benar dan hd ditetapkan, ini adalah akun Google Workspace.

Pengguna dapat mendaftar ke Akun Google tanpa menggunakan Gmail atau Google Workspace. Jika email tidak berisi akhiran @gmail.com dan hd tidak ada, Google tidak akan memiliki otoritas dan sandi atau metode tantangan lainnya direkomendasikan untuk memverifikasi pengguna. email_verified juga bisa benar karena Google awalnya memverifikasi pengguna saat Akun Google dibuat, tetapi kepemilikan akun email pihak ketiga mungkin telah berubah.

Kolom exp menampilkan waktu habis masa berlaku agar Anda dapat memverifikasi token di sisi server. Masa berlakunya adalah satu jam untuk token ID yang diperoleh dari Login dengan Google. Anda harus memverifikasi token sebelum waktu habis masa berlakunya. Jangan gunakan exp untuk pengelolaan sesi. Masa berlaku token ID yang habis bukan berarti pengguna logout. Aplikasi Anda bertanggung jawab atas pengelolaan sesi pengguna.

select_by

Tabel berikut mencantumkan kemungkinan nilai untuk kolom select_by. Jenis tombol yang digunakan bersama dengan sesi dan status izin digunakan untuk menetapkan nilai,

• Pengguna menekan tombol Sekali Ketuk atau Login Dengan Google atau menggunakan proses Login otomatis tanpa kontak fisik.

• Sesi yang ada ditemukan, atau pengguna memilih dan login ke Akun Google untuk membuat sesi baru.

• Sebelum membagikan kredensial token ID ke aplikasi Anda, pengguna dapat

  • menekan tombol Konfirmasi untuk memberikan izin berbagi kredensial, atau
  • sebelumnya telah memberikan izin dan menggunakan Pilih Akun untuk memilih Akun Google.

Nilai kolom ini ditetapkan ke salah satu jenis berikut,

dengan status tersembunyi akhir

Parameter ini hanya ditentukan saat pengguna mengklik tombol Login dengan Google untuk login, dan atribut data-state tombol yang diklik ditentukan. Nilai kolom ini adalah nilai yang sama dengan yang Anda tentukan dalam atribut data-state tombol.

Karena beberapa tombol Login dengan Google dapat dirender di halaman yang sama, Anda dapat menetapkan setiap tombol dengan string unik. Oleh karena itu, Anda dapat menggunakan parameter state ini untuk mengidentifikasi tombol yang diklik pengguna untuk login.

Endpoint pengendali kredensial sandi

Endpoint pengendali kredensial sandi memproses kredensial sandi yang diambil oleh pengelola kredensial native.

Permintaan POST HTTP berisi informasi berikut: