การอ้างอิงไคลเอ็นต์ JavaScript สําหรับ Google Sign-In

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

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

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

โหลดไลบรารีแพลตฟอร์ม Google API เพื่อสร้างออบเจ็กต์ 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 ดึงข้อมูลโปรไฟล์พื้นฐานของผู้ใช้เมื่อลงชื่อเข้าใช้ เพิ่ม "โปรไฟล์" "อีเมล" และ "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 รุ่นเก่าได้ โดยค่าเริ่มต้น ระบบจะบล็อกรหัสไคลเอ็นต์ที่สร้างใหม่ไม่ให้ใช้คลังแพลตฟอร์มและต้องใช้ไลบรารีบริการข้อมูลประจําตัวของ Google เวอร์ชันใหม่แทน คุณอาจเลือกค่าใดก็ได้ ขอแนะนําให้ใช้ชื่อที่สื่อความหมาย เช่น ชื่อผลิตภัณฑ์หรือปลั๊กอินเพื่อให้ระบุได้ง่าย เช่น plugin_name: 'YOUR_STRING_HERE'

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

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

gapi.auth2.getAuthInstance()

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

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

GoogleAuth.isSignIn.get()

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

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

GoogleAuth.isSignedIn.listen(ผู้ฟัง)

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

อาร์กิวเมนต์
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.grantแบบออฟไลน์เข้าถึง(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)

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

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

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

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

GoogleUser.getHostedDomain()

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

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

GoogleUser.getGrantedScopes()

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

การคืนสินค้า
สตริง ขอบเขตที่กําหนดโดยผู้ใช้

GoogleUser.getBasicProfile()

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

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

GoogleUser.getAuthResponse(รวมการให้สิทธิ์ข้อมูล)

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

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

ระดับสูง

gapi.auth2.authorized(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 Required ระบบพบรหัสไคลเอ็นต์ของแอปและสร้างใน Google Developers Console
scope string Required ขอบเขตที่ขอเป็นสตริงที่คั่นด้วยช่องว่าง
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
plugin_name string ไม่บังคับ หากตั้งค่า รหัสไคลเอ็นต์ที่สร้างก่อนวันที่ 29 กรกฎาคม 2022 จะใช้ไลบรารีของ Google 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 เมื่อคําขอล้มเหลว อาจมีข้อมูลเพิ่มเติมเกี่ยวกับรหัสข้อผิดพลาดที่แสดงผลด้วย