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 ini, 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)
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 apa pun yang ingin ditentukan. Kemudian, jika pengguna sudah login, objek GoogleAuth
akan memulihkan status login pengguna dari sesi sebelumnya.
Arguments | |
---|---|
params |
Objek yang berisi key-value pair data konfigurasi klien. Lihat
gapi.auth2.ClientConfig untuk mengetahui
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 di-resolve saat objek gapi.auth2.GoogleAuth selesai melakukan inisialisasi.
|
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.
Arguments | |
---|---|
onInit |
Fungsi yang dipanggil dengan objek GoogleAuth saat diinisialisasi sepenuhnya.
|
onError |
Fungsi dipanggil dengan objek yang berisi properti error , jika GoogleAuth gagal diinisialisasi.
|
Hasil | |
---|---|
Promise | Promise yang dipenuhi saat fungsi onInit telah selesai, atau ditolak jika terjadi error inisialisasi. Metode ini me-resolve 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 tidak didukung. Properti
details
akan memberikan informasi selengkapnya tentang error yang terjadi.
gapi.auth2.ClientConfig
Antarmuka yang merepresentasikan berbagai parameter konfigurasi untuk
metode gapi.auth2.init
.
Parameter | ||
---|---|---|
client_id |
string |
Wajib. Client ID aplikasi, ditemukan dan dibuat di Google Developers Console. |
cookie_policy |
string |
Domain tempat cookie login dibuat. URI,
single_host_origin , atau none . Jika tidak ditentukan, setelan defaultnya adalah single_host_origin . |
scope |
string |
Cakupan yang akan 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 login. Menambahkan 'profil', 'email', dan 'openid' ke cakupan yang diminta. True jika tidak ditentukan. |
hosted_domain |
string |
Domain G Suite tempat pengguna harus masuk. Ini rentan dimodifikasi oleh klien, jadi pastikan untuk memverifikasi properti domain yang dihosting dari pengguna yang ditampilkan. Gunakan GoogleUser.getHostedDomain() pada klien, dan klaim hd dalam Token ID pada server untuk memverifikasi bahwa domain tersebut sesuai dengan harapan Anda.
|
ux_mode |
string |
Mode UX yang akan digunakan untuk alur login. Secara default, tindakan ini akan membuka alur izin dalam jendela pop-up. Nilai yang valid adalah popup dan redirect . |
redirect_uri |
string |
Jika Anda 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 dihapus dari 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 akan berpengaruh pada Client ID OAuth yang dibuat selama atau setelah tahun 2019, karena izin yang lebih terperinci selalu diaktifkan untuk klien tersebut.
|
plugin_name |
string |
Opsional. Jika nilai ini ditetapkan, Client ID baru yang dibuat sebelum 29 Juli 2022 dapat menggunakan Library Google Platform lama.
Secara default, Client ID yang baru dibuat kini diblokir agar tidak menggunakan
Library Platform dan harus menggunakan library Google Identity
Services yang lebih baru. Anda dapat memilih nilai apa pun, sebaiknya gunakan nama deskriptif seperti
nama produk atau plugin agar mudah dikenali.
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 spesifik 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 login, atau false jika pengguna logout atau objek GoogleAuth tidak diinisialisasi.
|
GoogleAuth.isSignedIn.listen(listener)
Memproses perubahan status login pengguna saat ini.
Arguments | |
---|---|
listener |
Fungsi yang mengambil nilai boolean. listen() meneruskan true ke fungsi ini saat pengguna login, dan false saat pengguna logout.
|
GoogleAuth.signIn()
Proses login pengguna 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 kode error di bawah). |
Kode error
Lihat GoogleAuth.signIn(options)
.
GoogleAuth.signIn(options)
Memproses login pengguna menggunakan opsi yang ditentukan.
Arguments | |
---|---|
options |
Atau:
|
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 kode error di bawah). |
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 terjadi saat menggunakan
signIn
dengan opsiprompt: 'none'
. Opsi ini tidak wajib digunakan, karenagapi.auth2.init
akan membuat pengguna login secara otomatis jika sebelumnya login dalam sesi sebelumnya.
gapi.auth2.SignInOptions
Antarmuka yang mewakili parameter konfigurasi yang berbeda untuk
metode GoogleAuth.signIn(options)
.
Parameter | ||
---|---|---|
prompt |
string |
Memaksa mode tertentu untuk alur izin. Opsional. Nilai yang memungkinkan adalah:
|
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 false.
|
ux_mode |
string |
Mode UX yang akan digunakan untuk alur login. Secara default, tindakan ini akan membuka alur izin dalam jendela pop-up. Nilai yang valid adalah popup dan redirect . |
redirect_uri |
string |
Jika Anda 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 dihapus dari parameter kueri dan fragmen hash.
|
GoogleAuth.signOut()
Logout dari akun saat ini dari aplikasi.
Hasil | |
---|---|
Promise | Promise yang dipenuhi saat pengguna logout. |
GoogleAuth.disconnect()
Mencabut semua cakupan yang diberikan pengguna.
GoogleAuth.grantOfflineAccess(options)
Mendapatkan izin dari pengguna untuk mengakses cakupan yang ditentukan secara offline.
Arguments | |
---|---|
options |
Objek gapi.auth2.OfflineAccessOptions
yang berisi key-value pair parameter. Contoh: { scope: 'profile email' } |
Hasil | |
---|---|
Promise | Promise yang dipenuhi 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 untuk cakupan yang diperlukan.
immediate_failed
-
Tidak ada pengguna yang dapat dipilih secara otomatis tanpa meminta alur izin. Error terjadi saat menggunakan
signIn
dengan opsiprompt: 'none'
. Opsi ini tidak wajib digunakan, karenagapi.auth2.init
akan membuat pengguna login secara otomatis jika sebelumnya login dalam sesi sebelumnya.
gapi.auth2.OfflineAccessOptions
Antarmuka yang merepresentasikan parameter konfigurasi yang berbeda untuk
metode
GoogleAuth.grantOfflineAccess(options)
.
Parameter | ||
---|---|---|
prompt |
string |
Memaksa mode tertentu untuk alur izin. Opsional. Nilai yang memungkinkan adalah:
|
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 false.
|
GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)
Melampirkan alur login ke pengendali klik penampung yang ditentukan.
Arguments | |
---|---|
container | ID, atau referensi ke, elemen div tempat
untuk memasang 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 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.
Arguments | |
---|---|
listener |
Fungsi yang menggunakan parameter GoogleUser .
listen meneruskan fungsi ini instance GoogleUser pada setiap perubahan yang mengubah currentUser .
|
GoogleUser.getId()
Dapatkan 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()
Dapatkan domain G Suite pengguna jika ia 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.
Arguments | |
---|---|
includeAuthorizationData | Opsional: Boolean yang menentukan apakah akan selalu menampilkan token akses dan cakupan. Secara default, token akses dan cakupan yang diminta tidak akan ditampilkan jika fetch_basic_profile bernilai 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 dipenuhi 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 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 masa berlaku Token Akses akan berakhir. |
GoogleUser.hasGrantedScopes(scopes)
Menampilkan true (benar) jika pengguna memberikan cakupan yang ditentukan.
Arguments | |
---|---|
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.
Arguments | |
---|---|
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.
Arguments | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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 menetapkan opsi berikut:
|
Lanjutan
gapi.auth2.authorization(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 otomatis, tanpa interaksi pengguna.
Beberapa kasus penggunaan ketika metode ini berguna mencakup:
- Aplikasi Anda hanya perlu meminta endpoint Google API sekali, 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 dalam halaman yang sama.
Arguments | |
---|---|
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 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 yang diperlukan dari Google, misalnya, karena lingkungan tidak didukung. Properti
details
akan memberikan informasi selengkapnya 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 terjadi saat menggunakan
signIn
dengan opsiprompt: 'none'
.
gapi.auth2.AuthorizeConfig
Antarmuka yang mewakili parameter konfigurasi yang berbeda untuk
metode gapi.auth2.authorize
.
Properti | ||
---|---|---|
client_id |
string |
Wajib diisi. Client ID aplikasi, ditemukan dan dibuat di Google Developers Console. |
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 tempat cookie login dibuat. URI,
single_host_origin , atau none . Jika tidak ditentukan, setelan defaultnya adalah single_host_origin .
|
hosted_domain |
string |
Domain G Suite tempat pengguna harus masuk. Hal ini rentan dimodifikasi oleh klien, jadi pastikan untuk memverifikasi properti domain yang dihosting dari pengguna yang ditampilkan. |
login_hint |
string |
Email, atau User-ID, pengguna yang akan dipilih sebelumnya dalam alur login. Hal ini rentan
terhadap modifikasi oleh pengguna, kecuali jika prompt: "none" digunakan.
|
include_granted_scopes |
boolean |
Apakah akan 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 akan berpengaruh pada Client ID OAuth yang dibuat selama atau setelah tahun 2019, karena izin yang lebih terperinci selalu diaktifkan untuk klien tersebut.
|
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 akan diblokir agar tidak dapat menggunakan Library Platform dan harus menggunakan library Google Identity Services yang lebih baru. Anda dapat memilih nilai apa pun, sebaiknya gunakan nama deskriptif seperti nama produk atau plugin agar mudah dikenali.
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 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 di response_type .
|
expires_in |
number |
Jumlah detik hingga Token Akses kedaluwarsa. Hanya ada jika permission
atau token ditentukan di response_type .
|
first_issued_at |
number |
Stempel waktu saat pengguna pertama kali memberikan cakupan yang diminta. Hanya ada jika permission atau token ditentukan di response_type .
|
expires_at |
number |
Stempel waktu masa berlaku Token Akses akan berakhir. Hanya ada jika permission
atau token ditentukan di response_type .
|
error |
string |
Jika permintaan gagal, permintaan ini akan berisi kode error. |
error_subtype |
string |
Jika permintaan gagal, permintaan ini dapat berisi informasi tambahan ke kode error yang juga ditampilkan. |