ลงชื่อเข้าใช้ด้วยการอ้างอิง Google JavaScript API

หน้าอ้างอิงนี้จะอธิบายถึง API ของ JavaScript สำหรับการลงชื่อเข้าใช้ คุณสามารถใช้ 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 Developers Console โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง มี client_id: "CLIENT_ID.apps.googleusercontent.com"

เลือกอัตโนมัติ

ช่องนี้กำหนดว่าระบบจะส่งคืนโทเค็นรหัสโดยอัตโนมัติโดยไม่มีการโต้ตอบจากผู้ใช้หรือไม่ เมื่อมีเซสชันของ Google เพียงเซสชันเดียวที่เคยอนุมัติแอปของคุณ ค่าเริ่มต้นคือ false ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
บูลีน ไม่บังคับ auto_select: true

โค้ดเรียกกลับ

ช่องนี้คือฟังก์ชัน JavaScript ที่จัดการโทเค็นรหัสที่ส่งคืนจากพรอมต์ One Tap หรือหน้าต่างป๊อปอัป ต้องระบุแอตทริบิวต์นี้หากใช้ Google One Tap หรือปุ่มลงชื่อเข้าใช้ด้วย Google popup โหมด UX ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
function จำเป็นสำหรับ One Tap และโหมด UX ของ popup callback: handleResponse

เข้าสู่ระบบ_uri

แอตทริบิวต์นี้คือ URI ของปลายทางการเข้าสู่ระบบ

ค่าต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสำหรับไคลเอ็นต์ OAuth 2.0 ซึ่งคุณกำหนดค่าไว้ในคอนโซล API และต้องสอดคล้องกับกฎการตรวจสอบ 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 ที่จัดการข้อมูลเข้าสู่ระบบของรหัสผ่านที่แสดงจากเครื่องมือจัดการข้อมูลเข้าสู่ระบบดั้งเดิมของเบราว์เซอร์ ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
function ไม่บังคับ native_callback: handleResponse

ยกเลิกเมื่อแตะด้านนอก

ช่องนี้จะกำหนดว่าจะยกเลิกคำขอ One Tap หรือไม่หากผู้ใช้คลิกนอกข้อความแจ้ง ค่าเริ่มต้นคือ true คุณปิดใช้ฟีเจอร์นี้ได้หากกำหนดค่าเป็น false โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
บูลีน ไม่บังคับ cancel_on_tap_outside: false

รหัสผู้ปกครองของข้อความแจ้ง

แอตทริบิวต์นี้ตั้งค่ารหัส DOM ขององค์ประกอบคอนเทนเนอร์ หากไม่ได้ตั้งค่าไว้ ข้อความแจ้ง แบบแตะครั้งเดียวจะแสดงขึ้นที่มุมบนขวาของหน้าต่าง ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ prompt_parent_id: 'parent_id'

ค่าที่ได้จากการสุ่ม

ช่องนี้เป็นสตริงแบบสุ่มที่โทเค็นรหัสใช้เพื่อป้องกันการโจมตีซ้ำ โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ nonce: "biaqbm70g23"

ความยาวของ Nonce จะจำกัดอยู่ที่ขนาด JWT สูงสุดซึ่งสภาพแวดล้อมของคุณรองรับ รวมถึงข้อจำกัดด้านขนาด HTTP ของเบราว์เซอร์และเซิร์ฟเวอร์แต่ละรายการ

บริบท

ช่องนี้จะเปลี่ยนข้อความในชื่อและข้อความในข้อความแจ้งของ One Tap โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ context: "use"

ตารางต่อไปนี้แสดงบริบทที่มีอยู่และคำอธิบาย

บริบท
signin "ลงชื่อเข้าใช้ด้วย Google"
signup "ลงชื่อสมัครใช้ด้วย Google"
use "ใช้กับ Google"

หากจำเป็นต้องแสดง One Tap ในโดเมนหลักและโดเมนย่อย ให้ส่งโดเมนหลักไปยังช่องนี้เพื่อให้มีการใช้คุกกี้แบบสถานะที่แชร์รายการเดียว โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ state_cookie_domain: "example.com"

โหมด_ux

ใช้ช่องนี้เพื่อตั้งค่าขั้นตอน UX ที่ปุ่ม "ลงชื่อเข้าใช้ด้วย Google" ใช้ ค่าเริ่มต้นคือ popup แอตทริบิวต์นี้ไม่มีผลกับ One Tap UX ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ ux_mode: "redirect"

ตารางต่อไปนี้แสดงโหมด UX ที่พร้อมใช้งานและคำอธิบาย

โหมด UX
popup ดำเนินการขั้นตอนการลงชื่อเข้าใช้ UX ในหน้าต่างป๊อปอัป
redirect ดำเนินการโฟลว์ UX ลงชื่อเข้าใช้ด้วยการเปลี่ยนเส้นทางแบบเต็มหน้า

ต้นทางที่อนุญาต

ต้นทางที่ได้รับอนุญาตให้ฝัง 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 ไม่ถูกต้อง การเริ่มต้น One Tap ของโหมด iframe ระดับกลางจะล้มเหลวและหยุดทำงาน

รหัสสื่อกลาง iframe_close_callback

ลบล้างลักษณะการทำงานเริ่มต้นของ iframe เมื่อผู้ใช้ปิด "แตะครั้งเดียว" ด้วยตนเองโดยแตะปุ่ม "X" ใน UI ของ One Tap การทำงานเริ่มต้นคือการนำ iframe ตัวกลางออกจาก DOM ทันที

ช่อง intermediate_iframe_close_callback จะมีผลในโหมด iframe กลางเท่านั้น และจะส่งผลกระทบเฉพาะกับ iframe กลางๆ เท่านั้น แทนที่จะเป็น iframe ของ One Tap ระบบจะนำ UI ของ One Tap ออกก่อนที่จะมีการเรียกใช้การเรียกกลับ

ประเภท ต้องระบุ ตัวอย่าง
function ไม่บังคับ intermediate_iframe_close_callback: logBeforeClose

การสนับสนุน_ itp

ช่องนี้กำหนดว่าควรเปิดใช้ One Tap UX ที่อัปเกรดแล้วในเบราว์เซอร์ที่รองรับ Intelligent Tracking Prevention (ITP) หรือไม่ ค่าเริ่มต้นคือ false ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
บูลีน ไม่บังคับ itp_support: true

คำแนะนำการเข้าสู่ระบบ

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

ดูข้อมูลเพิ่มเติมได้ที่ช่อง login_hint ในเอกสารประกอบเกี่ยวกับ OpenID Connect

ประเภท ต้องระบุ ตัวอย่าง
สตริง อีเมลหรือค่าจากช่องโทเค็นรหัส sub ไม่บังคับ login_hint: 'elisa.beckett@gmail.com'

HD

เมื่อผู้ใช้มีหลายบัญชีและควรลงชื่อเข้าใช้ด้วยบัญชี Workspace เท่านั้น ให้ใช้บัญชีนี้เพื่อให้คำแนะนำเกี่ยวกับชื่อโดเมนแก่ Google เมื่อทำสำเร็จ บัญชีผู้ใช้ที่แสดง ในระหว่างการเลือกบัญชีจะถูกจำกัดไว้เฉพาะโดเมนที่ระบุไว้เท่านั้น ค่าไวลด์การ์ด: * เสนอเฉพาะบัญชี Workspace ให้กับผู้ใช้และยกเว้นบัญชีผู้ใช้ทั่วไป (user@gmail.com) ในระหว่างการเลือกบัญชี

โปรดดูข้อมูลเพิ่มเติมในช่อง hd ในเอกสาร OpenID Connect

ประเภท ต้องระบุ ตัวอย่าง
สตริง ชื่อโดเมนที่สมบูรณ์ในตัวเองหรือ * ไม่บังคับ hd: '*'

ใช้ฟีดสำหรับข้อความแจ้ง

อนุญาตให้เบราว์เซอร์ควบคุมข้อความแจ้งให้ลงชื่อเข้าใช้ของผู้ใช้และเป็นสื่อกลางขั้นตอนการลงชื่อเข้าใช้ระหว่างเว็บไซต์ของคุณกับ Google ค่าเริ่มต้นคือ false

ประเภท ต้องระบุ ตัวอย่าง
บูลีน ไม่บังคับ 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() เมื่อโหลดหน้าเว็บ UI ข้อความแจ้งของ One Tap อาจไม่แสดงขึ้นเนื่องจากสถานะเซสชันและการตั้งค่าผู้ใช้ในฝั่ง Google หากต้องการรับการแจ้งเตือนเกี่ยวกับสถานะ 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>

ประเภทข้อมูล: PromptMomentNotification

ตารางต่อไปนี้แสดงรายการวิธีการและคำอธิบายของประเภทข้อมูล PromptMomentNotification

วิธีการ
isDisplayMoment() นี่เป็นการแจ้งเตือนสำหรับช่วงเวลาที่แสดงใช่ไหม
isDisplayed() การแจ้งเตือนนี้เป็นการแจ้งเตือนในช่วงเวลาที่แสดงและ UI แสดงใช่ไหม
isNotDisplayed() การแจ้งเตือนนี้เป็นการแจ้งเตือนในช่วงเวลาที่แสดงและ UI ไม่แสดงใช่ไหม
getNotDisplayedReason()

เหตุผลโดยละเอียดที่ UI ไม่แสดง ค่าที่เป็นไปได้มีดังนี้

  • browser_not_supported
  • invalid_client
  • missing_client_id
  • opt_out_or_no_session
  • secure_http_required
  • suppressed_by_user
  • unregistered_origin
  • unknown_reason
isSkippedMoment() นี่เป็นการแจ้งเตือนสำหรับช่วงเวลาที่มีการข้ามหรือไม่
getSkippedReason()

เหตุผลโดยละเอียดสำหรับช่วงเวลาที่ถูกข้าม ค่าที่เป็นไปได้มีดังนี้

  • auto_cancel
  • user_cancel
  • tap_outside
  • issuing_failed
isDismissedMoment() การแจ้งเตือนนี้เป็นการแจ้งเตือนที่ปิดไปหรือไม่
getDismissedReason()

เหตุผลโดยละเอียดของการปิด ค่าที่เป็นไปได้มีดังนี้

  • credential_returned
  • cancel_called
  • flow_restarted
getMomentType()

แสดงผลสตริงสำหรับประเภทช่วงเวลา ค่าที่เป็นไปได้มีดังนี้

  • display
  • skipped
  • dismissed

ประเภทข้อมูล: CredentialResponse

เมื่อเรียกใช้ฟังก์ชัน callback ระบบจะส่งออบเจ็กต์ CredentialResponse เป็นพารามิเตอร์ ตารางต่อไปนี้แสดงช่องที่อยู่ในออบเจ็กต์การตอบกลับข้อมูลเข้าสู่ระบบ

ฟิลด์
credential ช่องนี้คือโทเค็นรหัสที่แสดงผล
select_by ช่องนี้จะกำหนดวิธีเลือกข้อมูลเข้าสู่ระบบ

ข้อมูล เข้าสู่ระบบ

ช่องนี้คือโทเค็นรหัสเป็นสตริง JSON Web Token (JWT) ที่เข้ารหัสแบบ Base64

เมื่อ ถอดรหัสแล้ว 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

การใช้ช่อง email, email_verified และ hd จะช่วยให้คุณระบุได้ว่า Google โฮสต์และมีสิทธิ์สำหรับอีเมลหรือไม่ ในกรณีที่ Google ให้สิทธิ์ ผู้ใช้ได้รับการยืนยันว่าเป็นเจ้าของบัญชีตัวจริง

กรณีที่ Google เชื่อถือได้

  • email มีส่วนต่อท้าย @gmail.com แล้ว นี่เป็นบัญชี Gmail
  • email_verified เป็นจริงและมีการตั้งค่า hd แล้ว บัญชีนี้เป็นบัญชี Google Workspace

ผู้ใช้จะลงทะเบียนบัญชี Google ได้โดยไม่ต้องใช้ Gmail หรือ Google Workspace เมื่อ email ไม่มีคำต่อท้าย @gmail.com และไม่มี hd Google จะไม่น่าเชื่อถือ ขอแนะนําให้ใช้รหัสผ่านหรือวิธีพิสูจน์อื่นๆ เพื่อยืนยันผู้ใช้ email_verfied อาจเป็นจริงได้เช่นกันเนื่องจาก Google ได้ยืนยันผู้ใช้ในตอนแรกเมื่อบัญชี Google สร้างขึ้น อย่างไรก็ตาม ความเป็นเจ้าของบัญชีอีเมลของบุคคลที่สามอาจมีการเปลี่ยนแปลงตั้งแต่นั้นมา

ช่อง exp จะแสดงเวลาหมดอายุเพื่อให้คุณยืนยันโทเค็นในฝั่งเซิร์ฟเวอร์ ซึ่งจะใช้เวลา 1 ชั่วโมง สำหรับโทเค็นรหัสที่ได้รับจากฟีเจอร์ลงชื่อเข้าใช้ด้วย Google คุณต้องยืนยันโทเค็นก่อนเวลาหมดอายุ อย่าใช้ exp เพื่อจัดการเซสชัน โทเค็นรหัสที่หมดอายุ ไม่ได้หมายความว่าผู้ใช้ออกจากระบบแล้ว แอปของคุณจะรับผิดชอบ การจัดการเซสชันของผู้ใช้

เลือกโดย

ตารางต่อไปนี้แสดงค่าที่เป็นไปได้สำหรับช่อง select_by ระบบจะใช้ประเภทของปุ่มร่วมกับเซสชันและสถานะความยินยอมเพื่อกำหนดมูลค่า

  • ผู้ใช้กดปุ่ม One Tap หรือปุ่มลงชื่อเข้าใช้ด้วย Google หรือใช้ขั้นตอนการลงชื่อเข้าใช้โดยอัตโนมัติแบบไม่ต้องสัมผัส

  • พบเซสชันที่มีอยู่ หรือผู้ใช้เลือกและลงชื่อเข้าใช้บัญชี Google เพื่อสร้างเซสชันใหม่

  • ก่อนแชร์ข้อมูลเข้าสู่ระบบโทเค็นรหัสกับแอป ให้ผู้ใช้ดำเนินการอย่างใดอย่างหนึ่งต่อไปนี้

    • กดปุ่มยืนยันเพื่อให้คำยินยอมในการแชร์ข้อมูลเข้าสู่ระบบ หรือ
    • ได้ให้คำยินยอมไว้ก่อนหน้านี้และใช้ "เลือกบัญชี" เพื่อเลือกบัญชี Google

ค่าของช่องนี้จะกำหนดไว้เป็นประเภทใดประเภทหนึ่งต่อไปนี้

ค่า คำอธิบาย
auto การลงชื่อเข้าใช้โดยอัตโนมัติของผู้ใช้ที่มีเซสชันอยู่ซึ่งเคยให้ความยินยอมในการแชร์ข้อมูลเข้าสู่ระบบ
user ผู้ใช้ที่มีเซสชันอยู่แล้วซึ่งได้ให้ความยินยอม ได้กดปุ่ม "ดำเนินการต่อในชื่อ" ด้วย One Tap เพื่อแชร์ข้อมูลเข้าสู่ระบบ
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 จากนั้นกดปุ่ม "ยืนยัน" เพื่อให้ความยินยอมและแชร์ข้อมูลเข้าสู่ระบบ

เมธอด: google.accounts.id.renderButton

เมธอด google.accounts.id.renderButton จะแสดงปุ่ม "ลงชื่อเข้าใช้ด้วย Google" ในหน้าเว็บ

ดูตัวอย่างโค้ดของเมธอดต่อไปนี้

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

ประเภทข้อมูล: GsiButtonConfiguration

ตารางต่อไปนี้แสดงช่องและคำอธิบายของข้อมูล GsiButtonConfiguration ประเภท

แอตทริบิวต์
type ประเภทปุ่ม: ไอคอน หรือปุ่มมาตรฐาน
theme ธีมของปุ่ม เช่น fill_blue หรือ filled_black
size ขนาดของปุ่ม เช่น ขนาดเล็กหรือใหญ่
text ข้อความปุ่ม เช่น "ลงชื่อเข้าใช้ด้วย Google" หรือ "ลงชื่อสมัครใช้ด้วย Google"
shape รูปร่างของปุ่ม เช่น สี่เหลี่ยมผืนผ้าหรือวงกลม
logo_alignment การจัดแนวโลโก้ Google: ด้านซ้ายหรือตรงกลาง
width ความกว้างของปุ่มในหน่วยพิกเซล
locale หากตั้งค่าไว้ จะแสดงภาษาของปุ่ม
click_listener หากตั้งค่าไว้ ระบบจะเรียกใช้ฟังก์ชันนี้เมื่อมีการคลิกปุ่ม "ลงชื่อเข้าใช้ด้วย Google"

ประเภทแอตทริบิวต์

ส่วนต่อไปนี้มีรายละเอียดเกี่ยวกับประเภทแอตทริบิวต์แต่ละรายการและตัวอย่าง

ประเภท

ประเภทของปุ่ม ค่าเริ่มต้นคือ standard

โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง มี type: "icon"

ตารางต่อไปนี้แสดงประเภทปุ่มที่ใช้ได้และคำอธิบาย

ประเภท
standard
ปุ่มที่มีข้อความหรือข้อมูลที่ปรับเปลี่ยนในแบบของคุณ
icon
ปุ่มไอคอนที่ไม่มีข้อความ

ธีม [theme]

ธีมของปุ่ม ค่าเริ่มต้นคือ outline โปรดดูข้อมูลเพิ่มเติมได้ในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ theme: "filled_blue"

ตารางต่อไปนี้แสดงรายการธีมที่ใช้ได้และคำอธิบาย

ธีม
outline
ธีมปุ่มมาตรฐาน
filled_blue
ธีมปุ่มที่มีสีน้ำเงิน
filled_black
ธีมปุ่มสีดำ

ขนาด

ขนาดของปุ่ม ค่าเริ่มต้นคือ large โปรดดูข้อมูลเพิ่มเติมได้ในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ size: "small"

ตารางต่อไปนี้แสดงขนาดปุ่มที่ใช้ได้และคำอธิบาย

ขนาด
large
ปุ่มมาตรฐานขนาดใหญ่ ปุ่มไอคอนขนาดใหญ่ ปุ่มขนาดใหญ่ที่ปรับเปลี่ยนในแบบของคุณ
ปุ่มขนาดใหญ่
medium
ปุ่มมาตรฐานปานกลาง ปุ่มไอคอนขนาดกลาง
ปุ่มขนาดกลาง
small
ปุ่มขนาดเล็ก ปุ่มไอคอนขนาดเล็ก
ปุ่มขนาดเล็ก

ข้อความ

ข้อความปุ่ม ค่าเริ่มต้นคือ signin_with ข้อความของปุ่มไอคอนที่มีแอตทริบิวต์ text ต่างกันไม่มีความแตกต่างกัน ข้อยกเว้นเพียงอย่างเดียวคือเมื่อมีการอ่านข้อความสำหรับการช่วยเหลือพิเศษบนหน้าจอ

โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ text: "signup_with"

ตารางต่อไปนี้แสดงข้อความของปุ่มที่ใช้ได้และคําอธิบาย

ข้อความ
signin_with
ข้อความบนปุ่มคือ "ลงชื่อเข้าใช้ด้วย Google"
signup_with
ข้อความบนปุ่มคือ "ลงชื่อสมัครใช้ด้วย Google"
continue_with
ข้อความบนปุ่มคือ "ดำเนินการต่อโดยใช้ Google"
signin
ข้อความบนปุ่มคือ "ลงชื่อเข้าใช้"

รูปร่าง

รูปร่างของปุ่ม ค่าเริ่มต้นคือ rectangular ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ shape: "rectangular"

ตารางต่อไปนี้แสดงรูปร่างของปุ่มที่ใช้ได้และคำอธิบาย

รูปร่าง
rectangular
ปุ่มรูปสี่เหลี่ยมผืนผ้า หากใช้สำหรับประเภทปุ่ม icon ปุ่มนั้นจะมีค่าเหมือนกับ square
pill
ปุ่มรูปยา หากใช้สำหรับประเภทปุ่ม icon ปุ่มนั้นจะมีค่าเหมือนกับ circle
circle
ปุ่มรูปวงกลม หากใช้สำหรับประเภทปุ่ม standard ปุ่มนั้นจะมีค่าเหมือนกับ pill
square
ปุ่มรูปสี่เหลี่ยมจัตุรัส หากใช้สำหรับประเภทปุ่ม standard ปุ่มนั้นจะมีค่าเหมือนกับ rectangular

การปรับแนวโลโก้

การวางแนวโลโก้ Google ค่าเริ่มต้นคือ left แอตทริบิวต์นี้ใช้ได้กับปุ่มประเภท standard เท่านั้น ดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ logo_alignment: "center"

ตารางต่อไปนี้แสดงการวางแนวที่ใช้งานได้และคําอธิบาย

การปรับแนวโลโก้
left
ปรับแนวโลโก้ Google ชิดซ้าย
center
จัดกึ่งกลางโลโก้ Google

ความกว้าง

ความกว้างของปุ่มขั้นต่ำในหน่วยพิกเซล ความกว้างสูงสุดคือ 400 พิกเซล

โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ width: "400"

ภาษา

ไม่บังคับ แสดงข้อความของปุ่มโดยใช้ภาษาที่ระบุ หรือกำหนดค่าเริ่มต้นเป็นการตั้งค่าบัญชี Google หรือเบราว์เซอร์ของผู้ใช้ เพิ่มพารามิเตอร์ hl และรหัสภาษาลงในคำสั่ง src เมื่อโหลดไลบรารี เช่น gsi/client?hl=<iso-639-code>

หากไม่ได้ตั้งค่า ระบบจะใช้ภาษาเริ่มต้นของเบราว์เซอร์หรือค่ากำหนดของผู้ใช้เซสชัน Google ดังนั้น ผู้ใช้กลุ่มต่างๆ อาจเห็นปุ่มที่แปลแล้ว ในเวอร์ชันที่ต่างกัน และอาจแสดงขนาดต่างกันด้วย

โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
สตริง ไม่บังคับ locale: "zh_CN"

โปรแกรมฟังการคลิก

คุณกำหนดให้เรียกใช้ฟังก์ชัน 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"

ประเภทข้อมูล: ข้อมูลเข้าสู่ระบบ

เมื่อมีการเรียกใช้ฟังก์ชัน 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 ได้ ระบบจะแจ้งให้คุณทราบหลังจาก โหลดไลบรารี JavaScript ของ "ลงชื่อเข้าใช้ด้วย Google"

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 สตริง อีเมลหรือรหัสที่ไม่ซ้ำกันของบัญชี Google ของผู้ใช้ รหัสคือพร็อพเพอร์ตี้ sub ของเพย์โหลดข้อมูลเข้าสู่ระบบ
callback function เครื่องจัดการ RevocationResponse ที่ไม่บังคับ

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้เมธอด revoke กับรหัส 

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

ประเภทข้อมูล: RevocationResponse

เมื่อเรียกใช้ฟังก์ชัน callback ระบบจะส่งออบเจ็กต์ RevocationResponse เป็นพารามิเตอร์ ตารางต่อไปนี้แสดงช่องที่อยู่ในออบเจ็กต์การตอบกลับการเพิกถอน

ฟิลด์
successful ช่องนี้คือค่าที่ส่งกลับจากการเรียกใช้เมธอด
error ช่องนี้จะมีข้อความตอบกลับข้อผิดพลาดโดยละเอียดหรือไม่ก็ได้

สำเร็จ

ช่องนี้เป็นค่าบูลีนที่ตั้งค่าเป็น "จริง" หากเรียกใช้เมธอดการเพิกถอนสำเร็จ หรือเป็นเท็จเมื่อล้มเหลว

error

ช่องนี้เป็นค่าสตริงและมีข้อความแสดงข้อผิดพลาดโดยละเอียดหากการเรียกใช้วิธีการเพิกถอนล้มเหลว จะไม่มีการระบุสถานะว่าสำเร็จ