หน้าอ้างอิงนี้จะอธิบายถึง Sign-In JavaScript API คุณสามารถใช้ API นี้เพื่อแสดงข้อความแจ้งของ One Tap หรือปุ่ม "ลงชื่อเข้าใช้ด้วย Google" ในหน้าเว็บ
วิธีการ: google.accounts.id.initialize
เมธอด google.accounts.id.initialize
จะเริ่มต้นไคลเอ็นต์ฟีเจอร์ลงชื่อเข้าใช้ด้วย Google โดยอิงตามออบเจ็กต์การกำหนดค่า ดูตัวอย่างโค้ดของวิธีการต่อไปนี้
google.accounts.id.initialize(IdConfiguration)
ตัวอย่างโค้ดต่อไปนี้ใช้เมธอด google.accounts.id.initialize
ด้วยฟังก์ชัน onload
<script>
window.onload = function () {
google.accounts.id.initialize({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: handleCredentialResponse
});
google.accounts.id.prompt();
};
</script>
เมธอด google.accounts.id.initialize
จะสร้างอินสแตนซ์ไคลเอ็นต์ของฟีเจอร์ลงชื่อเข้าใช้ด้วย Google ซึ่งโมดูลทั้งหมดในหน้าเว็บเดียวกันจะใช้โดยนัยได้
- คุณต้องเรียกเมธอด
google.accounts.id.initialize
เพียงครั้งเดียวเท่านั้นแม้ว่าจะใช้โมดูลหลายโมดูล (เช่น One Tap, ปุ่มที่ปรับเปลี่ยนในแบบของคุณ, การเพิกถอน ฯลฯ) ในหน้าเว็บเดียวกัน - หากคุณเรียกใช้เมธอด
google.accounts.id.initialize
หลายครั้ง ระบบจะจดจำและใช้เฉพาะการกำหนดค่าในการเรียกครั้งล่าสุดเท่านั้น
คุณจะรีเซ็ตการกำหนดค่าเมื่อใดก็ตามที่เรียกใช้เมธอด google.accounts.id.initialize
และเมธอดที่ตามมาทั้งหมดในหน้าเว็บเดียวกันจะใช้การกำหนดค่าใหม่ทันที
ประเภทข้อมูล: IdConfiguration
ตารางต่อไปนี้แสดงช่องและคำอธิบายของประเภทข้อมูล IdConfiguration
ฟิลด์ | |
---|---|
client_id |
รหัสไคลเอ็นต์ของแอปพลิเคชัน |
auto_select |
เปิดใช้การเลือกอัตโนมัติ |
callback |
ฟังก์ชัน JavaScript ที่จัดการโทเค็นรหัส Google One Tap และ
ปุ่มลงชื่อเข้าใช้ด้วย Google popup โหมด UX ใช้
แอตทริบิวต์นี้ |
login_uri |
URL ปลายทางของการเข้าสู่ระบบ ปุ่ม "ลงชื่อเข้าใช้ด้วย Google"
redirect โหมด UX ใช้แอตทริบิวต์นี้ |
native_callback |
ฟังก์ชัน JavaScript ที่จัดการข้อมูลเข้าสู่ระบบของรหัสผ่าน |
cancel_on_tap_outside |
ยกเลิกข้อความแจ้งหากผู้ใช้คลิกนอกข้อความแจ้ง |
prompt_parent_id |
รหัส DOM ขององค์ประกอบคอนเทนเนอร์ข้อความแจ้งของ One Tap |
nonce |
สตริงแบบสุ่มสำหรับโทเค็นรหัส |
context |
ชื่อและคําในข้อความแจ้งของ One Tap |
state_cookie_domain |
หากจำเป็นต้องเรียกใช้ One Tap ในโดเมนหลักและโดเมนย่อย ให้ส่งโดเมนหลักไปยังช่องนี้เพื่อให้ใช้คุกกี้ที่แชร์รายการเดียว |
ux_mode |
ขั้นตอนสำหรับปุ่ม "ลงชื่อเข้าใช้ด้วย Google" |
allowed_parent_origin |
ต้นทางที่ได้รับอนุญาตให้ฝัง iframe ตัวกลาง แตะครั้งเดียวจะทำงานในโหมด iframe ขั้นกลางหากมีช่องนี้ |
intermediate_iframe_close_callback |
ลบล้างลักษณะการทำงานเริ่มต้นของ iframe ระดับกลางเมื่อผู้ใช้ปิด One Tap ด้วยตนเอง |
itp_support |
เปิดใช้ One Tap UX ที่อัปเกรดแล้วในเบราว์เซอร์ ITP |
login_hint |
ข้ามการเลือกบัญชีด้วยการให้คำแนะนำผู้ใช้ |
hd |
จำกัดการเลือกบัญชีตามโดเมน |
use_fedcm_for_prompt |
อนุญาตให้เบราว์เซอร์ควบคุมข้อความแจ้งให้ลงชื่อเข้าใช้ของผู้ใช้และเป็นสื่อกลางขั้นตอนการลงชื่อเข้าใช้ระหว่างเว็บไซต์ของคุณกับ Google |
client_id
ช่องนี้คือรหัสไคลเอ็นต์ของแอปพลิเคชัน ซึ่งจะพบและสร้างในคอนโซล Google Cloud โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ใช่ | client_id: "CLIENT_ID.apps.googleusercontent.com" |
auto_select
ช่องนี้กำหนดว่าระบบจะส่งคืนโทเค็นรหัสโดยอัตโนมัติโดยไม่มีการโต้ตอบของผู้ใช้หรือไม่ เมื่อมีเซสชันของ Google เพียงเซสชันเดียวที่อนุมัติแอปของคุณมาก่อน ค่าเริ่มต้นคือ false
ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
boolean | ไม่บังคับ | auto_select: true |
Callback
ช่องนี้เป็นฟังก์ชัน JavaScript ที่จัดการโทเค็นรหัสจากข้อความแจ้งของ One Tap หรือหน้าต่างป๊อปอัป คุณต้องระบุแอตทริบิวต์นี้หากใช้ Google
One Tap หรือปุ่ม "ลงชื่อเข้าใช้ด้วย Google" popup
โหมด UX ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
ฟังก์ชัน | จำเป็นสำหรับ One Tap และโหมด UX popup |
callback: handleResponse |
login_uri
แอตทริบิวต์นี้คือ URI ของปลายทางการเข้าสู่ระบบ
ค่าต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสำหรับไคลเอ็นต์ OAuth 2.0 ที่คุณกำหนดค่าไว้ในคอนโซล Google Cloud และต้องเป็นไปตามกฎการตรวจสอบ URI การเปลี่ยนเส้นทาง
ระบบอาจละเว้นแอตทริบิวต์นี้หากหน้าปัจจุบันคือหน้าเข้าสู่ระบบ ซึ่งในกรณีนี้ระบบโพสต์ข้อมูลเข้าสู่ระบบในหน้านี้โดยค่าเริ่มต้น
การตอบกลับข้อมูลเข้าสู่ระบบของโทเค็นรหัสจะโพสต์ไปยังปลายทางการเข้าสู่ระบบเมื่อผู้ใช้คลิกปุ่ม "ลงชื่อเข้าใช้ด้วย Google" และมีการใช้โหมด UX ในการเปลี่ยนเส้นทาง
โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | ไม่บังคับ | ตัวอย่าง |
---|---|---|
URL | ค่าเริ่มต้นคือ URI ของหน้าปัจจุบันหรือค่าที่คุณระบุ ใช้เมื่อตั้งค่า ux_mode: "redirect" เท่านั้น |
login_uri="https://www.example.com/login" |
ปลายทางการเข้าสู่ระบบต้องจัดการคำขอ POST ที่มีคีย์ credential
ที่มีค่าโทเค็นรหัสในส่วนเนื้อหา
ตัวอย่างคำขอที่ส่งไปยังปลายทางการเข้าสู่ระบบของคุณมีดังนี้
POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded
credential=ID_TOKEN
native_callback
ช่องนี้เป็นชื่อของฟังก์ชัน JavaScript ที่จัดการข้อมูลเข้าสู่ระบบของรหัสผ่านที่ได้จากเครื่องมือจัดการข้อมูลเข้าสู่ระบบแบบเนทีฟของเบราว์เซอร์ ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
ฟังก์ชัน | ไม่บังคับ | native_callback: handleResponse |
cancel_on_tap_outside
ช่องนี้กำหนดว่าจะยกเลิกคำขอ One Tap หรือไม่หากผู้ใช้คลิกนอกข้อความแจ้ง ค่าเริ่มต้นคือ true
คุณปิดใช้ได้หากกำหนดค่าเป็น false
โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
boolean | ไม่บังคับ | cancel_on_tap_outside: false |
prompt_parent_id
แอตทริบิวต์นี้กำหนดรหัส DOM ขององค์ประกอบคอนเทนเนอร์ หากไม่ได้ตั้งค่าไว้ ข้อความแจ้ง One Tap จะปรากฏที่มุมขวาบนของหน้าต่าง ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | prompt_parent_id: 'parent_id' |
ค่าที่ได้จากการสุ่ม
ช่องนี้เป็นสตริงแบบสุ่มที่โทเค็นรหัสใช้เพื่อป้องกันการโจมตีด้วยการเล่นซ้ำ โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | nonce: "biaqbm70g23" |
ความยาวของ Nonce จำกัดไว้ที่ขนาด JWT สูงสุดที่สภาพแวดล้อมของคุณรองรับ รวมถึงข้อจำกัดด้านขนาด HTTP ของเบราว์เซอร์และเซิร์ฟเวอร์แต่ละรายการ
บริบท
ช่องนี้จะเปลี่ยนข้อความจากชื่อและข้อความในข้อความแจ้งของ One Tap ดูข้อมูลเพิ่มเติมได้ในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | context: "use" |
ตารางต่อไปนี้แสดงบริบทและคำอธิบายทั้งหมด
บริบท | |
---|---|
signin |
"ลงชื่อเข้าใช้ด้วย Google" |
signup |
"ลงชื่อสมัครใช้ด้วย Google" |
use |
"ใช้กับ Google" |
state_cookie_domain
หากต้องแสดง One Tap ในโดเมนหลักและโดเมนย่อย ให้ส่งโดเมนหลักไปยังช่องนี้เพื่อให้ใช้คุกกี้สถานะที่แชร์รายการเดียว ดูข้อมูลเพิ่มเติมได้ในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | state_cookie_domain: "example.com" |
ux_mode
ใช้ช่องนี้เพื่อตั้งค่าขั้นตอน UX ที่ปุ่ม "ลงชื่อเข้าใช้ด้วย Google" ใช้ ค่าเริ่มต้นคือ popup
แอตทริบิวต์นี้ไม่มีผลต่อ UX ของ One Tap ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | ux_mode: "redirect" |
ตารางต่อไปนี้แสดงโหมด UX ที่ใช้ได้และคําอธิบาย
โหมด UX | |
---|---|
popup |
ดำเนินการขั้นตอนการลงชื่อเข้าใช้ UX ในหน้าต่างป๊อปอัป |
redirect |
ดำเนินการขั้นตอนการลงชื่อเข้าใช้ UX ด้วยการเปลี่ยนเส้นทางทั้งหน้า |
allowed_parent_origin
ต้นทางที่ได้รับอนุญาตให้ฝัง iframe ตัวกลาง แตะครั้งเดียวจะทำงานในโหมด iframe ระดับกลางหากมีช่องนี้อยู่ ดูข้อมูลเพิ่มเติมได้ในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
สตริงหรืออาร์เรย์สตริง | ไม่บังคับ | allowed_parent_origin: "https://example.com" |
ตารางต่อไปนี้แสดงประเภทค่าที่รองรับและคำอธิบาย
ประเภทค่า | ||
---|---|---|
string |
URI โดเมนเดียว | "https://example.com" |
string array |
อาร์เรย์ของ URI โดเมน | ["https://news.example.com", "https://local.example.com"] |
นอกจากนี้ยังรองรับคำนำหน้าที่เป็นไวลด์การ์ดด้วย ตัวอย่างเช่น "https://*.example.com"
จะจับคู่ example.com
และโดเมนย่อยในทุกระดับ (เช่น news.example.com
, login.news.example.com
) สิ่งที่ควรทราบเมื่อใช้ไวลด์การ์ดมีดังนี้
- สตริงรูปแบบไม่สามารถประกอบด้วยได้เฉพาะไวลด์การ์ดและโดเมนระดับบนสุด เช่น
https://.com
และhttps://
.co.uk
ไม่ถูกต้อง ตามที่ระบุไว้ข้างต้น"https://.example.com"
ตรงกับexample.com
และโดเมนย่อย คุณยังใช้อาร์เรย์เพื่อแสดงโดเมน 2 รายการที่ต่างกันได้ด้วย เช่น["https://example1.com", "https://
.example2.com"]
จะตรงกับโดเมนexample1.com
,example2.com
และโดเมนย่อยของexample2.com
- โดเมนไวลด์การ์ดต้องขึ้นต้นด้วยรูปแบบ https:// ที่ปลอดภัย ซึ่งจะทำให้
"*.example.com"
ไม่ถูกต้อง
หากค่าของช่อง allowed_parent_origin
ไม่ถูกต้อง การเริ่มต้นโหมด iframe กลางของ One Tap จะไม่สำเร็จและหยุดทำงาน
intermediate_iframe_close_callback
ลบล้างลักษณะการทำงานเริ่มต้นของ iframe ระดับกลางเมื่อผู้ใช้ปิด One Tap ด้วยตนเองโดยแตะปุ่ม "X" ใน UI ของ One Tap ลักษณะการทำงานเริ่มต้นคือการนำ iframe ตัวกลางออกจาก DOM ทันที
ช่อง intermediate_iframe_close_callback
จะมีผลในโหมด iframe กลางเท่านั้น และจะมีผลกระทบต่อ iframe ตัวกลางเท่านั้น
แทนที่จะเป็น iframe แบบ One Tap UI ของ One Tap จะถูกนำออกก่อนเรียกใช้โค้ดเรียกกลับ
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
ฟังก์ชัน | ไม่บังคับ | intermediate_iframe_close_callback: logBeforeClose |
itp_support
ช่องนี้จะระบุว่าควรเปิดใช้
One Tap UX ที่อัปเกรด
ในเบราว์เซอร์ที่รองรับ Intelligent Tracking Prevention (ITP) หรือไม่ ค่าเริ่มต้นคือ false
ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
boolean | ไม่บังคับ | itp_support: true |
login_hint
หากแอปพลิเคชันของคุณทราบล่วงหน้าว่าควรลงชื่อเข้าใช้ผู้ใช้รายใด แอปพลิเคชันจะให้คำแนะนำการเข้าสู่ระบบแก่ Google ได้ เมื่อทำสำเร็จ ระบบจะข้ามการเลือกบัญชี ค่าที่ยอมรับ ได้แก่ อีเมลหรือค่าในช่องย่อยโทเค็นรหัส
ดูข้อมูลเพิ่มเติมได้ที่ช่อง login_hint ในเอกสารประกอบ OpenID Connect
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
สตริง อีเมล หรือค่าจากช่อง sub ของโทเค็นรหัส |
ไม่บังคับ | login_hint: 'elisa.beckett@gmail.com' |
HD
เมื่อผู้ใช้มีหลายบัญชีและควรลงชื่อเข้าใช้ด้วยบัญชี Workspace เท่านั้น ให้ใช้บัญชีนี้เพื่อให้คำแนะนำชื่อโดเมนแก่ Google เมื่อดำเนินการสำเร็จ บัญชีผู้ใช้ที่แสดงระหว่างการเลือกบัญชีจะถูกจำกัดไว้เฉพาะโดเมนที่ระบุ
ค่าไวลด์การ์ด: *
มอบเฉพาะบัญชี Workspace ให้กับผู้ใช้และยกเว้นบัญชีผู้ใช้ทั่วไป (user@gmail.com) ในระหว่างการเลือกบัญชี
โปรดดูข้อมูลเพิ่มเติมในช่อง hd ในเอกสาร OpenID Connect
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
สตริง ชื่อโดเมนที่สมบูรณ์ในตัวเองหรือ * | ไม่บังคับ | hd: '*' |
use_fedcm_for_prompt
อนุญาตให้เบราว์เซอร์ควบคุมข้อความแจ้งให้ลงชื่อเข้าใช้ของผู้ใช้และเป็นสื่อกลางในขั้นตอนการลงชื่อเข้าใช้ระหว่างเว็บไซต์ของคุณกับ Google ค่าเริ่มต้นคือ "เท็จ" โปรดดูข้อมูลเพิ่มเติมในหน้าย้ายข้อมูลไปยัง FedCM
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
boolean | ไม่บังคับ | use_fedcm_for_prompt: true |
วิธีการ: google.accounts.id.prompt
เมธอด google.accounts.id.prompt
จะแสดงข้อความแจ้งของ One Tap หรือเครื่องมือจัดการข้อมูลเข้าสู่ระบบดั้งเดิมของเบราว์เซอร์หลังจากเรียกใช้เมธอด initialize()
ดูตัวอย่างโค้ดของเมธอดต่อไปนี้
google.accounts.id.prompt(/**
@type{(function(!PromptMomentNotification):void)=} */ momentListener)
โดยปกติแล้ว จะมีการเรียกใช้เมธอด prompt()
เมื่อโหลดหน้าเว็บ เนื่องจากสถานะเซสชันและการตั้งค่าผู้ใช้ในฝั่ง Google ระบบอาจไม่แสดง UI ข้อความแจ้งของ One Tap หากต้องการรับการแจ้งเตือนเกี่ยวกับสถานะ UI สำหรับช่วงเวลาต่างๆ ให้ส่งฟังก์ชันเพื่อรับการแจ้งเตือนสถานะ UI
การแจ้งเตือนจะเริ่มทำงานในสถานการณ์ต่อไปนี้
- ช่วงเวลาที่แสดง: เหตุการณ์นี้จะเกิดขึ้นหลังจากเรียกใช้เมธอด
prompt()
การแจ้งเตือนจะมีค่าบูลีนที่ระบุว่ามีการแสดง UI หรือไม่ ช่วงเวลาที่ถูกข้าม: กรณีนี้จะเกิดขึ้นเมื่อข้อความแจ้งของ One Tap ปิดด้วยการยกเลิกอัตโนมัติ การยกเลิกด้วยตนเอง หรือเมื่อ Google ออกข้อมูลเข้าสู่ระบบไม่สำเร็จ เช่น เมื่อเซสชันที่เลือกได้ออกจากระบบของ Google แล้ว
ในกรณีเหล่านี้ เราขอแนะนำให้คุณไปยังผู้ให้บริการข้อมูลประจำตัวรายต่อไป หากมี
ช่วงเวลาที่ปิด: กรณีนี้จะเกิดขึ้นเมื่อ Google เรียกข้อมูลเข้าสู่ระบบสำเร็จ หรือผู้ใช้ต้องการหยุดขั้นตอนการดึงข้อมูลเข้าสู่ระบบ เช่น เมื่อผู้ใช้เริ่มป้อนชื่อผู้ใช้และรหัสผ่านในกล่องโต้ตอบการเข้าสู่ระบบ คุณจะเรียกใช้เมธอด
google.accounts.id.cancel()
เพื่อปิดข้อความแจ้งของ One Tap และทริกเกอร์ช่วงเวลาที่ปิดได้
ตัวอย่างโค้ดต่อไปนี้จะใช้ช่วงเวลาที่ถูกข้าม
<script>
window.onload = function () {
google.accounts.id.initialize(...);
google.accounts.id.prompt((notification) => {
if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
// continue with another identity provider.
}
});
};
</script>
ประเภทข้อมูล: PromptTimeNotification
ตารางต่อไปนี้แสดงรายการวิธีการและคำอธิบายของประเภทข้อมูล PromptMomentNotification
วิธีการ | |
---|---|
isDisplayMoment() |
การแจ้งเตือนนี้มีไว้เพื่อช่วงเวลาที่แสดงใช่ไหม หมายเหตุ: เมื่อ FedCM เปิดใช้ การแจ้งเตือนนี้จะไม่เริ่มทำงาน โปรดดูข้อมูลเพิ่มเติมในหน้าย้ายข้อมูลไปยัง FedCM |
isDisplayed() |
การแจ้งเตือนนี้เป็นการแจ้งเตือนที่แสดงชั่วขณะและ UI แสดงขึ้นใช่ไหม หมายเหตุ: เมื่อ FedCM เปิดใช้ การแจ้งเตือนนี้จะไม่เริ่มทำงาน โปรดดูข้อมูลเพิ่มเติมในหน้าย้ายข้อมูลไปยัง FedCM |
isNotDisplayed() |
การแจ้งเตือนนี้มีไว้เพื่อช่วงเวลาที่แสดงและ UI ไม่แสดงใช่ไหม หมายเหตุ: เมื่อ FedCM เปิดใช้ การแจ้งเตือนนี้จะไม่เริ่มทำงาน โปรดดูข้อมูลเพิ่มเติมในหน้าย้ายข้อมูลไปยัง FedCM |
getNotDisplayedReason() |
เหตุผลโดยละเอียดที่ UI ไม่แสดง ค่าที่เป็นไปได้มีดังนี้
|
isSkippedMoment() |
นี่เป็นการแจ้งเตือนสำหรับช่วงเวลาที่ถูกข้ามหรือไม่ |
getSkippedReason() |
เหตุผลโดยละเอียดสำหรับช่วงเวลาที่ถูกข้าม ค่าที่เป็นไปได้มีดังนี้
|
isDismissedMoment() |
การแจ้งเตือนนี้เป็นเวลาที่ปิดไปใช่ไหม |
getDismissedReason() |
เหตุผลโดยละเอียดของการปิด ค่าที่เป็นไปได้มีดังนี้
|
getMomentType() |
แสดงผลสตริงสำหรับประเภทช่วงเวลา ค่าที่เป็นไปได้มีดังนี้
|
ประเภทข้อมูล: CredentialResponse
เมื่อเรียกใช้ฟังก์ชัน callback
ระบบจะส่งออบเจ็กต์ CredentialResponse
เป็นพารามิเตอร์ ตารางต่อไปนี้แสดงช่องที่อยู่ในออบเจ็กต์การตอบกลับข้อมูลเข้าสู่ระบบ
ฟิลด์ | |
---|---|
credential |
ช่องนี้คือโทเค็นรหัสที่แสดงผล |
select_by |
ช่องนี้จะกำหนดวิธีการเลือกข้อมูลเข้าสู่ระบบ |
state |
ช่องนี้กำหนดไว้เฉพาะเมื่อผู้ใช้คลิกปุ่ม "ลงชื่อเข้าใช้ด้วย Google" เพื่อลงชื่อเข้าใช้ และมีการระบุแอตทริบิวต์ state ของปุ่มไว้เท่านั้น |
ข้อมูล เข้าสู่ระบบ
ช่องนี้คือโทเค็นรหัสเป็นสตริงเว็บโทเค็น JSON (JWT) ที่เข้ารหัสฐาน 64 (JWT)
เมื่อถอดรหัสแล้ว JWT จะมีลักษณะตามตัวอย่างต่อไปนี้
header { "alg": "RS256", "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature "typ": "JWT" } payload { "iss": "https://accounts.google.com", // The JWT's issuer "nbf": 161803398874, "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID "sub": "3141592653589793238", // The unique ID of the user's Google Account "hd": "gmail.com", // If present, the host domain of the user's GSuite email address "email": "elisa.g.beckett@gmail.com", // The user's email address "email_verified": true, // true, if Google has verified the email address "azp": "314159265-pi.apps.googleusercontent.com", "name": "Elisa Beckett", // If present, a URL to user's profile picture "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler", "given_name": "Elisa", "family_name": "Beckett", "iat": 1596474000, // Unix timestamp of the assertion's creation time "exp": 1596477600, // Unix timestamp of the assertion's expiration time "jti": "abc161803398874def" }
ช่อง sub
เป็นตัวระบุบัญชี Google ที่ไม่ซ้ำกันทั่วโลก เท่านั้น
ให้ใช้ช่อง sub
เป็นตัวระบุสำหรับผู้ใช้ เนื่องจากไม่ซ้ำกันกับบัญชี Google ทั้งหมด
และจะไม่ใช้ซ้ำ อย่าใช้อีเมลเป็นตัวระบุเนื่องจากบัญชี Google หนึ่งบัญชีมีอีเมลหลายรายการได้ในเวลาที่ต่างกัน
การใช้ช่อง email
, email_verified
และ hd
จะช่วยให้คุณระบุได้ว่า Google โฮสต์และมีสิทธิ์สำหรับอีเมลหรือไม่ ในกรณีที่ Google ได้รับอนุญาต ระบบจะยืนยันว่าผู้ใช้เป็นเจ้าของบัญชีที่ถูกต้องตามกฎหมาย
กรณีที่ Google มีอำนาจ
email
มีส่วนต่อท้าย@gmail.com
บัญชีนี้คือบัญชี Gmailemail_verified
เป็นจริงและตั้งค่าhd
แล้ว นี่คือบัญชี Google Workspace
ผู้ใช้สามารถลงทะเบียนบัญชี Google ได้โดยไม่ต้องใช้ Gmail หรือ Google Workspace
เมื่อ email
ไม่มีคำต่อท้าย @gmail.com
และ hd
ไม่มีไว้ Google ถือว่าไม่น่าเชื่อถือ เราขอแนะนำให้ใช้รหัสผ่านหรือวิธีพิสูจน์อื่นๆ เพื่อยืนยันผู้ใช้ หรือ email_verfied
ก็อาจเป็นความจริงเพราะ Google ได้ยืนยันผู้ใช้ในตอนแรกเมื่อสร้างบัญชี Google อย่างไรก็ตาม ความเป็นเจ้าของบัญชีอีเมลของบุคคลที่สามอาจมีการเปลี่ยนแปลงไปแล้ว
ช่อง exp
จะแสดงเวลาหมดอายุเพื่อให้คุณยืนยันโทเค็นในฝั่งเซิร์ฟเวอร์ ซึ่งจะใช้เวลา 1 ชั่วโมง
สำหรับโทเค็นรหัสที่ได้รับจากฟีเจอร์ลงชื่อเข้าใช้ด้วย Google คุณต้องยืนยันโทเค็นก่อนเวลาหมดอายุ อย่าใช้ exp
สำหรับการจัดการเซสชัน โทเค็นรหัสที่หมดอายุไม่ได้หมายความว่าผู้ใช้ออกจากระบบ แอปของคุณมีหน้าที่จัดการ
เซสชันของผู้ใช้
select_by
ตารางต่อไปนี้แสดงค่าที่เป็นไปได้สำหรับช่อง select_by
ประเภทของปุ่มที่ใช้กับเซสชันและสถานะความยินยอมจะใช้เพื่อกำหนดค่า
ผู้ใช้กดปุ่ม "แตะครั้งเดียว" หรือ "ลงชื่อเข้าใช้ด้วย Google" หรือใช้ขั้นตอนการลงชื่อเข้าใช้อัตโนมัติแบบไม่ต้องสัมผัส
พบเซสชันที่มีอยู่ หรือผู้ใช้เลือกและลงชื่อเข้าใช้บัญชี Google เพื่อสร้างเซสชันใหม่
ก่อนแชร์ข้อมูลเข้าสู่ระบบโทเค็นรหัสกับแอป ผู้ใช้ควรทำดังนี้
- กดปุ่ม "ยืนยัน" เพื่อให้ความยินยอมในการแชร์ข้อมูลเข้าสู่ระบบ หรือ
- เคยให้ความยินยอมและใช้ "เลือกบัญชี" เพื่อเลือกบัญชี Google
ค่าของช่องนี้จะตั้งค่าเป็นประเภทใดประเภทหนึ่งต่อไปนี้
ค่า | คำอธิบาย |
---|---|
auto |
การลงชื่อเข้าใช้โดยอัตโนมัติของผู้ใช้ที่มีเซสชันอยู่ซึ่งเคยให้ความยินยอมในการแชร์ข้อมูลเข้าสู่ระบบ มีผลกับเบราว์เซอร์ที่ไม่รองรับ FedCM เท่านั้น |
user |
ผู้ใช้ที่มีเซสชันอยู่แล้วซึ่งได้ให้ความยินยอมก่อนหน้านี้ได้กดปุ่ม "ดำเนินการต่อในชื่อ" ของ One Tap เพื่อแชร์ข้อมูลเข้าสู่ระบบ มีผลกับเบราว์เซอร์ที่ไม่รองรับ FedCM เท่านั้น |
fedcm |
ผู้ใช้กดปุ่ม "ดำเนินการต่อในชื่อ" ด้วย One Tap เพื่อแชร์ข้อมูลเข้าสู่ระบบโดยใช้ FedCM มีผลกับเบราว์เซอร์ที่รองรับ FedCM เท่านั้น |
fedcm_auto |
การลงชื่อเข้าใช้โดยอัตโนมัติของผู้ใช้ที่มีเซสชันอยู่ซึ่งเคยให้ความยินยอมในการแชร์ข้อมูลเข้าสู่ระบบโดยใช้ FedCM One Tap มีผลกับเบราว์เซอร์ที่รองรับ FedCM เท่านั้น |
user_1tap |
ผู้ใช้ที่มีเซสชันอยู่แล้วกดปุ่ม "ดำเนินการต่อในชื่อ" ของ One Tap เพื่อให้ความยินยอมและแชร์ข้อมูลเข้าสู่ระบบ ใช้กับ Chrome v75 ขึ้นไปเท่านั้น |
user_2tap |
ผู้ใช้ที่ไม่มีเซสชันอยู่แล้วกดปุ่ม "ดำเนินการต่อในชื่อ" ของ One Tap เพื่อเลือกบัญชี จากนั้นกดปุ่ม "ยืนยัน" ในหน้าต่างป๊อปอัปเพื่อให้ความยินยอมและแชร์ข้อมูลเข้าสู่ระบบ ใช้กับเบราว์เซอร์ที่ไม่ใช่ Chromium |
btn |
ผู้ใช้ที่มีเซสชันอยู่แล้วซึ่งให้ความยินยอมไว้ก่อนหน้านี้ได้กดปุ่ม "ลงชื่อเข้าใช้ด้วย Google" และเลือกบัญชี Google จาก "เลือกบัญชี" เพื่อแชร์ข้อมูลเข้าสู่ระบบ |
btn_confirm |
ผู้ใช้ที่มีเซสชันอยู่แล้วได้กดปุ่ม "ลงชื่อเข้าใช้ด้วย Google" และกดปุ่ม "ยืนยัน" เพื่อให้ความยินยอมและแชร์ข้อมูลเข้าสู่ระบบ |
btn_add_session |
ผู้ใช้ที่ไม่มีเซสชันอยู่แล้วซึ่งเคยให้ความยินยอมได้กดปุ่ม "ลงชื่อเข้าใช้ด้วย Google" เพื่อเลือกบัญชี Google และแชร์ข้อมูลเข้าสู่ระบบ |
btn_confirm_add_session |
ผู้ใช้ที่ไม่มีเซสชันอยู่กดปุ่ม "ลงชื่อเข้าใช้ด้วย Google" ก่อนเพื่อเลือกบัญชี Google จากนั้นกดปุ่ม "ยืนยัน" เพื่อให้ความยินยอมและแชร์ข้อมูลเข้าสู่ระบบ |
state
ช่องนี้กำหนดไว้เฉพาะเมื่อผู้ใช้คลิกปุ่ม "ลงชื่อเข้าใช้ด้วย Google" เพื่อลงชื่อเข้าใช้ และมีการระบุแอตทริบิวต์ state
ของปุ่มที่คลิกไว้ ค่าของช่องนี้คือค่าเดียวกับที่คุณระบุไว้ในแอตทริบิวต์ state
ของปุ่ม
เนื่องจากปุ่ม "ลงชื่อเข้าใช้ด้วย Google" หลายปุ่มสามารถแสดงผลในหน้าเดียวกัน คุณจึงกำหนดแต่ละปุ่มด้วยสตริงที่ไม่ซ้ำกันได้ ดังนั้น คุณจึงสามารถช่อง state
นี้
เพื่อระบุว่าผู้ใช้คลิกปุ่มใดเพื่อลงชื่อเข้าใช้
เมธอด: google.accounts.id.renderButton
เมธอด google.accounts.id.renderButton
จะแสดงปุ่ม "ลงชื่อเข้าใช้ด้วย Google" ในหน้าเว็บ
ดูตัวอย่างโค้ดของเมธอดต่อไปนี้
google.accounts.id.renderButton(
/** @type{!HTMLElement} */ parent,
/** @type{!GsiButtonConfiguration} */ options
)
ประเภทข้อมูล: GsiButtonConfiguration
ตารางต่อไปนี้แสดงช่องและคำอธิบายของประเภทข้อมูล GsiButtonConfiguration
แอตทริบิวต์ | |
---|---|
type |
ประเภทปุ่ม: ไอคอน หรือปุ่มมาตรฐาน |
theme |
ธีมของปุ่ม เช่น เติมสีน้ำเงินหรือสีดำ |
size |
ขนาดของปุ่ม เช่น ขนาดเล็กหรือใหญ่ |
text |
ข้อความปุ่ม เช่น "ลงชื่อเข้าใช้ด้วย Google" หรือ "ลงชื่อสมัครใช้ด้วย Google" |
shape |
รูปร่างของปุ่ม เช่น สี่เหลี่ยมผืนผ้าหรือวงกลม |
logo_alignment |
การจัดแนวโลโก้ Google: ด้านซ้ายหรือตรงกลาง |
width |
ความกว้างของปุ่ม หน่วยเป็นพิกเซล |
locale |
หากตั้งค่า ระบบจะแสดงภาษาของปุ่ม |
click_listener |
หากตั้งค่าไว้ ระบบจะเรียกใช้ฟังก์ชันนี้เมื่อมีการคลิกปุ่ม "ลงชื่อเข้าใช้ด้วย Google" |
state |
หากตั้งค่าไว้ สตริงนี้จะแสดงผลพร้อมโทเค็นรหัส |
ประเภทแอตทริบิวต์
ส่วนต่อไปนี้มีรายละเอียดเกี่ยวกับแอตทริบิวต์แต่ละประเภทและตัวอย่าง
ประเภท
ประเภทปุ่ม ค่าเริ่มต้นคือ standard
โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ใช่ | type: "icon" |
ตารางต่อไปนี้แสดงประเภทปุ่มและคำอธิบายของปุ่มที่ใช้ได้
ประเภท | |
---|---|
standard |
|
icon |
ธีม [theme]
ธีมของปุ่ม ค่าเริ่มต้นคือ outline
โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | theme: "filled_blue" |
ตารางต่อไปนี้แสดงรายการธีมที่ใช้ได้และคำอธิบาย
ธีม | |
---|---|
outline |
|
filled_blue |
|
filled_black |
ขนาด
ขนาดของปุ่ม ค่าเริ่มต้นคือ large
โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | size: "small" |
ตารางต่อไปนี้แสดงขนาดปุ่มที่ใช้ได้และคำอธิบายปุ่ม
ขนาด | |
---|---|
large |
|
medium |
|
small |
ข้อความ
ข้อความปุ่ม ค่าเริ่มต้นคือ signin_with
ข้อความของปุ่มไอคอนที่มีแอตทริบิวต์ text
จะไม่มีความแตกต่างกัน
ข้อยกเว้นเพียงอย่างเดียวคือเมื่อมีการอ่านข้อความสำหรับการช่วยเหลือพิเศษบนหน้าจอ
โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | text: "signup_with" |
ตารางต่อไปนี้แสดงข้อความของปุ่มและคำอธิบายทั้งหมด
ข้อความ | |
---|---|
signin_with |
|
signup_with |
|
continue_with |
|
signin |
รูปร่าง
รูปร่างของปุ่ม ค่าเริ่มต้นคือ rectangular
ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | shape: "rectangular" |
ตารางต่อไปนี้แสดงรูปร่างของปุ่มที่ใช้ได้และคำอธิบายของปุ่มเหล่านั้น
รูปร่าง | |
---|---|
rectangular |
|
pill |
|
circle |
|
square |
logo_alignment
การวางแนวโลโก้ Google ค่าเริ่มต้นคือ left
แอตทริบิวต์นี้ใช้ได้กับปุ่มประเภท standard
เท่านั้น ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | logo_alignment: "center" |
ตารางต่อไปนี้แสดงการจัดแนวที่มีอยู่และคำอธิบาย
logo_alignment | |
---|---|
left |
|
center |
ความกว้าง
ความกว้างขั้นต่ำของปุ่ม หน่วยเป็นพิกเซล ความกว้างสูงสุดคือ 400 พิกเซล
โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | width: "400" |
ภาษา
ไม่บังคับ แสดงข้อความของปุ่มโดยใช้ภาษาที่ระบุ หากไม่ใช่ค่าเริ่มต้นตามการตั้งค่าบัญชี Google หรือเบราว์เซอร์ของผู้ใช้ เพิ่มพารามิเตอร์ hl
และรหัสภาษาลงในคำสั่ง src เมื่อโหลดไลบรารี เช่น gsi/client?hl=<iso-639-code>
หากไม่ได้ตั้งค่า ระบบจะใช้ภาษาเริ่มต้นของเบราว์เซอร์หรือค่ากำหนดของผู้ใช้เซสชัน Google ดังนั้น ผู้ใช้แต่ละคนจึงอาจเห็นปุ่มที่แปลแล้วคนละเวอร์ชันกันและอาจมีขนาดที่แตกต่างกันไป
โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | locale: "zh_CN" |
click_listener
คุณกำหนดให้เรียกใช้ฟังก์ชัน JavaScript เมื่อมีการคลิกปุ่ม "ลงชื่อเข้าใช้ด้วย Google" ได้โดยใช้แอตทริบิวต์ click_listener
google.accounts.id.renderButton(document.getElementById("signinDiv"), { theme: 'outline', size: 'large', click_listener: onClickHandler }); function onClickHandler(){ console.log("Sign in with Google button clicked...") }
ในตัวอย่างนี้ ข้อความลงชื่อเข้าใช้ด้วย Google ที่มีการคลิกปุ่ม... จะบันทึกไปยังคอนโซลเมื่อมีการคลิกปุ่ม "ลงชื่อเข้าใช้ด้วย Google"
state
(ไม่บังคับ) เนื่องจากระบบแสดงปุ่ม "ลงชื่อเข้าใช้ด้วย Google" หลายปุ่มได้ในหน้าเดียวกัน คุณจึงกำหนดแต่ละปุ่มด้วยสตริงที่ไม่ซ้ำกันได้ สตริงเดียวกันนั้นจะส่งกลับมาพร้อมกับโทเค็นรหัสเพื่อให้คุณระบุปุ่มที่ผู้ใช้คลิกเพื่อลงชื่อเข้าใช้ได้
โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้
ประเภท | จำเป็น | ตัวอย่าง |
---|---|---|
string | ไม่บังคับ | data-state="button 1" |
ประเภทข้อมูล: ข้อมูลเข้าสู่ระบบ
เมื่อเรียกใช้ฟังก์ชัน native_callback
ระบบจะส่งออบเจ็กต์ Credential
เป็นพารามิเตอร์ ตารางต่อไปนี้แสดงช่องที่มีอยู่ในออบเจ็กต์
ฟิลด์ | |
---|---|
id |
ระบุผู้ใช้ |
password |
รหัสผ่าน |
เมธอด: google.accounts.id.disableAutoSelect
เมื่อผู้ใช้ออกจากระบบของเว็บไซต์ คุณจะต้องเรียกใช้เมธอด google.accounts.id.disableAutoSelect
เพื่อบันทึกสถานะในคุกกี้ เพื่อป้องกันการวนซ้ำของ UX ดูข้อมูลโค้ดของเมธอดต่อไปนี้
google.accounts.id.disableAutoSelect()
ตัวอย่างโค้ดต่อไปนี้ใช้เมธอด google.accounts.id.disableAutoSelect
ด้วยฟังก์ชัน onSignout()
<script>
function onSignout() {
google.accounts.id.disableAutoSelect();
}
</script>
เมธอด: google.accounts.id.storeCredential
เมธอดนี้เป็น Wrapper สำหรับเมธอด store()
ของ API เครื่องมือจัดการข้อมูลเข้าสู่ระบบแบบเนทีฟของเบราว์เซอร์ ดังนั้นจึงใช้เก็บข้อมูลรับรองรหัสผ่านได้เท่านั้น ดูตัวอย่างโค้ดของเมธอดต่อไปนี้
google.accounts.id.storeCredential(Credential, callback)
ตัวอย่างโค้ดต่อไปนี้ใช้เมธอด google.accounts.id.storeCredential
ด้วยฟังก์ชัน onSignIn()
<script>
function onSignIn() {
let cred = {id: '...', password: '...'};
google.accounts.id.storeCredential(cred);
}
</script>
วิธีการ: google.accounts.id.cancel
คุณสามารถยกเลิกขั้นตอน One Tap ได้หากนำข้อความแจ้งออกจากDOM ฝ่ายที่เกี่ยวข้อง ระบบจะละเว้นการดำเนินการยกเลิกหากมีการเลือกข้อมูลเข้าสู่ระบบไว้แล้ว ดูตัวอย่างโค้ดของเมธอดต่อไปนี้
google.accounts.id.cancel()
ตัวอย่างโค้ดต่อไปนี้ใช้เมธอด google.accounts.id.cancel()
ด้วยฟังก์ชัน onNextButtonClicked()
<script>
function onNextButtonClicked() {
google.accounts.id.cancel();
showPasswordPage();
}
</script>
โค้ดเรียกกลับการโหลดไลบรารี: onGoogleLibraryLoad
คุณสามารถลงทะเบียนการติดต่อกลับ onGoogleLibraryLoad
ได้ จะได้รับการแจ้งเตือนหลังจากโหลดไลบรารี
ลงชื่อเข้าใช้ด้วย Google JavaScript
window.onGoogleLibraryLoad = () => {
...
};
โค้ดเรียกกลับนี้เป็นเพียงทางลัดสำหรับโค้ดเรียกกลับของ window.onload
ลักษณะการทำงาน
ไม่ได้แตกต่างกัน
ตัวอย่างโค้ดต่อไปนี้ใช้โค้ดเรียกกลับ onGoogleLibraryLoad
<script>
window.onGoogleLibraryLoad = () => {
google.accounts.id.initialize({
...
});
google.accounts.id.prompt();
};
</script>
วิธีการ: google.accounts.id.revoke
เมธอด google.accounts.id.revoke
จะเพิกถอนการให้สิทธิ์ OAuth ที่ใช้เพื่อแชร์โทเค็นรหัสสำหรับผู้ใช้ที่ระบุ ดูข้อมูลโค้ดของเมธอดต่อไปนี้
javascript
google.accounts.id.revoke(login_hint, callback)
พารามิเตอร์ | ประเภท | คำอธิบาย |
---|---|---|
login_hint |
string | อีเมลหรือรหัสที่ไม่ซ้ำกันของบัญชี Google ของผู้ใช้ รหัสคือพร็อพเพอร์ตี้ sub ของเพย์โหลดข้อมูลเข้าสู่ระบบ |
callback |
ฟังก์ชัน | ตัวแฮนเดิล RevocationResponse ที่ไม่บังคับ |
ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้เมธอด revoke
กับรหัส
google.accounts.id.revoke('1618033988749895', done => { console.log(done.error); });
ประเภทข้อมูล: RevocationResponse
เมื่อเรียกใช้ฟังก์ชัน callback
ระบบจะส่งออบเจ็กต์ RevocationResponse
เป็นพารามิเตอร์ ตารางต่อไปนี้แสดงช่องที่อยู่ในออบเจ็กต์ตอบกลับการเพิกถอน
ฟิลด์ | |
---|---|
successful |
ช่องนี้คือค่าที่ส่งกลับมาจากการเรียกใช้เมธอด |
error |
ช่องนี้อาจมีข้อความตอบกลับข้อผิดพลาดโดยละเอียดหรือไม่ก็ได้ |
สำเร็จ
ช่องนี้เป็นค่าบูลีนที่ตั้งค่าเป็น "จริง" หากเรียกใช้วิธีเพิกถอนสำเร็จ หรือ "เท็จ" เมื่อเรียกใช้ไม่สำเร็จ
error
ช่องนี้เป็นค่าสตริงและมีข้อความแสดงข้อผิดพลาดโดยละเอียดหากเรียกใช้วิธีการเพิกถอนไม่สำเร็จ จะไม่มีคำจำกัดความว่าประสบความสำเร็จ