Kami menghentikan Library Platform JavaScript Login dengan Google untuk web. Library tidak akan tersedia untuk didownload setelah tanggal penghentian 31 Maret 2023. Sebagai gantinya, gunakan Layanan Identitas Google yang baru untuk Web.
Secara default, Client ID yang baru dibuat kini diblokir agar tidak menggunakan Library Platform yang lebih lama, Client ID yang sudah ada tidak akan terpengaruh. Client ID baru yang dibuat sebelum 29 Juli 2022 dapat menetapkan `plugin_name` untuk mengaktifkan penggunaan Library Google Platform.

Referensi klien JavaScript Login dengan Google

Referensi ini menjelaskan metode dan atribut klien JavaScript yang akan Anda gunakan untuk menerapkan Login dengan Google di aplikasi web Anda.

Jika Anda mengalami masalah saat menggunakan library, harap laporkan ke repositori GitHub kami.

Penyiapan Autentikasi

Muat library platform Google API untuk membuat objek gapi:

<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>

Setelah library platform dimuat, muat library auth2:

function init() {
  gapi.load('auth2', function() {
    /* Ready. Make a call to gapi.auth2.init or some other API */
  });
}

gapi.auth2.init(params)

Menginisialisasi objek GoogleAuth. Anda harus memanggil metode ini sebelum memanggil metode gapi.auth2.GoogleAuth.

Saat melakukan inisialisasi objek GoogleAuth, Anda akan mengonfigurasi objek dengan client ID OAuth 2.0 dan opsi tambahan yang ingin Anda tentukan. Kemudian, jika pengguna sudah login, objek GoogleAuth akan memulihkan status login pengguna dari sesi sebelumnya.

Argumen
params Objek yang berisi key-value pair pada data konfigurasi klien. Lihat gapi.auth2.ClientConfig untuk berbagai properti yang dapat dikonfigurasi. Contoh: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
Hasil
gapi.auth2.GoogleAuth Objek gapi.auth2.GoogleAuth. Gunakan metode then() untuk mendapatkan Promise yang diselesaikan saat objek gapi.auth2.GoogleAuth selesai diinisialisasi.

GoogleAuth.then(onInit, onError)

Memanggil fungsi onInit saat objek GoogleAuth diinisialisasi sepenuhnya. Jika terjadi error saat melakukan inisialisasi (ini dapat terjadi di browser lama yang tidak didukung), fungsi onError akan dipanggil.

Argumen
onInit Fungsi dipanggil dengan objek GoogleAuth saat sudah diinisialisasi sepenuhnya.
onError Fungsi yang dipanggil dengan objek yang berisi properti error, jika GoogleAuth gagal diinisialisasi.
Hasil
Promise Promise yang terpenuhi saat fungsi onInit selesai, atau ditolak jika error inisialisasi terjadi. Fungsi ini akan diperbaiki dengan nilai yang ditampilkan dari fungsi onInit, jika ada.

Kode Error

idpiframe_initialization_failed
Gagal melakukan inisialisasi iframe yang diperlukan dari Google, misalnya karena lingkungan yang tidak didukung. Properti details akan memberikan informasi lebih lanjut tentang error yang terjadi.

API gapi.auth2.

Antarmuka yang merepresentasikan parameter konfigurasi yang berbeda untuk metode gapi.auth2.init.

Parameter
client_id string Wajib. Client ID aplikasi yang ditemukan dan dibuat di Google Developers Console.
cookie_policy string Domain yang akan dibuatkan cookie loginnya. URI, single_host_origin, atau none. Jika tidak ditentukan, setelan defaultnya adalah single_host_origin.
scope string Cakupan yang diminta, sebagai string yang dipisahkan spasi. Opsional jika fetch_basic_profile tidak ditetapkan ke false.
fetch_basic_profile boolean Mengambil informasi profil dasar pengguna saat mereka login. Menambahkan 'profile', 'email', dan 'openid' ke cakupan yang diminta. True jika tidak ditentukan.
hosted_domain string Domain G Suite yang harus dimiliki pengguna untuk login. Hal ini rentan terhadap modifikasi oleh klien, jadi pastikan untuk memverifikasi properti domain yang dihosting dari pengguna yang ditampilkan. Gunakan GoogleUser.getHostedDomain() pada klien, dan klaim hd di Token ID pada server untuk memverifikasi domain sesuai yang diharapkan.
ux_mode string Mode UX yang digunakan untuk alur login. Secara default, tindakan ini akan membuka alur izin di pop-up. Nilai yang valid adalah popup dan redirect.
redirect_uri string Jika menggunakan ux_mode='redirect', parameter ini memungkinkan Anda mengganti redirect_uri default yang akan digunakan pada akhir alur izin. redirect_uri default adalah URL saat ini yang dihilangkan dari parameter kueri dan fragmen hash.
plugin_name string Opsional. Jika nilai ini ditetapkan, Client ID baru yang dibuat sebelum 29 Juli 2022 dapat menggunakan Library Google Platform yang lebih lama. Secara default, Client ID yang baru dibuat kini diblokir agar tidak menggunakan Library Platform, dan sebagai gantinya harus menggunakan library Layanan Identitas Google yang lebih baru. Anda dapat memilih nilai apa pun, dan nama deskriptif seperti nama produk atau plugin direkomendasikan untuk memudahkan identifikasi. Contoh: plugin_name: 'YOUR_STRING_HERE'

Autentikasi

GoogleAuth adalah class singleton yang menyediakan metode untuk mengizinkan pengguna login dengan akun Google, mendapatkan status login pengguna saat ini, mendapatkan data tertentu dari profil Google pengguna, meminta cakupan tambahan, dan logout dari akun saat ini.

gapi.auth2.getAuthInstance()

Menampilkan objek GoogleAuth. Anda harus menginisialisasi objek GoogleAuth dengan gapi.auth2.init() sebelum memanggil metode ini.

Hasil
gapi.auth2.GoogleAuth Objek gapi.auth2.GoogleAuth. Gunakan objek ini untuk memanggil metode gapi.auth2.GoogleAuth.

GoogleAuth.isSignedIn.get()

Menampilkan apakah pengguna saat ini sedang login.

Hasil
Boolean true jika pengguna login, atau false jika pengguna logout atau objek GoogleAuth tidak diinisialisasi.

GoogleAuth.isSignedIn.listen(pemroses)

Mendeteksi perubahan pada status login pengguna saat ini.

Argumen
listener Fungsi yang mengambil nilai boolean. listen() meneruskan true ke fungsi ini saat pengguna login, dan false saat pengguna logout.

GoogleAuth.signIn()

Memproses login pengguna dengan opsi yang ditentukan untuk gapi.auth2.init().

Hasil
Promise Promise yang terpenuhi dengan instance GoogleUser saat pengguna berhasil mengautentikasi dan memberikan cakupan yang diminta, atau ditolak dengan objek yang berisi properti error jika terjadi error (lihat di bawah ini untuk kode kesalahan).

Kode error

Lihat GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

Membuat pengguna login menggunakan opsi yang ditentukan.

Argumen
options Salah satu dari:
  • Objek gapi.auth2.SignInOptions yang berisi key-value pair parameter login. Contoh: 
    {
  scope: 'profile email'
}
  • Instance gapi.auth2.SigninOptionsBuilder. Contoh:
    options = new gapi.auth2.SigninOptionsBuilder();
options.setAppPackageName('com.example.app');
options.setFetchBasicProfile(True);
options.setPrompt('select_account');
options.setScope('profile').setScope('email');
Hasil
Promise Promise yang terpenuhi dengan instance GoogleUser saat pengguna berhasil mengautentikasi dan memberikan cakupan yang diminta, atau ditolak dengan objek yang berisi properti error jika terjadi error (lihat di bawah ini untuk kode kesalahan).

Kode error

popup_closed_by_user
Pengguna menutup pop-up sebelum menyelesaikan alur login.
access_denied
Pengguna menolak izin untuk cakupan yang diperlukan.
immediate_failed
Tidak ada pengguna yang dapat dipilih secara otomatis tanpa meminta alur izin. Error muncul saat menggunakan signIn dengan opsi prompt: 'none'. Opsi ini seharusnya tidak perlu digunakan, karena gapi.auth2.init akan otomatis membuat pengguna login jika sebelumnya login selama sesi sebelumnya.

gapi.auth2.SignInOptions

Antarmuka yang merepresentasikan parameter konfigurasi yang berbeda untuk metode GoogleAuth.signIn(options).

Parameter
prompt string Memaksakan mode tertentu untuk alur izin. Opsional.
Nilai yang memungkinkan adalah:
  • consent
    Server otorisasi meminta persetujuan pengguna sebelum menampilkan informasi ke aplikasi.
  • select_account
    Server otorisasi meminta pengguna untuk memilih Akun Google. Hal ini memungkinkan pengguna yang memiliki beberapa akun untuk memilih di antara beberapa akun yang ingin mereka tetapkan sesinya saat ini.
  • none (tidak direkomendasikan)
    Server otorisasi tidak akan menampilkan layar autentikasi atau izin pengguna; akan menampilkan error jika pengguna belum diautentikasi dan belum menyetujui cakupan yang diminta.
    Karena gapi.auth2.init akan otomatis memproses login pengguna ke aplikasi jika sebelumnya login, memanggil signIn({prompt: 'none'}) biasanya akan gagal.
scope string Cakupan yang diminta, sebagai string yang dipisahkan spasi, di atas cakupan yang ditentukan dalam parameter gapi.auth2.init. Opsional jika fetch_basic_profile tidak ditetapkan ke salah.
ux_mode string Mode UX yang digunakan untuk alur login. Secara default, tindakan ini akan membuka alur izin di pop-up. Nilai yang valid adalah popup dan redirect.
redirect_uri string Jika menggunakan ux_mode='redirect', parameter ini memungkinkan Anda mengganti redirect_uri default yang akan digunakan pada akhir alur izin. redirect_uri default adalah URL saat ini yang dihilangkan dari parameter kueri dan fragmen hash.

GoogleAuth.signOut()

Membuat akun saat ini logout dari aplikasi.

Hasil
Promise Promise yang dipenuhi saat pengguna telah logout.

GoogleAuth.disconnect()

Mencabut semua cakupan yang diberikan pengguna.

GoogleAuth.grantOfflineAccess(options)

Mendapatkan izin dari pengguna untuk mengakses cakupan yang ditentukan secara offline.

Argumen
options Objek gapi.auth2.OfflineAccessOptions yang berisi key-value pair parameter. Contoh: 
{
  scope: 'profile email'
}
Hasil
Promise Promise yang terpenuhi saat pengguna memberikan cakupan yang diminta, meneruskan objek yang berisi kode otorisasi ke pengendali fulfillment Promise. Contoh: 
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

Kode error

popup_closed_by_user
Pengguna menutup pop-up sebelum menyelesaikan alur izin.
access_denied
Pengguna menolak izin untuk cakupan yang diperlukan.
immediate_failed
Tidak ada pengguna yang dapat dipilih secara otomatis tanpa meminta alur izin. Error muncul saat menggunakan signIn dengan opsi prompt: 'none'. Opsi ini seharusnya tidak perlu digunakan, karena gapi.auth2.init akan otomatis membuat pengguna login jika sebelumnya login selama sesi sebelumnya.

gapi.auth2.OfflineAccessOptions

Antarmuka yang merepresentasikan parameter konfigurasi yang berbeda untuk metode GoogleAuth.grantOfflineAccess(options).

Parameter
prompt string Memaksakan mode tertentu untuk alur izin. Opsional.
Nilai yang memungkinkan adalah:
  • consent
    Server otorisasi meminta persetujuan pengguna sebelum menampilkan informasi ke aplikasi.
  • select_account
    Server otorisasi meminta pengguna untuk memilih Akun Google. Hal ini memungkinkan pengguna yang memiliki beberapa akun untuk memilih di antara beberapa akun yang ingin mereka tetapkan sesinya saat ini.
scope string Cakupan yang diminta, sebagai string yang dipisahkan spasi, di atas cakupan yang ditentukan dalam parameter gapi.auth2.init. Opsional jika fetch_basic_profile tidak ditetapkan ke salah.

GoogleAuth.AttachClickHandler(container, options, onsuccess, onfailure)

Melampirkan alur login ke pengendali klik container yang ditentukan.

Argumen
container ID, atau referensi ke, elemen div yang akan digunakan untuk menambahkan pengendali klik.
options Objek yang berisi key-value pair parameter. Lihat GoogleAuth.signIn().
onsuccess Fungsi yang akan dipanggil setelah login selesai.
onfailure Fungsi yang akan dipanggil jika login gagal.

Pengguna

Objek GoogleUser mewakili satu akun pengguna. Objek GoogleUser biasanya diperoleh dengan memanggil GoogleAuth.currentUser.get().

GoogleAuth.currentUser.get()

Menampilkan objek GoogleUser yang merepresentasikan pengguna saat ini. Perhatikan bahwa pada instance GoogleAuth yang baru diinisialisasi, pengguna saat ini belum ditetapkan. Gunakan metode currentUser.listen() atau GoogleAuth.then() untuk mendapatkan instance GoogleAuth yang diinisialisasi.

Hasil
GoogleUser Pengguna aktif

GoogleAuth.currentUser.listen(listener)

Memproses perubahan pada currentUser.

Argumen
listener Fungsi yang menggunakan parameter GoogleUser. listen meneruskan fungsi GoogleUser ke instance ini pada setiap perubahan yang mengubah currentUser.

GoogleUser.getId()

Dapatkan string ID unik pengguna.

Hasil
String ID unik pengguna

GoogleUser.isSignedIn()

Menampilkan true jika pengguna login.

Hasil
Boolean True jika pengguna login

GoogleUser.getHostedDomain()

Dapatkan domain G Suite pengguna jika pengguna login dengan akun G Suite.

Hasil
String Domain G Suite pengguna

GoogleUser.getGrantedScopes()

Mendapatkan cakupan yang diberikan pengguna sebagai string yang dipisahkan spasi.

Hasil
String Cakupan yang diberikan oleh pengguna

GoogleUser.getBasicProfile()

Dapatkan informasi profil dasar pengguna.

Hasil
gapi.auth2.BasicProfile Anda dapat mengambil properti gapi.auth2.BasicProfile dengan metode berikut:
  • BasicProfile.getId()
  • BasicProfile.getName()
  • BasicProfile.getProvidenName()
  • BasicProfile.getFamilyName()
  • BasicProfile.getImageUrl()
  • BasicProfile.getEmail()

GoogleUser.getAuthResponse(termasukOtorisasiData)

Dapatkan objek respons dari sesi autentikasi pengguna.

Argumen
includeAuthorizationData Opsional: Boolean yang menentukan apakah akan selalu menampilkan token akses dan cakupan. Secara default, token akses dan cakupan yang diminta tidak ditampilkan saat fetch_basic_profile benar (nilai default) dan tidak ada cakupan tambahan yang diminta.
Hasil
gapi.auth2.AuthResponse Objek gapi.auth2.AuthResponse.

GoogleUser.reloadAuthResponse()

Memaksa pembaruan token akses, lalu menampilkan Promise untuk AuthResponse baru.

Hasil
Promise Promise yang diisi dengan gapi.auth2.AuthResponse yang dimuat ulang saat pemuatan ulang token OAuth selesai.

gapi.auth2.AuthResponse

Respons yang ditampilkan saat memanggil metode GoogleUser.getAuthResponse(includeAuthorizationData) atau GoogleUser.reloadAuthResponse().

Properti
access_token string Token Akses diberikan.
id_token string Token ID diberikan.
scope string Cakupan yang diberikan dalam Token Akses.
expires_in number Jumlah detik hingga Token Akses berakhir.
first_issued_at number Stempel waktu saat pengguna pertama kali memberikan cakupan yang diminta.
expires_at number Stempel waktu saat Token Akses akan berakhir masa berlakunya.

GoogleUser.hasGrantedScopes(scopes)

Menampilkan true jika pengguna memberikan cakupan yang ditentukan.

Argumen
scopes String cakupan yang dipisahkan spasi.
Hasil
Boolean True jika cakupan diberikan

GoogleUser.grant(options)

Meminta cakupan tambahan kepada pengguna.

Lihat GoogleAuth.signIn() untuk daftar parameter dan kode error.

GoogleUser.grantOfflineAccess(options)

Mendapatkan izin dari pengguna untuk mengakses cakupan yang ditentukan secara offline.

Argumen
options Objek gapi.auth2.OfflineAccessOptions yang berisi key-value pair parameter. Contoh: 
{
  scope: 'profile email'
}

GoogleUser.disconnect()

Mencabut semua cakupan yang diberikan pengguna untuk aplikasi.

Elemen UI

gapi.signin2.render(id, options)

Merender tombol login dalam elemen dengan ID yang diberikan, menggunakan setelan yang ditentukan oleh objek options.

Argumen
id ID elemen untuk merender tombol login.
options Objek yang berisi setelan yang akan digunakan untuk merender tombol. Misalnya: 
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
Anda dapat menentukan opsi berikut:
Parameter
cakupannya. Cakupan yang akan diminta saat pengguna login (default: profile).
lebar Lebar tombol dalam piksel (default: 120).
tinggi Tinggi tombol dalam piksel (default: 36).
judul panjang Tampilkan label panjang seperti "Login dengan Google", bukan "Login" (default: false). Saat menggunakan judul yang panjang, Anda harus meningkatkan lebar tombol dari default-nya.
tema Tema warna tombol: light atau dark (default: light).
saat berhasil Fungsi callback yang akan dipanggil saat pengguna berhasil login. Fungsi ini harus mengambil satu argumen: instance dari gapi.auth2.GoogleUser (default: none).
gagal Fungsi callback yang akan dipanggil saat login gagal. Fungsi ini tidak menggunakan argumen (default: tidak ada).

Lanjutan

gapi.auth2.authorize(params; callback)

Melakukan otorisasi OAuth 2.0 satu kali. Bergantung pada parameter yang digunakan, tindakan ini akan membuka jendela pop-up ke alur login Google atau mencoba memuat respons yang diminta tanpa suara, tanpa interaksi pengguna.

Beberapa kasus penggunaan di mana metode ini berguna, antara lain:

  • Aplikasi Anda hanya perlu meminta endpoint Google API satu kali, misalnya untuk memuat video YouTube favorit pengguna saat pertama kali login.
  • Aplikasi Anda memiliki infrastruktur pengelolaan sesi sendiri, dan hanya memerlukan Token ID sekali untuk mengidentifikasi pengguna di backend Anda.
  • Beberapa ID Klien digunakan dalam halaman yang sama.
Argumen
params Objek yang berisi key-value pair data konfigurasi. Lihat gapi.auth2.AuthorizeConfig untuk berbagai properti yang dapat dikonfigurasi. Contoh: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}
callback Fungsi yang dipanggil dengan objek gapi.auth2.AuthorizeResponse setelah permintaan selesai (baik berhasil atau gagal).

Contoh

gapi.auth2.authorize({
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}, function(response) {
  if (response.error) {
    // An error happened!
    return;
  }
  // The user authorized the application for the scopes requested.
  var accessToken = response.access_token;
  var idToken = response.id_token;
  // You can also now use gapi.client to perform authenticated requests.
});

Kode error

idpiframe_initialization_failed
Gagal melakukan inisialisasi iframe yang diperlukan dari Google, misalnya karena lingkungan yang tidak didukung. Properti details akan memberikan informasi lebih lanjut tentang error yang terjadi.
popup_closed_by_user
Pengguna menutup pop-up sebelum menyelesaikan alur login.
access_denied
Pengguna menolak izin untuk cakupan yang diperlukan.
immediate_failed
Tidak ada pengguna yang dapat dipilih secara otomatis tanpa meminta alur izin. Error muncul saat menggunakan signIn dengan opsi prompt: 'none'.

gapi.auth2.AuthorizeConfig

Antarmuka yang merepresentasikan parameter konfigurasi yang berbeda untuk metode gapi.auth2.authorize.

Properti
client_id string Required. Client ID aplikasi yang ditemukan dan dibuat di Google Developers Console.
scope string Required. Cakupan yang diminta, sebagai string yang dipisahkan spasi.
response_type string Daftar jenis respons yang dipisahkan spasi. Default-nya adalah 'permission'. Kemungkinan nilainya adalah:
  • id_token, untuk mengambil Token ID
  • permission (atau token), untuk mengambil Token Akses
  • code, untuk mengambil Kode Otorisasi
prompt string Memaksakan mode tertentu untuk alur izin. Kemungkinan nilainya adalah:
  • consent
    Server otorisasi meminta persetujuan pengguna sebelum menampilkan informasi ke aplikasi.
  • select_account
    Server otorisasi meminta pengguna untuk memilih Akun Google. Hal ini memungkinkan pengguna yang memiliki beberapa akun untuk memilih di antara beberapa akun yang ingin mereka tetapkan sesinya saat ini.
  • none
    Server otorisasi tidak akan menampilkan autentikasi atau layar persetujuan pengguna; akan menampilkan error jika pengguna belum diautentikasi dan belum menyetujui cakupan yang diminta.
    Jika code diminta sebagai jenis respons, kode yang ditampilkan hanya akan dapat ditukar dengan access_token, bukan refresh_token.
cookie_policy string Domain yang akan dibuatkan cookie loginnya. URI, single_host_origin, atau none. Jika tidak ditentukan, setelan defaultnya adalah single_host_origin.
hosted_domain string Domain G Suite yang harus dimiliki pengguna untuk login. Hal ini rentan terhadap modifikasi oleh klien, jadi pastikan untuk memverifikasi properti domain yang dihosting dari pengguna yang ditampilkan.
login_hint string Email atau ID Pengguna dari pengguna yang telah dipilih sebelumnya di alur login. Ini rentan terhadap modifikasi oleh pengguna, kecuali jika prompt: "none" digunakan.
include_granted_scopes boolean Apakah meminta Token Akses yang mencakup semua cakupan yang sebelumnya diberikan oleh pengguna ke aplikasi, atau hanya cakupan yang diminta dalam panggilan saat ini. Default-nya adalah true.
plugin_name string Opsional. Jika ditetapkan, Client ID yang dibuat sebelum 29 Juli 2022 dapat menggunakan Library Google Platform. Secara default, Client ID yang baru dibuat diblokir agar tidak menggunakan Library Platform, dan sebagai gantinya harus menggunakan library Layanan Identitas Google yang lebih baru. Anda dapat memilih nilai apa pun, dan nama deskriptif seperti nama produk atau plugin direkomendasikan untuk memudahkan identifikasi. Contoh: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

Respons yang ditampilkan ke callback metode gapi.auth2.authorize.

Properti
access_token string Token Akses diberikan. Hanya ada jika permission atau token ditentukan dalam response_type.
id_token string Token ID diberikan. Hanya ada jika id_token ditentukan dalam response_type.
code string Kode Otorisasi yang diberikan. Hanya ada jika code ditentukan dalam response_type.
scope string Cakupan yang diberikan dalam Token Akses. Hanya ada jika permission atau token ditentukan dalam response_type.
expires_in number Jumlah detik hingga Token Akses berakhir. Hanya ada jika permission atau token ditentukan dalam response_type.
first_issued_at number Stempel waktu saat pengguna pertama kali memberikan cakupan yang diminta. Hanya ada jika permission atau token ditentukan dalam response_type.
expires_at number Stempel waktu saat Token Akses akan berakhir masa berlakunya. Hanya ada jika permission atau token ditentukan dalam response_type.
error string Jika permintaan gagal, pesan ini akan berisi kode error.
error_subtype string Jika permintaan gagal, pesan ini dapat berisi informasi tambahan ke kode error yang juga ditampilkan.