การอ้างอิงไคลเอ็นต์ JavaScript ใน Google Sign-In

ข้อมูลอ้างอิงนี้อธิบายวิธีไคลเอ็นต์และแอตทริบิวต์ JavaScript ที่คุณจะใช้เพื่อติดตั้งใช้งาน Google Sign-In ในเว็บแอปพลิเคชัน

หากคุณประสบปัญหาในการใช้ไลบรารี โปรดรายงานไปยังที่เก็บ GitHub ของเรา

การตั้งค่าการตรวจสอบสิทธิ์

โหลดไลบรารีแพลตฟอร์ม Google APIs เพื่อสร้างออบเจ็กต์ gapi ดังนี้

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

หลังจากที่ไลบรารีแพลตฟอร์มโหลดแล้ว ให้โหลดไลบรารี auth2 ดังนี้

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

gapi.auth2.init(params)

เริ่มต้นออบเจ็กต์ GoogleAuth คุณต้องเรียกใช้เมธอดนี้ก่อนเรียกใช้เมธอดของ gapi.auth2.GoogleAuth

เมื่อคุณเริ่มต้นออบเจ็กต์ GoogleAuth คุณจะกำหนดค่าออบเจ็กต์ด้วยรหัสไคลเอ็นต์ OAuth 2.0 และตัวเลือกอื่นๆ ที่ต้องการระบุ จากนั้น หากผู้ใช้ลงชื่อเข้าใช้แล้ว ออบเจ็กต์ GoogleAuth จะคืนค่าสถานะการลงชื่อเข้าใช้ของผู้ใช้จากเซสชันก่อนหน้า

อาร์กิวเมนต์
params ออบเจ็กต์ที่มีคู่คีย์-ค่าของข้อมูลการกำหนดค่าไคลเอ็นต์ โปรดดู gapi.auth2.ClientConfig สำหรับพร็อพเพอร์ตี้ต่างๆ ที่กำหนดค่าได้ ดังตัวอย่างต่อไปนี้ 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
การคืนสินค้า
gapi.auth2.GoogleAuth ออบเจ็กต์ gapi.auth2.GoogleAuth ใช้เมธอด then() เพื่อรับ "สัญญา" ที่ได้รับการแก้ไขเมื่อออบเจ็กต์ gapi.auth2.GoogleAuth เริ่มต้นเสร็จสมบูรณ์

GoogleAuth.then(onInit, onError)

เรียกใช้ฟังก์ชัน onInit เมื่อออบเจ็กต์ GoogleAuth เริ่มต้นโดยสมบูรณ์ หากเกิดข้อผิดพลาดขึ้นขณะเริ่มต้น (ซึ่งอาจเกิดขึ้นได้ในเบราว์เซอร์เวอร์ชันเก่าที่ไม่รองรับ) ระบบจะเรียกใช้ฟังก์ชัน onError แทน

อาร์กิวเมนต์
onInit ฟังก์ชันที่เรียกใช้ด้วยออบเจ็กต์ GoogleAuth เมื่อเริ่มต้นอย่างสมบูรณ์
onError มีการเรียกฟังก์ชันด้วยออบเจ็กต์ที่มีพร็อพเพอร์ตี้ error หากเริ่มต้น GoogleAuth ไม่สำเร็จ
การคืนสินค้า
สัญญา Promise ระบบจะดำเนินการเมื่อฟังก์ชัน onInit เสร็จสมบูรณ์ หรือถูกปฏิเสธหากเกิดข้อผิดพลาดในการเริ่มต้น โดยจะแก้ไขด้วยค่าที่แสดงผลจากฟังก์ชัน onInit หากมี

รหัสข้อผิดพลาด

idpiframe_initialization_failed
เริ่มต้น iframe ที่จำเป็นจาก Google ไม่สำเร็จเนื่องจากสภาพแวดล้อมที่ไม่รองรับ พร็อพเพอร์ตี้ details จะให้ข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดที่เกิดขึ้น

gapi.auth2.ClientConfig

อินเทอร์เฟซที่แสดงพารามิเตอร์การกำหนดค่าต่างๆ สำหรับเมธอด gapi.auth2.init

พารามิเตอร์
client_id string ต้องระบุ รหัสไคลเอ็นต์ของแอปที่พบและสร้างในคอนโซล Google API
cookie_policy string โดเมนที่จะใช้สร้างคุกกี้การลงชื่อเข้าใช้ ซึ่งเป็น URI, single_host_origin หรือ none ค่าเริ่มต้นจะเป็น single_host_origin หากไม่ระบุ
scope string ขอบเขตที่จะส่งคำขอ เป็นสตริงที่คั่นด้วยช่องว่าง ไม่บังคับหาก ไม่ได้ตั้งค่า fetch_basic_profile เป็น "เท็จ"
fetch_basic_profile boolean ดึงข้อมูลโปรไฟล์พื้นฐานของผู้ใช้เมื่อลงชื่อเข้าใช้ เพิ่ม "โปรไฟล์", "อีเมล" และ "openid" ในขอบเขตที่ขอ จริงหากไม่ได้ระบุ
hosted_domain string โดเมน G Suite ที่ผู้ใช้ต้องลงชื่อเข้าใช้ ลูกค้ามีแนวโน้มที่จะแก้ไขได้ ดังนั้นอย่าลืมยืนยันพร็อพเพอร์ตี้โดเมนที่โฮสต์ของผู้ใช้ที่กลับมาด้วย ใช้ GoogleUser.getHostedDomain() ในไคลเอ็นต์ และการอ้างสิทธิ์ hd ในโทเค็นรหัสบนเซิร์ฟเวอร์เพื่อยืนยันโดเมนนั้นเป็นไปตามที่คุณคาดไว้
use_fedcm boolean ไม่บังคับ ค่าเริ่มต้นคือ True เปิดหรือปิดการใช้ FedCM API ของเบราว์เซอร์ระหว่างการลงชื่อเข้าใช้
ux_mode string โหมด UX ที่ใช้สำหรับขั้นตอนการลงชื่อเข้าใช้ โดยค่าเริ่มต้น ระบบจะเปิดขั้นตอนการขอความยินยอมในป๊อปอัป ค่าที่ถูกต้องคือ popup และ redirect
redirect_uri string หากใช้ ux_mode='redirect' พารามิเตอร์นี้จะช่วยให้คุณลบล้าง redirect_uri เริ่มต้นที่จะใช้เมื่อสิ้นสุดขั้นตอนการขอความยินยอมได้ redirect_uri เริ่มต้นคือ URL ปัจจุบันที่ถูกตัดออกจากพารามิเตอร์การค้นหาและส่วนเครื่องหมายแฮชแท็ก
enable_granular_consent boolean ไม่บังคับ เลือกว่าจะเปิดใช้สิทธิ์แบบละเอียดหรือไม่ หากตั้งค่าเป็น false ระบบจะปิดใช้สิทธิ์เข้าถึงบัญชี Google ที่ละเอียดยิ่งขึ้นสำหรับรหัสไคลเอ็นต์ OAuth ที่สร้างก่อนปี 2019 รหัสไคลเอ็นต์ OAuth ที่สร้างขึ้นระหว่างหรือหลังปี 2019 จะไม่มีผล เนื่องจากระบบจะเปิดใช้สิทธิ์ที่ละเอียดยิ่งขึ้นไว้เสมอ
plugin_name string ไม่บังคับ หากตั้งค่านี้ไว้ รหัสไคลเอ็นต์ใหม่ที่สร้างขึ้นก่อนวันที่ 29 กรกฎาคม 2022 จะใช้ไลบรารี Google Platform เวอร์ชันเก่าได้ โดยค่าเริ่มต้น ระบบจะบล็อกรหัสไคลเอ็นต์ที่สร้างขึ้นใหม่ไม่ให้ใช้ไลบรารีของ Platform และต้องใช้ไลบรารีของ Google Identity Services เวอร์ชันใหม่แทน คุณสามารถเลือกค่าใดก็ได้ ขอแนะนำให้ระบุชื่อที่สื่อความหมาย เช่น ชื่อผลิตภัณฑ์หรือชื่อปลั๊กอิน เช่น plugin_name: 'YOUR_STRING_HERE'

การตรวจสอบสิทธิ์

GoogleAuth เป็นคลาส Singleton ที่มีวิธีการอนุญาตให้ผู้ใช้ลงชื่อเข้าใช้ด้วยบัญชี Google, ดูสถานะการลงชื่อเข้าใช้ปัจจุบันของผู้ใช้, ดูข้อมูลที่ต้องการจากโปรไฟล์ Google ของผู้ใช้, ขอขอบเขตเพิ่มเติม และออกจากระบบบัญชีปัจจุบัน

gapi.auth2.getAuthInstance()

แสดงผลออบเจ็กต์ GoogleAuth คุณต้องเริ่มต้นออบเจ็กต์ GoogleAuth ด้วย gapi.auth2.init() ก่อนเรียกใช้เมธอดนี้

การคืนสินค้า
gapi.auth2.GoogleAuth ออบเจ็กต์ gapi.auth2.GoogleAuth ใช้ออบเจ็กต์นี้เพื่อเรียกเมธอดของ gapi.auth2.GoogleAuth

GoogleAuth.isSignedIn.get()

แสดงผลว่าผู้ใช้ปัจจุบันลงชื่อเข้าใช้หรือไม่

การคืนสินค้า
บูลีน true หากผู้ใช้ลงชื่อเข้าใช้ หรือ false หากผู้ใช้ออกจากระบบหรือออบเจ็กต์ GoogleAuth ไม่เริ่มต้น

GoogleAuth.isSignedIn.listen(listener)

ฟังการเปลี่ยนแปลงในสถานะการลงชื่อเข้าใช้ของผู้ใช้ปัจจุบัน

อาร์กิวเมนต์
listener ฟังก์ชันที่ใช้ค่าบูลีน listen() จะส่ง true ไปยังฟังก์ชันนี้เมื่อผู้ใช้ลงชื่อเข้าใช้ และ false เมื่อผู้ใช้ออกจากระบบ

GoogleAuth.signIn()

ลงชื่อเข้าใช้ผู้ใช้ด้วยตัวเลือกที่ระบุไว้ใน gapi.auth2.init()

การคืนสินค้า
สัญญา Promise ที่ได้ดำเนินการด้วยอินสแตนซ์ GoogleUser เมื่อผู้ใช้ตรวจสอบสิทธิ์และระบุขอบเขตที่ขอเรียบร้อยแล้ว หรือปฏิเสธด้วยออบเจ็กต์ที่มีพร็อพเพอร์ตี้ error หากเกิดข้อผิดพลาด ดูรหัสข้อผิดพลาดในส่วนถัดไป

รหัสข้อผิดพลาด

ดูGoogleAuth.signIn(options)

GoogleAuth.signIn(options)

ลงชื่อเข้าใช้ผู้ใช้โดยใช้ตัวเลือกที่ระบุ

อาร์กิวเมนต์
options โดยทำอย่างใดอย่างหนึ่งต่อไปนี้
  • ออบเจ็กต์ gapi.auth2.SignInOptions ที่มีคู่คีย์-ค่าของพารามิเตอร์การลงชื่อเข้าใช้ ตัวอย่างเช่น 
    {
  scope: 'profile email'
}
  • อินสแตนซ์ของ gapi.auth2.SigninOptionsBuilder เช่น
    options = new gapi.auth2.SigninOptionsBuilder();
options.setAppPackageName('com.example.app');
options.setFetchBasicProfile(True);
options.setPrompt('select_account');
options.setScope('profile').setScope('email');
การคืนสินค้า
สัญญา Promise ที่ดำเนินการด้วยอินสแตนซ์ GoogleUser เมื่อผู้ใช้ตรวจสอบสิทธิ์และกำหนดขอบเขตที่ขอสำเร็จแล้ว หรือปฏิเสธด้วยออบเจ็กต์ที่มีพร็อพเพอร์ตี้ error หากเกิดข้อผิดพลาด (ดูรหัสข้อผิดพลาดด้านล่าง)

รหัสข้อผิดพลาด

popup_closed_by_user
ผู้ใช้ปิดป๊อปอัปก่อนทำการลงชื่อเข้าใช้ให้เสร็จสิ้น
access_denied
ผู้ใช้ปฏิเสธสิทธิ์ในขอบเขตที่จำเป็น
immediate_failed
ระบบจะไม่เลือกผู้ใช้โดยอัตโนมัติหากไม่ได้แจ้งขั้นตอนการขอความยินยอม เกิดข้อผิดพลาดเมื่อใช้ signIn กับตัวเลือก prompt: 'none' คุณไม่ควรใช้ตัวเลือกนี้เนื่องจาก gapi.auth2.init จะลงชื่อเข้าใช้ผู้ใช้โดยอัตโนมัติหากลงชื่อเข้าใช้ไว้ก่อนหน้านี้ในเซสชันก่อนหน้า

gapi.auth2.SignInOptions

อินเทอร์เฟซที่แสดงพารามิเตอร์การกำหนดค่าต่างๆ สำหรับเมธอด GoogleAuth.signIn(options)

พารามิเตอร์
prompt string บังคับใช้โหมดเฉพาะเจาะจงสำหรับขั้นตอนการขอความยินยอม ไม่บังคับ
ค่าที่เป็นไปได้มีดังนี้
  • consent
    เซิร์ฟเวอร์การให้สิทธิ์จะแจ้งให้ผู้ใช้ขอความยินยอมก่อนส่งคืนข้อมูลไปยังแอปพลิเคชัน
  • select_account
    เซิร์ฟเวอร์การให้สิทธิ์จะแจ้งให้ผู้ใช้เลือกบัญชี Google วิธีนี้ช่วยให้ผู้ใช้ที่มีหลายบัญชีสามารถเลือกจากหลายบัญชีที่อาจใช้งานเซสชันปัจจุบันได้
  • none (ไม่แนะนำ)
    เซิร์ฟเวอร์การให้สิทธิ์จะไม่แสดงหน้าจอการตรวจสอบสิทธิ์หรือความยินยอมของผู้ใช้ แต่จะแสดงข้อผิดพลาดหากผู้ใช้ยังไม่ได้ตรวจสอบสิทธิ์ และยังไม่ได้ให้ความยินยอมแก่ขอบเขตที่ขอไว้ก่อนหน้านี้
    เนื่องจาก gapi.auth2.init จะลงชื่อเข้าใช้แอปพลิเคชันให้ผู้ใช้โดยอัตโนมัติหากเคยลงชื่อเข้าใช้มาก่อน โดยปกติการเรียกใช้ signIn({prompt: 'none'}) จึงจะไม่สำเร็จ
scope string ขอบเขตที่จะขอเป็นสตริงที่คั่นด้วยช่องว่าง ที่ด้านบนของขอบเขตที่กำหนดไว้ในพารามิเตอร์ gapi.auth2.init ไม่บังคับหากไม่ได้ตั้งค่า fetch_basic_profile เป็น "เท็จ"
ux_mode string โหมด UX ที่ใช้สำหรับขั้นตอนการลงชื่อเข้าใช้ โดยค่าเริ่มต้น ระบบจะเปิดขั้นตอนการขอความยินยอมในป๊อปอัป ค่าที่ถูกต้องคือ popup และ redirect
redirect_uri string หากใช้ ux_mode='redirect' พารามิเตอร์นี้จะช่วยให้คุณลบล้าง redirect_uri เริ่มต้นที่จะใช้เมื่อสิ้นสุดขั้นตอนการขอความยินยอมได้ ค่าเริ่มต้น redirect_uri คือ URL ปัจจุบันที่ถูกตัดออกจากพารามิเตอร์การค้นหาและส่วนแฮช

GoogleAuth.signOut()

ออกจากระบบบัญชีปัจจุบันจากแอปพลิเคชัน

การคืนสินค้า
สัญญา Promise จะมีการดำเนินการเมื่อผู้ใช้ออกจากระบบ

GoogleAuth.disconnect()

เพิกถอนขอบเขตทั้งหมดที่ผู้ใช้ให้สิทธิ์

GoogleAuth.grantOfflineAccess(options)

ขอสิทธิ์จากผู้ใช้เพื่อเข้าถึงขอบเขตที่ระบุแบบออฟไลน์

อาร์กิวเมนต์
options ออบเจ็กต์ gapi.auth2.OfflineAccessOptions ที่มีคู่คีย์-ค่าของพารามิเตอร์ ตัวอย่างเช่น 
{
  scope: 'profile email'
}
การคืนสินค้า
สัญญา Promise ที่จะมีการดำเนินการเมื่อผู้ใช้ให้สิทธิ์ขอบเขตที่ขอ โดยส่งออบเจ็กต์ที่มีรหัสการให้สิทธิ์ไปยังเครื่องจัดการการดำเนินการของ Promise ตัวอย่างเช่น 
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

รหัสข้อผิดพลาด

popup_closed_by_user
ผู้ใช้ปิดป๊อปอัปก่อนทำขั้นตอนการขอความยินยอมให้เสร็จสิ้น
access_denied
ผู้ใช้ปฏิเสธสิทธิ์ในขอบเขตที่จำเป็น
immediate_failed
ระบบจะไม่เลือกผู้ใช้โดยอัตโนมัติหากไม่ได้แจ้งขั้นตอนการขอความยินยอม เกิดข้อผิดพลาดเมื่อใช้ signIn กับตัวเลือก prompt: 'none' คุณไม่ควรใช้ตัวเลือกนี้เนื่องจาก gapi.auth2.init จะลงชื่อเข้าใช้ผู้ใช้โดยอัตโนมัติหากเคยลงชื่อเข้าใช้ก่อนหน้านี้ในเซสชันก่อนหน้า

gapi.auth2.OfflineAccessOptions

อินเทอร์เฟซที่แสดงพารามิเตอร์การกำหนดค่าต่างๆ สำหรับเมธอด GoogleAuth.grantOfflineAccess(options)

พารามิเตอร์
prompt string บังคับใช้โหมดเฉพาะเจาะจงสำหรับขั้นตอนการขอความยินยอม ไม่บังคับ
ค่าที่เป็นไปได้มีดังนี้
  • consent
    เซิร์ฟเวอร์การให้สิทธิ์จะแจ้งให้ผู้ใช้ขอความยินยอมก่อนส่งคืนข้อมูลไปยังแอปพลิเคชัน
  • select_account
    เซิร์ฟเวอร์การให้สิทธิ์จะแจ้งให้ผู้ใช้เลือกบัญชี Google วิธีนี้ช่วยให้ผู้ใช้ที่มีหลายบัญชีสามารถเลือกจากหลายบัญชีที่อาจใช้งานเซสชันปัจจุบันได้
scope string ขอบเขตที่จะขอเป็นสตริงที่คั่นด้วยช่องว่าง ที่ด้านบนของขอบเขตที่กำหนดไว้ในพารามิเตอร์ gapi.auth2.init ไม่บังคับหากไม่ได้ตั้งค่า fetch_basic_profile เป็น "เท็จ"

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

แนบขั้นตอนการลงชื่อเข้าใช้กับ Click Handler ของคอนเทนเนอร์ที่ระบุ

อาร์กิวเมนต์
container รหัสหรือการอ้างอิงองค์ประกอบ div ที่จะแนบเครื่องจัดการคลิก
options ออบเจ็กต์ที่มีคู่คีย์-ค่าของพารามิเตอร์ โปรดดู GoogleAuth.signIn()
onsuccess ฟังก์ชันที่จะเรียกใช้หลังจากการลงชื่อเข้าใช้เสร็จสมบูรณ์
onfailure ฟังก์ชันที่เรียกใช้หากลงชื่อเข้าใช้ไม่สำเร็จ

ผู้ใช้

ออบเจ็กต์ GoogleUser แสดงบัญชีผู้ใช้ 1 บัญชี โดยปกติแล้ว ออบเจ็กต์ GoogleUser จะได้จากการเรียกใช้ GoogleAuth.currentUser.get()

GoogleAuth.currentUser.get()

แสดงผลออบเจ็กต์ GoogleUser ที่แสดงผู้ใช้ปัจจุบัน โปรดทราบว่าในอินสแตนซ์ GoogleAuth ที่เพิ่งเริ่มต้น ยังไม่มีการตั้งค่าผู้ใช้ปัจจุบัน ใช้เมธอด currentUser.listen() หรือ GoogleAuth.then() เพื่อรับอินสแตนซ์ GoogleAuth ที่เริ่มต้นแล้ว

การคืนสินค้า
GoogleUser ผู้ใช้ปัจจุบัน

GoogleAuth.currentUser.listen(listener)

รอดูการเปลี่ยนแปลงใน CurrentUser

อาร์กิวเมนต์
listener ฟังก์ชันที่ใช้พารามิเตอร์ GoogleUser listen จะส่งอินสแตนซ์ GoogleUser ของฟังก์ชันนี้ในทุกการเปลี่ยนแปลงที่แก้ไข currentUser

GoogleUser.getId()

รับสตริงรหัสที่ไม่ซ้ำกันของผู้ใช้

การคืนสินค้า
สตริง รหัสที่ไม่ซ้ำกันของผู้ใช้

GoogleUser.isSignedIn()

แสดงค่า "จริง" หากผู้ใช้ลงชื่อเข้าใช้

การคืนสินค้า
บูลีน จริงหากผู้ใช้ลงชื่อเข้าใช้

GoogleUser.getHostedDomain()

รับโดเมน G Suite ของผู้ใช้หากผู้ใช้ลงชื่อเข้าใช้ด้วยบัญชี G Suite

การคืนสินค้า
สตริง โดเมน G Suite ของผู้ใช้

GoogleUser.getGrantedScopes()

รับขอบเขตที่ผู้ใช้ให้สิทธิ์เป็นสตริงที่คั่นด้วยช่องว่าง

การคืนสินค้า
สตริง ขอบเขตที่ผู้ใช้ให้สิทธิ์

GoogleUser.getBasicProfile()

รับข้อมูลโปรไฟล์พื้นฐานของผู้ใช้

การคืนสินค้า
gapi.auth2.BasicProfile คุณดึงข้อมูลพร็อพเพอร์ตี้ของ gapi.auth2.BasicProfile ได้ด้วยวิธีต่อไปนี้
  • BasicProfile.getId()
  • BasicProfile.getName()
  • BasicProfile.getGivenName()
  • BasicProfile.getFamilyName()
  • BasicProfile.getImageUrl()
  • BasicProfile.getEmail()

GoogleUser.getAuthResponse(includeAuthorizationData)

รับออบเจ็กต์การตอบกลับจากเซสชันการตรวจสอบสิทธิ์ของผู้ใช้

อาร์กิวเมนต์
includeAuthorizationData ไม่บังคับ: บูลีนที่ระบุว่าจะแสดงผลโทเค็นเพื่อการเข้าถึงและขอบเขตเสมอหรือไม่ โดยค่าเริ่มต้น ระบบจะไม่แสดงผลโทเค็นการเข้าถึงและขอบเขตที่ขอเมื่อ fetch_basic_profile เป็นจริง (ค่าเริ่มต้น) และไม่มีคำขอขอบเขตเพิ่มเติม
การคืนสินค้า
gapi.auth2.AuthResponse ออบเจ็กต์ gapi.auth2.AuthResponse

GoogleUser.reloadAuthResponse()

บังคับให้รีเฟรชโทเค็นเพื่อการเข้าถึง แล้วแสดงผล Promise สำหรับ AuthResponse ใหม่

การคืนสินค้า
Promise Promise ซึ่งเติมด้วย gapi.auth2.AuthResponse ที่โหลดซ้ำเมื่อโหลดโทเค็น OAuth ซ้ำเสร็จแล้ว

gapi.auth2.AuthResponse

ระบบแสดงคำตอบเมื่อเรียกใช้เมธอด GoogleUser.getAuthResponse(includeAuthorizationData) หรือ GoogleUser.reloadAuthResponse()

พร็อพเพอร์ตี้
access_token string โทเค็นเพื่อการเข้าถึงได้รับอนุมัติแล้ว
id_token string โทเค็นรหัสที่ได้รับ
scope string ขอบเขตที่ให้สิทธิ์ในโทเค็นเพื่อการเข้าถึง
expires_in number จำนวนวินาทีที่โทเค็นเพื่อการเข้าถึงจะหมดอายุ
first_issued_at number การประทับเวลาที่ผู้ใช้ให้สิทธิ์ขอบเขตที่ขอเป็นครั้งแรก
expires_at number การประทับเวลาที่โทเค็นเพื่อการเข้าถึงจะหมดอายุ

GoogleUser.hasGrantedScopes(scopes)

แสดงผลเป็น "จริง" หากผู้ใช้ให้สิทธิ์ขอบเขตที่ระบุ

อาร์กิวเมนต์
scopes สตริงขอบเขตที่คั่นด้วยช่องว่าง
การคืนสินค้า
บูลีน เป็นจริงหากขอบเขตได้รับสิทธิ์

GoogleUser.grant(options)

ขอขอบเขตเพิ่มเติมสำหรับผู้ใช้

ดูรายการพารามิเตอร์และรหัสข้อผิดพลาดได้ที่ GoogleAuth.signIn()

GoogleUser.grantOfflineAccess(options)

ขอสิทธิ์จากผู้ใช้เพื่อเข้าถึงขอบเขตที่ระบุแบบออฟไลน์

อาร์กิวเมนต์
options ออบเจ็กต์ gapi.auth2.OfflineAccessOptions ที่มีคู่คีย์-ค่าของพารามิเตอร์ ตัวอย่างเช่น 
{
  scope: 'profile email'
}

GoogleUser.disconnect()

เพิกถอนขอบเขตทั้งหมดที่ผู้ใช้อนุญาตสำหรับแอปพลิเคชัน

องค์ประกอบ UI

gapi.signin2.render(id, options)

แสดงผลปุ่มลงชื่อเข้าใช้ในองค์ประกอบที่มีรหัสที่กำหนด โดยใช้การตั้งค่าที่ระบุโดยออบเจ็กต์ options

อาร์กิวเมนต์
id รหัสขององค์ประกอบที่จะแสดงปุ่มลงชื่อเข้าใช้
options ออบเจ็กต์ที่มีการตั้งค่าที่จะใช้ในการแสดงผลปุ่ม ตัวอย่างเช่น 
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
คุณระบุตัวเลือกต่อไปนี้ได้
พารามิเตอร์
ขอบเขต ขอบเขตที่จะขอเมื่อผู้ใช้ลงชื่อเข้าใช้ (ค่าเริ่มต้น: profile)
ความกว้าง ความกว้างของปุ่มในหน่วยพิกเซล (ค่าเริ่มต้น: 120)
ส่วนสูง ความสูงของปุ่มเป็นพิกเซล (ค่าเริ่มต้น: 36)
ชื่อเต็ม แสดงป้ายกำกับแบบยาว เช่น "ลงชื่อเข้าใช้ด้วย Google" แทนที่จะเป็น "ลงชื่อเข้าใช้" (ค่าเริ่มต้น: false) เมื่อใช้ชื่อยาว คุณควรเพิ่มความกว้างของปุ่มจากค่าเริ่มต้น
ธีม [theme] ธีมสีของปุ่ม: light หรือ dark (ค่าเริ่มต้น: light)
ความสำเร็จ ฟังก์ชัน Callback ที่จะเรียกใช้เมื่อผู้ใช้ลงชื่อเข้าใช้สำเร็จ ฟังก์ชันนี้ต้องใช้อาร์กิวเมนต์ 1 รายการ ได้แก่ อินสแตนซ์ของ gapi.auth2.GoogleUser (ค่าเริ่มต้น: ไม่มี)
Onfailure ฟังก์ชัน Callback ที่จะเรียกใช้เมื่อลงชื่อเข้าใช้ไม่สำเร็จ ฟังก์ชันนี้ไม่รับอาร์กิวเมนต์ (ค่าเริ่มต้น: ไม่มี)

ขั้นสูง

gapi.auth2.Authorize(params, callback)

ดำเนินการให้สิทธิ์ OAuth 2.0 แบบครั้งเดียว การดำเนินการนี้จะเปิดป๊อปอัปไปยังขั้นตอนการลงชื่อเข้าใช้ Google หรือพยายามโหลดคำตอบที่ขอโดยไม่มีการโต้ตอบของผู้ใช้ ทั้งนี้ขึ้นอยู่กับพารามิเตอร์ที่ใช้

กรณีการใช้งานบางส่วนที่วิธีนี้เป็นประโยชน์มีดังนี้

  • แอปพลิเคชันของคุณต้องขออุปกรณ์ปลายทาง Google API เพียงครั้งเดียว เช่น เพื่อโหลดวิดีโอ YouTube ที่ผู้ใช้ชื่นชอบเมื่อลงชื่อเข้าใช้ครั้งแรก
  • แอปพลิเคชันของคุณมีโครงสร้างพื้นฐานการจัดการเซสชันของตนเอง และต้องใช้โทเค็นรหัสเพียงครั้งเดียวเพื่อระบุผู้ใช้ในแบ็กเอนด์ของคุณ
  • มีการใช้รหัสไคลเอ็นต์หลายรหัสภายในหน้าเดียวกัน
อาร์กิวเมนต์
params ออบเจ็กต์ที่มีคู่คีย์-ค่าของข้อมูลการกำหนดค่า โปรดดู gapi.auth2.AuthorizeConfig สำหรับพร็อพเพอร์ตี้ต่างๆ ที่กำหนดค่าได้ ดังตัวอย่างต่อไปนี้ 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}
callback ฟังก์ชันที่มีการเรียกด้วยออบเจ็กต์ gapi.auth2.AuthorizeResponse หลังจากที่ดำเนินการตามคำขอเสร็จสมบูรณ์แล้ว (ไม่ว่าจะสำเร็จหรือล้มเหลว)

ตัวอย่าง

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.
});

รหัสข้อผิดพลาด

idpiframe_initialization_failed
ตัวอย่างเช่น เริ่มต้น iframe ที่จำเป็นจาก Google ไม่สำเร็จเนื่องจากสภาพแวดล้อมที่ไม่รองรับ พร็อพเพอร์ตี้ details จะให้ข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดที่เกิดขึ้น
popup_closed_by_user
ผู้ใช้ปิดป๊อปอัปก่อนทำการลงชื่อเข้าใช้ให้เสร็จสิ้น
access_denied
ผู้ใช้ปฏิเสธสิทธิ์ในขอบเขตที่จำเป็น
immediate_failed
ระบบจะไม่เลือกผู้ใช้โดยอัตโนมัติหากไม่ได้แจ้งขั้นตอนการขอความยินยอม เกิดข้อผิดพลาดเมื่อใช้ signIn กับตัวเลือก prompt: 'none'

gapi.auth2.AuthorizeConfig

อินเทอร์เฟซที่แสดงพารามิเตอร์การกำหนดค่าต่างๆ สำหรับเมธอด gapi.auth2.authorize

พร็อพเพอร์ตี้
client_id string ต้องระบุ รหัสไคลเอ็นต์ของแอปที่พบและสร้างในคอนโซล Google API
scope string ต้องระบุ ขอบเขตที่จะส่งคำขอ เป็นสตริงที่คั่นด้วยช่องว่าง
response_type string รายการประเภทการตอบกลับที่คั่นด้วยช่องว่าง ค่าเริ่มต้นคือ 'permission' โดยค่าที่เป็นไปได้มีดังนี้
  • id_token เพื่อเรียกข้อมูลโทเค็นรหัส
  • permission (หรือ token) เพื่อเรียกข้อมูลโทเค็นเพื่อการเข้าถึง
  • code ในการเรียกรหัสการให้สิทธิ์
prompt string บังคับใช้โหมดเฉพาะเจาะจงสำหรับขั้นตอนการขอความยินยอม โดยค่าที่เป็นไปได้มีดังนี้
  • consent
    เซิร์ฟเวอร์การให้สิทธิ์จะแจ้งให้ผู้ใช้ขอความยินยอมก่อนส่งคืนข้อมูลไปยังแอปพลิเคชัน
  • select_account
    เซิร์ฟเวอร์การให้สิทธิ์จะแจ้งให้ผู้ใช้เลือกบัญชี Google วิธีนี้ช่วยให้ผู้ใช้ที่มีหลายบัญชีสามารถเลือกจากหลายบัญชีที่อาจใช้งานเซสชันปัจจุบันได้
  • none
    เซิร์ฟเวอร์การให้สิทธิ์จะไม่แสดงหน้าจอการตรวจสอบสิทธิ์หรือความยินยอมของผู้ใช้ แต่จะแสดงข้อผิดพลาดหากผู้ใช้ยังไม่ได้ตรวจสอบสิทธิ์และยังไม่ได้ให้ความยินยอมแก่ขอบเขตที่ขอไว้ก่อนหน้านี้
    หากมีการขอ code เป็นประเภทการตอบกลับ โค้ดที่แสดงผลจะแลกเปลี่ยนเป็น access_token เท่านั้น ไม่ใช่ refresh_token
cookie_policy string โดเมนที่จะใช้สร้างคุกกี้การลงชื่อเข้าใช้ ซึ่งเป็น URI, single_host_origin หรือ none ค่าเริ่มต้นจะเป็น single_host_origin หากไม่ระบุ
hosted_domain string โดเมน G Suite ที่ผู้ใช้ต้องลงชื่อเข้าใช้ ลูกค้ามีแนวโน้มที่จะแก้ไขได้ ดังนั้นอย่าลืมยืนยันพร็อพเพอร์ตี้โดเมนที่โฮสต์ของผู้ใช้ที่กลับมา
login_hint string อีเมลหรือรหัสผู้ใช้ของผู้ใช้ที่จะเลือกล่วงหน้าในขั้นตอนการลงชื่อเข้าใช้ ผู้ใช้มีแนวโน้มที่จะแก้ไขได้ เว้นแต่จะใช้ prompt: "none"
include_granted_scopes boolean ไม่ว่าจะขอโทเค็นเพื่อการเข้าถึงที่มีขอบเขตทั้งหมดที่ผู้ใช้มอบให้แก่แอปก่อนหน้านี้ หรือขอเฉพาะขอบเขตที่ขอในการเรียกใช้ปัจจุบัน ค่าเริ่มต้นคือ true
enable_granular_consent boolean ไม่บังคับ เลือกว่าจะเปิดใช้สิทธิ์แบบละเอียดหรือไม่ หากตั้งค่าเป็น false ระบบจะปิดใช้สิทธิ์เข้าถึงบัญชี Google ที่ละเอียดยิ่งขึ้นสำหรับรหัสไคลเอ็นต์ OAuth ที่สร้างก่อนปี 2019 รหัสไคลเอ็นต์ OAuth ที่สร้างขึ้นระหว่างหรือหลังปี 2019 จะไม่มีผล เนื่องจากระบบจะเปิดใช้สิทธิ์ที่ละเอียดยิ่งขึ้นไว้เสมอ
plugin_name string ไม่บังคับ หากตั้งค่าไว้ รหัสไคลเอ็นต์ที่สร้างขึ้นก่อนวันที่ 29 กรกฎาคม 2022 จะใช้ไลบรารี Google Platform ได้ โดยค่าเริ่มต้น รหัสไคลเอ็นต์ที่สร้างขึ้นใหม่จะถูกบล็อกไม่ให้ใช้ไลบรารีของ Platform และต้องใช้ไลบรารีบริการข้อมูลประจําตัวของ Google ที่ใหม่กว่าแทน คุณสามารถเลือกค่าใดก็ได้ ขอแนะนำให้ใช้ชื่อที่สื่อความหมาย เช่น ชื่อผลิตภัณฑ์หรือชื่อปลั๊กอิน เพื่อให้ระบุได้ง่าย เช่น plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

การตอบสนองแสดงการติดต่อกลับของเมธอด gapi.auth2.authorize

พร็อพเพอร์ตี้
access_token string โทเค็นเพื่อการเข้าถึงได้รับอนุมัติแล้ว ปรากฏต่อเมื่อมีการระบุ permission หรือ token ใน response_type เท่านั้น
id_token string โทเค็นรหัสที่ได้รับ แสดงเมื่อมีการระบุ id_token ใน response_type เท่านั้น
code string รหัสการให้สิทธิ์ที่ได้รับ แสดงเมื่อมีการระบุ code ใน response_type เท่านั้น
scope string ขอบเขตที่ให้สิทธิ์ในโทเค็นเพื่อการเข้าถึง แสดงเมื่อมีการระบุ permission หรือ token ใน response_type เท่านั้น
expires_in number จำนวนวินาทีที่โทเค็นเพื่อการเข้าถึงจะหมดอายุ แสดงเมื่อมีการระบุ permission หรือ token ใน response_type เท่านั้น
first_issued_at number การประทับเวลาที่ผู้ใช้ให้สิทธิ์ขอบเขตที่ขอเป็นครั้งแรก แสดงเมื่อมีการระบุ permission หรือ token ใน response_type เท่านั้น
expires_at number การประทับเวลาที่โทเค็นเพื่อการเข้าถึงจะหมดอายุ แสดงเมื่อมีการระบุ permission หรือ token ใน response_type เท่านั้น
error string เมื่อคำขอล้มเหลว จะมีรหัสข้อผิดพลาด
error_subtype string เมื่อคำขอล้มเหลว อาจมีข้อมูลเพิ่มเติมเกี่ยวกับรหัสข้อผิดพลาดที่แสดงกลับมาด้วย