การอ้างอิงไคลเอ็นต์ 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() เพื่อรับ Promise ที่แก้ไขเมื่อออบเจ็กต์ gapi.auth2.GoogleAuth เริ่มต้นเสร็จแล้ว

GoogleAuth.then(onInit, onError)

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

อาร์กิวเมนต์
onInit ฟังก์ชันที่เรียกใช้กับออบเจ็กต์ GoogleAuth เมื่อเริ่มต้นขึ้นอย่างสมบูรณ์
onError ฟังก์ชันที่เรียกใช้ด้วยออบเจ็กต์ที่มีพร็อพเพอร์ตี้ error หาก GoogleAuth เริ่มต้นไม่สำเร็จ
การคืนสินค้า
สัญญา Promise ที่ดำเนินการเมื่อฟังก์ชัน onInit เสร็จสมบูรณ์ หรือถูกปฏิเสธหากเกิดข้อผิดพลาดในการเริ่มต้น โดยจะคลายคําว่า "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 ดึงข้อมูลโปรไฟล์พื้นฐานของผู้ใช้เมื่อลงชื่อเข้าใช้ เพิ่ม "profile", "email" และ "openid" ลงในขอบเขตที่ขอ เป็นจริงหากไม่ได้ระบุ
hosted_domain string โดเมน G Suite ที่ผู้ใช้ต้องอยู่ในนั้นจึงจะลงชื่อเข้าใช้ได้ ข้อมูลนี้อาจมีการแก้ไขโดยลูกค้า ดังนั้นโปรดยืนยันพร็อพเพอร์ตี้โดเมนที่โฮสต์ของผู้ใช้ที่กลับมา ใช้ GoogleUser.getHostedDomain() ในไคลเอ็นต์ และการอ้างสิทธิ์ hd ในโทเค็นระบุตัวตนบนเซิร์ฟเวอร์เพื่อยืนยันว่าโดเมนเป็นโดเมนที่คุณต้องการ
use_fedcm boolean ไม่บังคับ ค่าเริ่มต้นคือ True เปิดหรือปิดใช้ API ของ FedCM ในเบราว์เซอร์ระหว่างการลงชื่อเข้าใช้
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 ไม่บังคับ มีผลกับรหัสไคลเอ็นต์ที่สร้างก่อนวันที่ 3 มีนาคม 2025 เท่านั้น ไม่เช่นนั้นจะไม่มีผล ช่วยให้เว็บแอปที่มีอยู่ใช้ไลบรารีแพลตฟอร์ม Google ต่อไปได้ โดยค่าเริ่มต้น ระบบจะบล็อกรหัสไคลเอ็นต์ที่สร้างขึ้นใหม่ไม่ให้ใช้ Platform Library และต้องใช้ไลบรารี 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 params ไม่บังคับหากไม่ได้ตั้งค่า 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 params ไม่บังคับหากไม่ได้ตั้งค่า fetch_basic_profile เป็นเท็จ

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

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

อาร์กิวเมนต์
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)
longtitle แสดงป้ายกำกับแบบยาว เช่น "ลงชื่อเข้าใช้ด้วย Google" แทน "ลงชื่อเข้าใช้" (ค่าเริ่มต้น: false) เมื่อใช้ชื่อแบบยาว คุณควรเพิ่มความกว้างของปุ่มจากค่าเริ่มต้น
ธีม [theme] ธีมสีของปุ่ม: light หรือ dark (ค่าเริ่มต้น: light)
onsuccess ฟังก์ชัน 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 ไม่บังคับ มีผลกับรหัสไคลเอ็นต์ที่สร้างก่อนวันที่ 3 มีนาคม 2025 เท่านั้น ไม่เช่นนั้นจะไม่มีผล ช่วยให้เว็บแอปที่มีอยู่ใช้ไลบรารีแพลตฟอร์ม Google ต่อไปได้ โดยค่าเริ่มต้น ระบบจะบล็อกรหัสไคลเอ็นต์ที่สร้างขึ้นใหม่ไม่ให้ใช้ Platform Library และต้องใช้ไลบรารี Google Identity Services เวอร์ชันใหม่แทน

คุณเลือกค่าใดก็ได้ แต่ขอแนะนำให้ใช้ชื่อที่สื่อความหมาย เช่น ชื่อผลิตภัณฑ์หรือปลั๊กอิน เพื่อระบุ เช่น plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

คำตอบที่แสดงผลใน Callback ของเมธอด 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 เมื่อคำขอไม่สำเร็จ ข้อมูลนี้อาจมีข้อมูลเพิ่มเติมเกี่ยวกับรหัสข้อผิดพลาดที่แสดง