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

หน้าอ้างอิงนี้จะอธิบายถึง 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 ขั้นตอน UX ของปุ่มลงชื่อเข้าใช้ด้วย 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 โปรดดูข้อมูลเพิ่มเติมในตารางต่อไปนี้

ประเภท ต้องระบุ ตัวอย่าง
string ใช่ client_id: "CLIENT_ID.apps.googleusercontent.com"

auto_select

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

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

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

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

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

login_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

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"

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

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

ux_mode

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

ประเภท ต้องระบุ ตัวอย่าง
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 จะถูกนำออกก่อนเรียกใช้การเรียกกลับ

ประเภท ต้องระบุ ตัวอย่าง
function ไม่บังคับ 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 ค่าเริ่มต้นคือ false โปรดดูข้อมูลเพิ่มเติมในหน้าย้ายข้อมูลไปยัง 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>

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

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

วิธีการ
isDisplayMoment() การแจ้งเตือนนี้เป็นการแจ้งเตือนที่แสดงช่วงเวลาหนึ่งใช่ไหม

หมายเหตุ: เมื่อ เปิดใช้ FedCM จะไม่มีการส่งการแจ้งเตือนนี้ โปรดดูข้อมูลเพิ่มเติมในหน้าย้ายข้อมูลไปยัง FedCM
isDisplayed() การแจ้งเตือนนี้เป็นการแจ้งเตือนที่แสดงขึ้นและมี UI ปรากฏอยู่หรือไม่

หมายเหตุ: เมื่อ เปิดใช้ FedCM จะไม่มีการส่งการแจ้งเตือนนี้ โปรดดูข้อมูลเพิ่มเติมในหน้าย้ายข้อมูลไปยัง FedCM
isNotDisplayed() การแจ้งเตือนนี้แสดงขึ้นขณะที่ UI ไม่แสดงใช่ไหม

หมายเหตุ: เมื่อ เปิดใช้ FedCM จะไม่มีการส่งการแจ้งเตือนนี้ โปรดดูข้อมูลเพิ่มเติมในหน้าย้ายข้อมูลไปยัง FedCM
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
หมายเหตุ: เมื่อ เปิดใช้ FedCM ระบบจะไม่รองรับวิธีการนี้ โปรดดูข้อมูลเพิ่มเติมในหน้าย้ายข้อมูลไปยัง FedCM
isSkippedMoment() นี่เป็นการแจ้งเตือนสำหรับช่วงเวลาที่ถูกข้ามใช่ไหม
getSkippedReason()

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

  • auto_cancel
  • user_cancel
  • tap_outside
  • issuing_failed
หมายเหตุ: เมื่อ เปิดใช้ FedCM ระบบจะไม่รองรับวิธีการนี้ โปรดดูข้อมูลเพิ่มเติมในหน้าย้ายข้อมูลไปยัง FedCM
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 ที่ไม่ซ้ำกันทั่วโลก ใช้ ช่อง sub เป็นตัวระบุผู้ใช้เท่านั้นเนื่องจากจะไม่ซ้ำกันในบัญชี Google ทั้งหมดและไม่มีการนำไปใช้ซ้ำ อย่าใช้อีเมลเป็นตัวระบุเนื่องจากบัญชี 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

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

  • ผู้ใช้กดปุ่ม "แตะครั้งเดียว" หรือ "ลงชื่อเข้าใช้ด้วย 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

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

ประเภท ต้องระบุ ตัวอย่าง
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
ข้อความบนปุ่มคือ "ลงชื่อเข้าใช้ด้วย Google"
signup_with
ข้อความบนปุ่มคือ "ลงชื่อสมัครใช้กับ Google"
continue_with
ข้อความบนปุ่มคือ "ดำเนินการต่อโดยใช้ Google"
signin
ข้อความบนปุ่มคือ "ลงชื่อเข้าใช้"

รูปร่าง

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

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

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

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

logo_alignment

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

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

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

logo_alignment
left
จัดชิดซ้ายกับโลโก้ Google
center
จัดกึ่งกลางโลโก้ Google

ความกว้าง

ความกว้างของปุ่มขั้นต่ำในหน่วยพิกเซล ความกว้างสูงสุดคือ 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"

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

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

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

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

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

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

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

สำเร็จ

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

error

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