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

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

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

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

โหลดไลบรารี Google APIs Platform เพื่อสร้างออบเจ็กต์ 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 (หากมี)

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

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

gapi.auth2.ClientConfig

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

พารามิเตอร์
client_id string จำเป็น รหัสไคลเอ็นต์ของแอป ซึ่งพบและสร้างใน Google Developers Console
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 ในโทเค็นรหัสบนเซิร์ฟเวอร์เพื่อยืนยันว่าโดเมนเป็นไปตามที่คุณคาดไว้
ux_mode string โหมด UX ที่จะใช้ในขั้นตอนการลงชื่อเข้าใช้ ระบบจะเปิดขั้นตอนการขอความยินยอมในป๊อปอัปโดยค่าเริ่มต้น ค่าที่ถูกต้องคือ popup และ redirect
redirect_uri string หากใช้ ux_mode='redirect' พารามิเตอร์นี้ช่วยให้ลบล้าง redirect_uri เริ่มต้นซึ่งจะใช้ในตอนท้ายของกระบวนการขอความยินยอมได้ redirect_uri เริ่มต้นคือ URL ปัจจุบันที่ตัดพารามิเตอร์การค้นหาและส่วนเครื่องหมายแฮชแท็ก
plugin_name string ไม่บังคับ หากมีการตั้งค่านี้ รหัสไคลเอ็นต์ใหม่ที่สร้างขึ้นก่อนวันที่ 29 กรกฎาคม 2022 จะใช้ไลบรารี Google Platform แบบเก่าได้ โดยค่าเริ่มต้น ระบบจะบล็อก Client-ID ที่สร้างขึ้นใหม่ไม่ให้ใช้ไลบรารีแพลตฟอร์ม และต้องใช้ไลบรารีบริการ Google Identity เวอร์ชันใหม่แทน คุณอาจเลือกค่าใดก็ได้ ขอแนะนำให้ใช้ชื่อที่สื่อความหมาย เช่น ชื่อผลิตภัณฑ์หรือปลั๊กอิน เพื่อให้ระบุได้ง่าย เช่น 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 ที่มีการดำเนินการเมื่อผู้ใช้ให้สิทธิ์ขอบเขตที่ขอ โดยส่งออบเจ็กต์ที่มีรหัสการให้สิทธิ์ไปยังเครื่องจัดการ Fulfillment ของ 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)

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

อาร์กิวเมนต์
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()

บังคับรีเฟรชโทเค็นเพื่อการเข้าถึง แล้วจึงส่งคำสัญญาสำหรับ 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)
สำเร็จ ฟังก์ชันเรียกกลับที่จะเรียกใช้เมื่อผู้ใช้ลงชื่อเข้าใช้สำเร็จ ฟังก์ชันนี้ต้องใช้อาร์กิวเมนต์ 1 รายการ ซึ่งเป็นอินสแตนซ์ของ gapi.auth2.GoogleUser (ค่าเริ่มต้น: ไม่มี)
ดำเนินการไม่สำเร็จ ฟังก์ชันเรียกกลับที่จะเรียกใช้เมื่อลงชื่อเข้าใช้ไม่สำเร็จ ฟังก์ชันนี้ไม่ต้องใช้อาร์กิวเมนต์ (ค่าเริ่มต้น: ไม่มี)

ระดับสูง

gapi.auth2.ให้สิทธิ์(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 Developers Console
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 อีเมลหรือ User ID ของผู้ใช้ที่จะเลือกล่วงหน้าในขั้นตอนการลงชื่อเข้าใช้ ซึ่งผู้ใช้อาจแก้ไขได้ เว้นแต่จะใช้ prompt: "none"
include_granted_scopes boolean ต้องการขอโทเค็นเพื่อการเข้าถึงที่รวมขอบเขตทั้งหมดที่ผู้ใช้มอบให้แก่แอปก่อนหน้านี้ หรือเฉพาะขอบเขตที่ขอในการเรียกปัจจุบัน ค่าเริ่มต้นคือ true
plugin_name string ไม่บังคับ หากตั้งค่าไว้ รหัสไคลเอ็นต์ที่สร้างก่อนวันที่ 29 กรกฎาคม 2022 จะใช้ไลบรารี Google Platform ได้ โดยค่าเริ่มต้น รหัสไคลเอ็นต์ที่สร้างขึ้นใหม่จะถูกบล็อกไม่ให้ใช้ไลบรารีแพลตฟอร์ม และต้องใช้ไลบรารี Google Identity Services เวอร์ชันใหม่แทน คุณอาจเลือกค่าใดก็ได้ ขอแนะนำให้ใช้ชื่อที่สื่อความหมาย เช่น ชื่อผลิตภัณฑ์หรือชื่อปลั๊กอิน เพื่อให้ระบุได้ง่าย เช่น 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 เมื่อคำขอล้มเหลว อาจมีข้อมูลเพิ่มเติมเกี่ยวกับรหัสข้อผิดพลาดที่แสดงผลด้วย