Referensi klien JavaScript Masuk Google

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

Jika Anda mengalami masalah apa pun saat menggunakan pustaka, laporkan ke repositori GitHub kami.

Penyiapan Auth

Muat pustaka platform Google API untuk membuat objek gapi :

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

Setelah pustaka platform dimuat, muat pustaka 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 Anda menginisialisasi objek GoogleAuth , Anda mengonfigurasi objek dengan ID klien OAuth 2.0 dan opsi tambahan apa pun yang ingin Anda tentukan. Kemudian, jika pengguna sudah masuk, objek GoogleAuth memulihkan status masuk pengguna dari sesi sebelumnya.

Argumen
params Objek yang berisi pasangan nilai-kunci dari data konfigurasi klien. Lihat gapi.auth2.ClientConfig untuk mengetahui properti berbeda yang dapat dikonfigurasi. Misalnya:
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
Kembali
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 kesalahan muncul saat menginisialisasi (ini bisa terjadi di browser lama yang tidak didukung), fungsi onError akan dipanggil sebagai gantinya.

Argumen
onInit Fungsi yang dipanggil dengan objek GoogleAuth saat diinisialisasi sepenuhnya.
onError Fungsi dipanggil dengan objek yang berisi properti error , jika GoogleAuth gagal diinisialisasi.
Kembali
Janji Promise yang terpenuhi ketika fungsi onInit telah selesai, atau ditolak jika kesalahan inisialisasi dimunculkan. Ini menyelesaikan dengan nilai yang dikembalikan dari fungsi onInit , jika ada.

Kode Kesalahan

idpiframe_initialization_failed
Gagal menginisialisasi iframe yang diperlukan dari Google, misalnya, karena lingkungan yang tidak didukung. Properti details akan memberikan lebih banyak informasi tentang kesalahan yang diangkat.

gapi.auth2.ClientConfig

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

Parameter
client_id string Yg dibutuhkan. ID klien aplikasi, ditemukan dan dibuat di Google Developers Console.
cookie_policy string Domain yang akan digunakan untuk membuat cookie masuk. Bisa berupa URI, single_host_origin , atau none . Default-nya ke single_host_origin jika tidak ditentukan.
scope string Cakupan yang akan diminta, sebagai string yang dipisahkan spasi. Opsional jika fetch_basic_profile tidak disetel ke false.
fetch_basic_profile boolean Ambil informasi profil dasar pengguna saat mereka masuk. Tambahkan 'profil', 'email', dan 'openid' ke cakupan yang diminta. Benar jika tidak ditentukan.
hosted_domain string Domain G Suite tempat pengguna harus login. Ini rentan terhadap modifikasi oleh klien, jadi pastikan untuk memverifikasi properti domain yang dihosting dari pengguna yang kembali. Gunakan GoogleUser.getHostedDomain () di klien, dan klaim hd di ID Token di server untuk memverifikasi domain adalah apa yang Anda harapkan.
ux_mode string Mode UX yang akan digunakan untuk alur masuk. Secara default, ini akan membuka aliran persetujuan dalam munculan. Nilai yang valid adalah popup dan redirect .
redirect_uri string Jika menggunakan ux_mode='redirect' , parameter ini memungkinkan Anda untuk mengganti redirect_uri default yang akan digunakan di akhir alur persetujuan. redirect_uri default adalah URL saat ini yang dipisahkan dari parameter kueri dan fragmen hash.

Autentikasi

GoogleAuth adalah kelas tunggal yang menyediakan metode untuk memungkinkan pengguna masuk dengan akun Google, mendapatkan status masuk pengguna saat ini, mendapatkan data spesifik dari profil Google pengguna, meminta cakupan tambahan, dan keluar dari akun saat ini.

gapi.auth2.getAuthInstance ()

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

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

GoogleAuth.isSignedIn.get ()

Menampilkan apakah pengguna saat ini masuk.

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

GoogleAuth.isSignedIn.listen (pendengar)

Dengarkan perubahan dalam status masuk pengguna saat ini.

Argumen
listener Fungsi yang mengambil nilai boolean. listen() meneruskan true ke fungsi ini ketika pengguna masuk, dan false ketika pengguna keluar.

GoogleAuth.signIn ()

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

Kembali
Janji 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 kesalahan

Lihat GoogleAuth.signIn( options ) .

GoogleAuth.signIn ( options )

Masuk pengguna menggunakan opsi yang ditentukan.

Argumen
options Antara:
  • Objek gapi.auth2.SignInOptions berisi pasangan nilai kunci dari parameter masuk. Misalnya:
    {
      scope: 'profile email'
    }
  • Sebuah instance dari gapi.auth2.SigninOptionsBuilder . Misalnya:
    options = new gapi.auth2.SigninOptionsBuilder();
    options.setAppPackageName('com.example.app');
    options.setFetchBasicProfile(True);
    options.setPrompt('select_account');
    options.setScope('profile').setScope('email');
Kembali
Janji 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 kesalahan

popup_closed_by_user
Pengguna menutup munculan sebelum menyelesaikan alur masuk.
access_denied
Pengguna menolak izin untuk cakupan yang diperlukan.
immediate_failed
Tidak ada pengguna yang dapat dipilih secara otomatis tanpa meminta alur persetujuan. Terjadi kesalahan saat menggunakan signIn dengan opsi prompt: 'none' . Opsi ini tidak diperlukan untuk digunakan, karena gapi.auth2.init akan memasukkan pengguna secara otomatis jika sebelumnya masuk pada sesi sebelumnya.

gapi.auth2.SignInOptions

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

Parameter
prompt string Memaksakan mode tertentu untuk aliran persetujuan. Pilihan.
Nilai yang mungkin adalah:
  • consent
    Server otorisasi meminta persetujuan pengguna sebelum mengembalikan informasi ke aplikasi.
  • select_account
    Server otorisasi meminta pengguna untuk memilih akun Google. Ini memungkinkan pengguna yang memiliki beberapa akun untuk memilih di antara beberapa akun yang mungkin mereka miliki sesinya.
  • none ( tidak disarankan )
    Server otorisasi tidak akan menampilkan layar otentikasi atau persetujuan pengguna; itu akan mengembalikan kesalahan jika pengguna belum diautentikasi dan sebelumnya tidak menyetujui cakupan yang diminta.
    Karena gapi.auth2.init akan memasukkan pengguna ke aplikasi secara otomatis jika sebelumnya sudah masuk, memanggil signIn({prompt: 'none'}) biasanya akan gagal.
scope string Cakupan yang akan diminta, sebagai string yang dipisahkan spasi, di atas cakupan yang ditentukan dalam parameter gapi.auth2.init . Opsional jika fetch_basic_profile tidak disetel ke false.
ux_mode string Mode UX yang akan digunakan untuk alur masuk. Secara default, ini akan membuka aliran persetujuan dalam munculan. Nilai yang valid adalah popup dan redirect .
redirect_uri string Jika menggunakan ux_mode='redirect' , parameter ini memungkinkan Anda untuk mengganti redirect_uri default yang akan digunakan di akhir alur persetujuan. redirect_uri default adalah URL saat ini yang dipisahkan dari parameter kueri dan fragmen hash.

GoogleAuth.signOut ()

Keluar dari akun saat ini dari aplikasi.

Kembali
Janji Promise yang dipenuhi ketika pengguna telah keluar.

GoogleAuth.disconnect ()

Mencabut semua cakupan yang diberikan pengguna.

GoogleAuth.grantOfflineAccess ( options )

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

Argumen
options Objek gapi.auth2.OfflineAccessOptions berisi parameter pasangan nilai kunci. Misalnya:
{
  scope: 'profile email'
}
Kembali
Janji Promise yang terpenuhi saat pengguna memberikan cakupan yang diminta, meneruskan objek yang berisi kode otorisasi ke penangan pemenuhan Promise . Misalnya:
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

Kode kesalahan

popup_closed_by_user
Pengguna menutup pop-up sebelum menyelesaikan alur persetujuan.
access_denied
Pengguna menolak izin untuk cakupan yang diperlukan.
immediate_failed
Tidak ada pengguna yang dapat dipilih secara otomatis tanpa meminta alur persetujuan. Terjadi kesalahan saat menggunakan signIn dengan opsi prompt: 'none' . Opsi ini tidak diperlukan untuk digunakan, karena gapi.auth2.init akan memasukkan pengguna secara otomatis jika sebelumnya masuk pada sesi sebelumnya.

gapi.auth2.OfflineAccessOptions

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

Parameter
prompt string Memaksakan mode tertentu untuk aliran persetujuan. Pilihan.
Nilai yang mungkin adalah:
  • consent
    Server otorisasi meminta persetujuan pengguna sebelum mengembalikan informasi ke aplikasi.
  • select_account
    Server otorisasi meminta pengguna untuk memilih akun Google. Ini memungkinkan pengguna yang memiliki beberapa akun untuk memilih di antara beberapa akun yang mungkin mereka miliki sesinya.
scope string Cakupan yang akan diminta, sebagai string yang dipisahkan spasi, di atas cakupan yang ditentukan dalam parameter gapi.auth2.init . Opsional jika fetch_basic_profile tidak disetel ke false.

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

Melampirkan alur masuk ke penangan klik penampung yang ditentukan.

Argumen
container ID dari, atau referensi ke, elemen div yang akan dilampirkan handler klik.
options Objek yang berisi pasangan nilai-kunci parameter. Lihat GoogleAuth.signIn () .
onsuccess Fungsi yang akan dipanggil setelah proses masuk selesai.
onfailure Fungsi untuk memanggil jika masuk gagal.

Pengguna

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

GoogleAuth.currentUser.get ()

Mengembalikan objek GoogleUser yang mewakili pengguna saat ini. Perhatikan bahwa dalam contoh GoogleAuth baru diinisialisasi, pengguna saat ini belum disetel. Gunakan currentUser.listen() metode atau GoogleAuth.then() untuk mendapatkan diinisialisasi GoogleAuth misalnya.

Kembali
GoogleUser Pengguna saat ini

GoogleAuth.currentUser.listen ( listener )

Dengarkan perubahan di currentUser.

Argumen
listener Sebuah fungsi yang mengambil parameter GoogleUser . listen meneruskan fungsi ini instance GoogleUser pada setiap perubahan yang mengubah currentUser .

GoogleUser.getId ()

Dapatkan string ID unik pengguna.

Kembali
Tali ID unik pengguna

GoogleUser.isSignedIn ()

Menampilkan nilai benar jika pengguna masuk.

Kembali
Boolean Benar jika pengguna masuk

GoogleUser.getHostedDomain ()

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

Kembali
Tali Domain G Suite pengguna

GoogleUser.getGrantedScopes ()

Dapatkan cakupan yang diberikan pengguna sebagai string yang dipisahkan spasi.

Kembali
Tali Cakupan yang diberikan oleh pengguna

GoogleUser.getBasicProfile ()

Dapatkan informasi profil dasar pengguna.

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

GoogleUser.getAuthResponse (includeAuthorizationData)

Dapatkan objek respons dari sesi autentikasi pengguna.

Argumen
includeAuthorizationData Opsional: Boolean yang menentukan apakah akan selalu mengembalikan cakupan dan token akses. Secara default, token akses dan cakupan yang diminta tidak dikembalikan jika fetch_basic_profile adalah true (nilai default) dan tidak ada cakupan tambahan yang diminta.
Kembali
gapi.auth2.AuthResponse Objek gapi.auth2.AuthResponse .

GoogleUser.reloadAuthResponse ()

Memaksa penyegaran token akses, lalu mengembalikan Promise untuk AuthResponse baru.

Kembali
Promise Promise yang dipenuhi dengan gapi.auth2.AuthResponse dimuat ulang saat memuat ulang token OAuth selesai.

gapi.auth2.AuthResponse

Tanggapan kembali saat memanggil GoogleUser.getAuthResponse( includeAuthorizationData ) atau GoogleUser.reloadAuthResponse() metode.

Properti
access_token string Access Token diberikan.
id_token string Token ID diberikan.
scope string Cakupan yang diberikan dalam Access Token.
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 di mana Token Akses akan kedaluwarsa.

GoogleUser.hasGrantedScopes ( scopes )

Menampilkan nilai benar jika pengguna memberikan cakupan yang ditentukan.

Argumen
scopes String cakupan yang dipisahkan spasi.
Kembali
Boolean Benar jika cakupannya diberikan

GoogleUser.grant ( options )

Minta cakupan tambahan untuk pengguna.

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

GoogleUser.grantOfflineAccess ( options )

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

Argumen
options Objek gapi.auth2.OfflineAccessOptions berisi parameter pasangan nilai kunci. Misalnya:
{
  scope: 'profile email'
}

GoogleUser.disconnect ()

Mencabut semua cakupan yang diberikan pengguna untuk aplikasi tersebut.

Elemen UI

gapi.signin2.render ( id , options )

Merender tombol masuk di elemen dengan ID yang diberikan, menggunakan pengaturan yang ditentukan oleh objek options .

Argumen
id ID elemen yang akan merender tombol masuk.
options Objek berisi pengaturan 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
cakupan Cakupan yang akan diminta saat pengguna masuk (default: profile ).
lebar Lebar tombol dalam piksel (default: 120 ).
tinggi Tinggi tombol dalam piksel (default: 36 ).
judul panjang Tampilkan label panjang seperti "Masuk dengan Google" daripada "Masuk" (default: false ). Saat Anda menggunakan judul yang panjang, Anda harus menambah lebar tombol dari defaultnya.
tema Tema warna tombol: light atau dark (default: light ).
berhasil Fungsi panggilan balik untuk dipanggil ketika pengguna berhasil masuk. Fungsi ini harus mengambil satu argumen: sebuah contoh dari gapi.auth2.GoogleUser (default: tidak ada).
kegagalan Fungsi panggilan balik untuk dipanggil saat masuk gagal. Fungsi ini tidak membutuhkan argumen (default: tidak ada).

Maju

gapi.auth2.authorize ( params , callback )

Melakukan otorisasi OAuth 2.0 satu kali. Bergantung pada parameter yang digunakan, ini akan membuka munculan ke alur masuk Google atau mencoba memuat respons yang diminta secara diam-diam, tanpa interaksi pengguna.

Beberapa kasus penggunaan di mana metode ini berguna meliputi:

  • Aplikasi Anda hanya perlu meminta titik akhir Google API satu kali, misalnya memuat video YouTube favorit pengguna saat pertama kali masuk.
  • Aplikasi Anda memiliki infrastruktur manajemen sesi sendiri, dan itu hanya membutuhkan Token ID sekali untuk mengidentifikasi pengguna di backend Anda.
  • Beberapa ID Klien digunakan dalam halaman yang sama.
Argumen
params Objek yang berisi pasangan nilai-kunci dari data konfigurasi. Lihat gapi.auth2.AuthorizeConfig untuk properti berbeda yang dapat dikonfigurasi. Misalnya:
{
  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 (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 kesalahan

idpiframe_initialization_failed
Gagal menginisialisasi iframe yang diperlukan dari Google, misalnya, karena lingkungan yang tidak didukung. Properti details akan memberikan lebih banyak informasi tentang kesalahan yang diangkat.
popup_closed_by_user
Pengguna menutup munculan sebelum menyelesaikan alur masuk.
access_denied
Pengguna menolak izin untuk cakupan yang diperlukan.
immediate_failed
Tidak ada pengguna yang dapat dipilih secara otomatis tanpa meminta alur persetujuan. Terjadi kesalahan saat menggunakan signIn dengan opsi prompt: 'none' .

gapi.auth2.AuthorizeConfig

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

Properti
client_id string Wajib . ID klien aplikasi, ditemukan dan dibuat di Google Developers Console.
scope string Wajib . Cakupan yang akan diminta, sebagai string yang dipisahkan spasi.
response_type string Daftar jenis respons yang dipisahkan spasi. Default-nya adalah 'permission' . Nilai yang mungkin adalah:
  • id_token , untuk mengambil Token ID
  • permission (atau token ), untuk mengambil Access Token
  • code , untuk mengambil Kode Otorisasi
prompt string Memaksakan mode tertentu untuk aliran persetujuan. Nilai yang mungkin adalah:
  • consent
    Server otorisasi meminta persetujuan pengguna sebelum mengembalikan informasi ke aplikasi.
  • select_account
    Server otorisasi meminta pengguna untuk memilih akun Google. Ini memungkinkan pengguna yang memiliki beberapa akun untuk memilih di antara beberapa akun yang mungkin mereka miliki sesinya.
  • none
    Server otorisasi tidak akan menampilkan layar otentikasi atau persetujuan pengguna; itu akan mengembalikan kesalahan jika pengguna belum diautentikasi dan sebelumnya tidak menyetujui cakupan yang diminta.
    Jika code diminta sebagai tipe respons, kode yang dikembalikan hanya dapat ditukar dengan access_token , bukan refresh_token .
cookie_policy string Domain yang akan digunakan untuk membuat cookie masuk. Bisa berupa URI, single_host_origin , atau none . Default-nya ke single_host_origin jika tidak ditentukan.
hosted_domain string Domain G Suite tempat pengguna harus login. Ini rentan terhadap modifikasi oleh klien, jadi pastikan untuk memverifikasi properti domain yang dihosting dari pengguna yang kembali.
login_hint string Email, atau ID Pengguna, pengguna yang akan dipilih sebelumnya dalam alur masuk. Ini rentan terhadap modifikasi oleh pengguna, kecuali 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 .

gapi.auth2.AuthorizeResponse

Respons kembali ke callback metode gapi.auth2.authorize .

Properti
access_token string Access Token diberikan. Hanya ada jika permission atau token ditentukan di response_type .
id_token string Token ID diberikan. Hanya ada jika id_token ditentukan di response_type .
code string Kode Otorisasi diberikan. Hanya ada jika code ditentukan di response_type .
scope string Cakupan yang diberikan dalam Access Token. 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 di mana Token Akses akan kedaluwarsa. Hanya ada jika permission atau token ditentukan di response_type .
error string Jika permintaan gagal, ini berisi kode kesalahan .
error_subtype string Ketika permintaan gagal, ini dapat berisi informasi tambahan ke kode kesalahan juga dikembalikan.