การอ้างอิงไคลเอ็นต์ 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 แสดงผล (หากมี)

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

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 แบบเก่าได้ โดยค่าเริ่มต้น ระบบจะบล็อกรหัสไคลเอ็นต์ที่สร้างใหม่ไม่ให้ใช้ไลบรารีแพลตฟอร์ม และต้องใช้ไลบรารีบริการ 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 ฟังก์ชันที่ใช้ค่าบูลีน 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.Authorize(params, callback)

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

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

  • แอปพลิเคชันของคุณต้องขอปลายทาง Google API เพียงครั้งเดียวเท่านั้น เช่น เพื่อโหลดวิดีโอ YouTube ที่ผู้ใช้ชื่นชอบเมื่อลงชื่อเข้าใช้เป็นครั้งแรก
  • แอปพลิเคชันของคุณมีโครงสร้างพื้นฐานการจัดการเซสชันของตัวเอง และต้องใช้โทเค็นรหัสเพียงครั้งเดียวเพื่อระบุผู้ใช้ในแบ็กเอนด์ของคุณ
  • มีการใช้ Client-ID หลายรายการภายในหน้าเดียวกัน
อาร์กิวเมนต์
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 ไม่บังคับ หากมีการตั้งค่า Client-ID ที่สร้างขึ้นก่อนวันที่ 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 เมื่อคำขอล้มเหลว อาจมีข้อมูลเพิ่มเติมของรหัสข้อผิดพลาดที่ส่งกลับมาด้วย