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, laporkan ke repositori GitHub kami.
Penyiapan Auth
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)
Melakukan inisialisasi objek GoogleAuth
. Anda harus memanggil metode ini sebelum memanggil metode gapi.auth2.GoogleAuth
.
Saat melakukan inisialisasi objek GoogleAuth
, Anda perlu mengonfigurasi objek tersebut dengan client ID OAuth 2.0 dan opsi tambahan apa pun 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 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 error muncul saat melakukan inisialisasi (hal ini dapat terjadi di browser lama yang tidak didukung), fungsi onError akan dipanggil.
Argumen | |
---|---|
onInit |
Fungsi yang dipanggil dengan objek GoogleAuth saat telah diinisialisasi
sepenuhnya.
|
onError |
Fungsi yang dipanggil dengan objek yang berisi properti error , jika GoogleAuth gagal diinisialisasi.
|
Hasil | |
---|---|
Promise | Promise yang terpenuhi saat fungsi onInit telah selesai, atau ditolak jika terjadi error inisialisasi. Metode ini di-resolve dengan nilai yang ditampilkan dari fungsi onInit, jika ada. |
Kode Error
idpiframe_initialization_failed
-
Gagal melakukan inisialisasi iframe wajib dari Google, misalnya, karena lingkungan tidak didukung. Properti
details
akan memberikan informasi selengkapnya tentang error yang dilaporkan.
gapi.auth2.ClientConfig
Antarmuka yang mewakili berbagai parameter konfigurasi untuk
metode gapi.auth2.init
.
Parameter | ||
---|---|---|
client_id |
string |
Wajib. Client ID aplikasi, ditemukan dan dibuat di Konsol API Google. |
cookie_policy |
string |
Domain yang digunakan untuk membuat cookie login. URI,
single_host_origin , atau none . Nilai defaultnya adalah single_host_origin jika tidak ditentukan. |
scope |
string |
Cakupan yang akan diminta, sebagai string yang dipisahkan spasi. Opsional jika fetch_basic_profile tidak ditetapkan ke salah (false). |
fetch_basic_profile |
boolean |
Mengambil informasi profil dasar pengguna saat login. Menambahkan 'profile', 'email', dan 'openid' ke cakupan yang diminta. Benar jika tidak ditentukan. |
hosted_domain |
string |
Domain G Suite tempat pengguna harus masuk. Properti 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 pada Token ID di server untuk memverifikasi bahwa domain sesuai dengan harapan Anda.
|
use_fedcm |
boolean |
Opsional, ditetapkan secara default ke True . Aktifkan atau nonaktifkan penggunaan
API FedCM browser selama login. |
ux_mode |
string |
Mode UX yang akan 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 di akhir alur izin. redirect_uri
default adalah URL saat ini yang saat ini tidak berisi parameter kueri dan fragmen
hash.
|
enable_granular_consent |
boolean |
Opsional. Apakah akan mengaktifkan izin terperinci. Jika ditetapkan ke false , izin Akun Google yang lebih terperinci akan dinonaktifkan untuk client ID OAuth yang dibuat sebelum tahun 2019. Tidak berlaku untuk Client ID OAuth yang dibuat selama atau setelah tahun 2019, karena
izin yang lebih terperinci selalu diaktifkan untuk mereka.
|
plugin_name |
string |
Opsional. Jika nilai ini ditetapkan, Client ID baru yang dibuat sebelum 29
Juli 2022 dapat menggunakan Library Google Platform versi lama.
Secara default, Client ID yang baru dibuat kini diblokir agar tidak dapat menggunakan
Library Platform dan sebagai gantinya harus menggunakan library Google Identity
Services yang lebih baru. Anda dapat memilih nilai apa pun. Sebaiknya gunakan nama deskriptif seperti
nama produk atau plugin untuk identifikasi.
Contoh: plugin_name: 'YOUR_STRING_HERE'
|
Autentikasi
GoogleAuth
adalah class singleton yang menyediakan metode untuk memungkinkan 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 melakukan inisialisasi 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 sudah login, atau false jika pengguna logout atau objek GoogleAuth tidak diinisialisasi.
|
GoogleAuth.isSignedIn.listen(listener)
Memproses perubahan status login pengguna saat ini.
Argumen | |
---|---|
listener |
Fungsi yang menggunakan nilai boolean. listen() meneruskan true ke fungsi ini saat pengguna login, dan false saat pengguna logout.
|
GoogleAuth.signIn()
Membuat pengguna login dengan opsi yang ditentukan untuk gapi.auth2.init()
.
Hasil | |
---|---|
Promise | Promise yang dipenuhi dengan instance GoogleUser saat pengguna berhasil mengautentikasi dan memberikan cakupan yang diminta, atau ditolak dengan objek yang berisi properti error jika terjadi error. Lihat bagian berikutnya untuk mengetahui kode error. |
Kode error
Lihat GoogleAuth.signIn(options)
.
GoogleAuth.signIn(options)
Membuat pengguna login menggunakan opsi yang ditentukan.
Argumen | |
---|---|
options |
Atau:
|
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 kode error di bawah). |
Kode error
popup_closed_by_user
- Pengguna menutup pop-up sebelum menyelesaikan alur login.
access_denied
- Pengguna menolak izin ke cakupan yang diperlukan.
immediate_failed
-
Tidak ada pengguna yang dapat dipilih secara otomatis tanpa meminta alur izin. Error muncul saat menggunakan
signIn
dengan opsiprompt: 'none'
. Opsi ini tidak perlu diwajibkan, karenagapi.auth2.init
akan membuat pengguna login secara otomatis jika sebelumnya sudah login di sesi sebelumnya.
gapi.auth2.SignInOptions
Antarmuka yang mewakili berbagai parameter konfigurasi untuk
metode GoogleAuth.signIn(options)
.
Parameter | ||
---|---|---|
prompt |
string |
Memaksa mode tertentu untuk alur izin. Opsional. Kemungkinan nilainya adalah:
|
scope |
string |
Cakupan yang akan diminta, sebagai string yang dipisahkan spasi, selain cakupan yang ditentukan dalam
parameter gapi.auth2.init . Opsional jika fetch_basic_profile tidak ditetapkan ke salah (false).
|
ux_mode |
string |
Mode UX yang akan 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 di akhir alur
izin. redirect_uri default adalah URL saat ini yang saat ini tidak menyertakan parameter kueri dan fragmen hash.
|
GoogleAuth.signOut()
Membuat akun saat ini logout dari aplikasi.
Hasil | |
---|---|
Promise | Promise yang terpenuhi 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, dengan 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 ke cakupan yang diperlukan.
immediate_failed
-
Tidak ada pengguna yang dapat dipilih secara otomatis tanpa meminta alur izin. Error muncul saat menggunakan
signIn
dengan opsiprompt: 'none'
. Opsi ini tidak perlu digunakan karenagapi.auth2.init
akan membuat pengguna login secara otomatis jika sebelumnya sudah login di sesi sebelumnya.
gapi.auth2.OfflineAccessOptions
Antarmuka yang mewakili berbagai parameter konfigurasi untuk
metode
GoogleAuth.grantOfflineAccess(options)
.
Parameter | ||
---|---|---|
prompt |
string |
Memaksa mode tertentu untuk alur izin. Opsional. Kemungkinan nilainya adalah:
|
scope |
string |
Cakupan yang akan diminta, sebagai string yang dipisahkan spasi, selain cakupan yang ditentukan dalam
parameter gapi.auth2.init . Opsional jika fetch_basic_profile tidak ditetapkan ke salah (false).
|
GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)
Melampirkan alur login ke pengendali klik penampung yang ditentukan.
Argumen | |
---|---|
container | ID, atau referensi ke, elemen div yang akan ditambahi pengendali klik. |
options | Objek yang berisi pasangan nilai kunci 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 mewakili pengguna saat ini. Perhatikan bahwa dalam 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 saat ini |
GoogleAuth.currentUser.listen(listener)
Memproses perubahan pada currentUser.
Argumen | |
---|---|
listener |
Fungsi yang menggunakan parameter GoogleUser .
listen akan meneruskan instance GoogleUser ke fungsi ini pada setiap perubahan yang mengubah currentUser .
|
GoogleUser.getId()
Mendapatkan string ID unik pengguna.
Hasil | |
---|---|
String | ID unik pengguna |
GoogleUser.isSignedIn()
Menampilkan true (benar) jika pengguna login.
Hasil | |
---|---|
Boolean | True jika pengguna login |
GoogleUser.getHostedDomain()
Mendapatkan domain G Suite pengguna jika pengguna login dengan akun G Suite.
Hasil | |
---|---|
String | Domain G Suite pengguna |
GoogleUser.getGrantedScopes()
Dapatkan cakupan yang diberikan pengguna sebagai string yang dipisahkan spasi.
Hasil | |
---|---|
String | Cakupan yang diberikan oleh pengguna |
GoogleUser.getBasicProfile()
Mendapatkan informasi profil dasar pengguna.
Hasil | |
---|---|
gapi.auth2.BasicProfile |
Anda dapat mengambil properti gapi.auth2.BasicProfile
dengan metode berikut:
|
GoogleUser.getAuthResponse(includeAuthorizationData)
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 jika fetch_basic_profile bernilai benar (true) (nilai default) dan tidak ada cakupan tambahan yang diminta. |
Hasil | |
---|---|
gapi.auth2.AuthResponse |
Objek gapi.auth2.AuthResponse . |
GoogleUser.reloadAuthResponse()
Memaksa refresh token akses, lalu menampilkan Promise untuk AuthResponse baru.
Hasil | |
---|---|
Promise |
Promise yang terpenuhi dengan gapi.auth2.AuthResponse yang dimuat ulang saat token OAuth dimuat ulang selesai.
|
gapi.auth2.AuthResponse
Respons yang ditampilkan saat memanggil metode GoogleUser.getAuthResponse(includeAuthorizationData)
atau GoogleUser.reloadAuthResponse()
.
Properti | ||
---|---|---|
access_token |
string |
Token Akses yang diberikan. |
id_token |
string |
Token ID yang diberikan. |
scope |
string |
Cakupan yang diberikan dalam Token Akses. |
expires_in |
number |
Jumlah detik hingga Token Akses kedaluwarsa. |
first_issued_at |
number |
Stempel waktu saat pengguna pertama kali memberikan cakupan yang diminta. |
expires_at |
number |
Stempel waktu saat Token Akses akan kedaluwarsa. |
GoogleUser.hasGrantedScopes(scopes)
Menampilkan true (benar) jika pengguna diberi cakupan yang ditentukan.
Argumen | |
---|---|
scopes | String cakupan yang dipisahkan spasi. |
Hasil | |
---|---|
Boolean | True jika cakupan diberikan |
GoogleUser.grant(options)
Minta cakupan tambahan kepada pengguna.
Lihat GoogleAuth.signIn()
untuk mengetahui 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 pada elemen dengan ID yang diberikan, menggunakan setelan yang ditentukan oleh objek options.
Argumen | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | ID elemen tempat 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:
|
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 dengan Google atau mencoba memuat respons yang diminta secara diam-diam, tanpa interaksi pengguna.
Beberapa kasus penggunaan yang dapat memanfaatkan metode ini 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 satu kali untuk mengidentifikasi pengguna di backend.
- Beberapa Client-ID digunakan di halaman yang sama.
Argumen | |
---|---|
params |
Objek yang berisi pasangan nilai kunci data konfigurasi. Lihat
gapi.auth2.AuthorizeConfig untuk
properti lain 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 diselesaikan (baik berhasil maupun 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 wajib dari Google, misalnya, karena lingkungan tidak didukung. Properti
details
akan memberikan informasi selengkapnya tentang error yang dilaporkan. popup_closed_by_user
- Pengguna menutup pop-up sebelum menyelesaikan alur login.
access_denied
- Pengguna menolak izin ke cakupan yang diperlukan.
immediate_failed
-
Tidak ada pengguna yang dapat dipilih secara otomatis tanpa meminta alur izin. Error muncul saat menggunakan
signIn
dengan opsiprompt: 'none'
.
gapi.auth2.AuthorizeConfig
Antarmuka yang mewakili berbagai parameter konfigurasi untuk
metode gapi.auth2.authorize
.
Properti | ||
---|---|---|
client_id |
string |
Wajib diisi. Client ID aplikasi, ditemukan dan dibuat di Konsol API Google. |
scope |
string |
Wajib diisi. Cakupan yang akan diminta, sebagai string yang dipisahkan spasi. |
response_type |
string |
Daftar jenis respons yang dipisahkan spasi. Default-nya adalah 'permission' . Kemungkinan
nilainya adalah:
|
prompt |
string |
Memaksa mode tertentu untuk alur izin. Kemungkinan nilainya adalah:
|
cookie_policy |
string |
Domain yang digunakan untuk membuat cookie login. URI,
single_host_origin , atau none . Nilai defaultnya adalah single_host_origin jika tidak ditentukan.
|
hosted_domain |
string |
Domain G Suite tempat pengguna harus masuk. Properti 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, pengguna yang harus dipilih sebelumnya dalam alur login. Atribut ini rentan terhadap
diubah oleh pengguna, kecuali jika prompt: "none" digunakan.
|
include_granted_scopes |
boolean |
Apakah ingin meminta Token Akses yang menyertakan semua cakupan yang sebelumnya diberikan oleh pengguna ke aplikasi, atau hanya cakupan yang diminta dalam panggilan saat ini. Default-nya adalah true .
|
enable_granular_consent |
boolean |
Opsional. Apakah akan mengaktifkan izin terperinci. Jika ditetapkan ke false , izin Akun Google yang lebih terperinci akan dinonaktifkan untuk client ID OAuth yang dibuat sebelum tahun 2019. Tidak berlaku untuk Client ID OAuth yang dibuat selama atau setelah tahun 2019, karena
izin yang lebih terperinci selalu diaktifkan untuk mereka.
|
plugin_name |
string |
Opsional. Jika ditetapkan, Client-ID yang dibuat sebelum 29 Juli 2022 dapat menggunakan
Library Platform Google. Secara default, Client ID yang baru dibuat diblokir
agar tidak menggunakan Library Platform dan sebagai gantinya harus menggunakan library
Google Identity Services yang lebih baru. Anda dapat memilih nilai apa pun. Sebaiknya gunakan nama deskriptif seperti nama produk atau plugin 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 yang diberikan. Hanya ada jika permission atau token ditentukan dalam response_type .
|
id_token |
string |
Token ID yang 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 kedaluwarsa. 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 kedaluwarsa. Hanya ada jika permission atau token ditentukan dalam response_type .
|
error |
string |
Jika permintaan gagal, pesan berisi kode error. |
error_subtype |
string |
Jika permintaan gagal, permintaan ini dapat berisi informasi tambahan ke kode error yang juga ditampilkan. |