chrome.identity

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

ใช้ chrome.identity API เพื่อรับโทเค็นเพื่อการเข้าถึง OAuth2

สิทธิ์

identity

ประเภท

AccountInfo

พร็อพเพอร์ตี้

• id

  สตริง

  ตัวระบุที่ไม่ซ้ำกันสำหรับบัญชี รหัสนี้จะไม่เปลี่ยนแปลงตลอดอายุการใช้งานของบัญชี

AccountStatus

Chrome 84 ขึ้นไป

ค่าแจกแจง

"SYNC"
ระบุว่าเปิดใช้การซิงค์สำหรับบัญชีหลัก

"ANY"
ระบุการมีอยู่ของบัญชีหลัก (หากมี)

GetAuthTokenResult

Chrome 105 ขึ้นไป

พร็อพเพอร์ตี้

• grantedScopes

  string[] ไม่บังคับ

  รายการขอบเขต OAuth2 ที่ให้สิทธิ์แก่ส่วนขยาย

• โทเค็น

  สตริง ไม่บังคับ

  โทเค็นเฉพาะที่เชื่อมโยงกับคำขอ

InvalidTokenDetails

พร็อพเพอร์ตี้

• โทเค็น

  สตริง

  โทเค็นที่เฉพาะเจาะจงที่ควรนำออกจากแคช

ProfileDetails

Chrome 84 ขึ้นไป

พร็อพเพอร์ตี้

• accountStatus

  AccountStatus ไม่บังคับ

  สถานะของบัญชีหลักที่ลงชื่อเข้าใช้โปรไฟล์ที่ควรแสดง ProfileUserInfo ค่าเริ่มต้นคือสถานะบัญชี SYNC

ProfileUserInfo

พร็อพเพอร์ตี้

• อีเมล

  สตริง

  อีเมลสำหรับบัญชีผู้ใช้ที่ลงชื่อเข้าใช้โปรไฟล์ปัจจุบัน ว่างเปล่าหากผู้ใช้ไม่ได้ลงชื่อเข้าใช้หรือไม่ได้ระบุสิทธิ์ไฟล์ Manifest identity.email

• id

  สตริง

  ตัวระบุที่ไม่ซ้ำกันสำหรับบัญชี รหัสนี้จะไม่เปลี่ยนแปลงตลอดอายุการใช้งานของบัญชี ว่างเปล่าหากผู้ใช้ไม่ได้ลงชื่อเข้าใช้หรือ (ใน M41+) ไม่ได้ระบุสิทธิ์ไฟล์ Manifest identity.email

TokenDetails

พร็อพเพอร์ตี้

• บัญชี

  AccountInfo ไม่บังคับ

  รหัสบัญชีที่ควรแสดงผลโทเค็น หากไม่ได้ระบุไว้ ฟังก์ชันจะใช้บัญชีจากโปรไฟล์ Chrome ซึ่งก็คือบัญชีการซิงค์ (หากมี) หรือบัญชีเว็บ Google บัญชีแรก

• enableGranularPermissions

  บูลีน ไม่บังคับ

  Chrome 87 ขึ้นไป

  แฟล็ก enableGranularPermissions ช่วยให้ส่วนขยายเลือกใช้หน้าจอขอความยินยอมสำหรับสิทธิ์แบบละเอียดได้ตั้งแต่เนิ่นๆ ซึ่งจะมีการให้หรือปฏิเสธสิทธิ์ที่ขอเป็นรายรายการ

• อินเทอร์แอกทีฟ

  บูลีน ไม่บังคับ

  การดึงข้อมูลโทเค็นอาจกำหนดให้ผู้ใช้ลงชื่อเข้าใช้ Chrome หรืออนุมัติขอบเขตที่แอปพลิเคชันขอ หากแฟล็กแบบอินเทอร์แอกทีฟเป็น true getAuthToken จะแจ้งผู้ใช้ตามความจำเป็น เมื่อแฟล็กเป็น false หรือถูกละเว้น getAuthToken จะแสดงผลเป็นไม่สำเร็จทุกครั้งที่ต้องใช้ข้อความแจ้ง

• ขอบเขต

  string[] ไม่บังคับ

  รายการขอบเขต OAuth2 ที่จะขอ

  เมื่อมีช่อง scopes ระบบจะลบล้างรายการขอบเขตที่ระบุใน manifest.json

WebAuthFlowDetails

พร็อพเพอร์ตี้

• abortOnLoadForNonInteractive

  บูลีน ไม่บังคับ

  Chrome 113 ขึ้นไป

  เลือกว่าจะสิ้นสุด launchWebAuthFlow สำหรับคำขอที่ไม่มีการโต้ตอบหลังจากโหลดหน้าเว็บหรือไม่ พารามิเตอร์นี้ไม่มีผลต่อขั้นตอนแบบอินเทอร์แอกทีฟ

  เมื่อตั้งค่าเป็น true (ค่าเริ่มต้น) โฟลว์จะสิ้นสุดทันทีหลังจากโหลดหน้าเว็บ เมื่อตั้งค่าเป็น false โฟลว์จะสิ้นสุดหลังจากผ่านไป timeoutMsForNonInteractive เท่านั้น ซึ่งจะเป็นประโยชน์สำหรับผู้ให้บริการข้อมูลประจำตัวที่ใช้ JavaScript เพื่อทำการเปลี่ยนเส้นทางหลังจากโหลดหน้าเว็บ

• อินเทอร์แอกทีฟ

  บูลีน ไม่บังคับ

  เลือกว่าจะเปิดขั้นตอนการตรวจสอบสิทธิ์ในโหมดอินเทอร์แอกทีฟหรือไม่

  เนื่องจากขั้นตอนการตรวจสอบสิทธิ์บางขั้นตอนอาจเปลี่ยนเส้นทางไปยัง URL ผลลัพธ์ทันที launchWebAuthFlow จึงซ่อน WebView ไว้จนกว่าการนําทางครั้งแรกจะเปลี่ยนเส้นทางไปยัง URL สุดท้าย หรือโหลดหน้าเว็บที่ต้องการแสดงเสร็จสิ้น

  หากแฟล็ก interactive เป็น true หน้าต่างจะแสดงขึ้นเมื่อการโหลดหน้าเว็บเสร็จสมบูรณ์ หากแฟล็กเป็น false หรือถูกละเว้น launchWebAuthFlow จะแสดงผลพร้อมข้อผิดพลาดหากการนําทางเริ่มต้นไม่เสร็จสมบูรณ์

  สำหรับขั้นตอนที่ใช้ JavaScript ในการเปลี่ยนเส้นทาง คุณสามารถตั้งค่า abortOnLoadForNonInteractive เป็น false ร่วมกับการตั้งค่า timeoutMsForNonInteractive เพื่อให้หน้าเว็บมีโอกาสทำการเปลี่ยนเส้นทางได้

• timeoutMsForNonInteractive

  number ไม่บังคับ

  Chrome 113 ขึ้นไป

  ระยะเวลาสูงสุด (เป็นมิลลิวินาที) ที่อนุญาตให้ launchWebAuthFlow ทำงานในโหมดที่ไม่มีการโต้ตอบทั้งหมด จะมีผลก็ต่อเมื่อ interactive เป็น false เท่านั้น

• URL

  สตริง

  URL ที่เริ่มต้นขั้นตอนการตรวจสอบสิทธิ์

เมธอด

clearAllCachedAuthTokens()

Promise Chrome 87 ขึ้นไป

chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
): Promise<void>

รีเซ็ตสถานะของ Identity API:

• นำโทเค็นเพื่อการเข้าถึง OAuth2 ทั้งหมดออกจากแคชโทเค็น
• นำการตั้งค่าบัญชีของผู้ใช้ออก
• ยกเลิกการให้สิทธิ์ผู้ใช้จากขั้นตอนการให้สิทธิ์ทั้งหมด

พารามิเตอร์

• callback

  function ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  () => void

การคืนสินค้า

• Promise<void>

  Chrome 106 ขึ้นไป

  แสดงผล Promise ซึ่งจะได้รับการแก้ไขเมื่อล้างสถานะแล้ว

  ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getAccounts()

Promise เวอร์ชันที่กำลังพัฒนา

chrome.identity.getAccounts(
  callback?: function,
): Promise<AccountInfo[]>

ดึงข้อมูลรายการออบเจ็กต์ AccountInfo ที่อธิบายบัญชีที่มีอยู่ในโปรไฟล์

getAccounts รองรับเฉพาะในเวอร์ชันที่กำลังพัฒนาเท่านั้น

พารามิเตอร์

• callback

  function ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (accounts: AccountInfo[]) => void

  • บัญชี

    AccountInfo[]

การคืนสินค้า

• Promise<AccountInfo[]>

  ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getAuthToken()

Promise

chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
): Promise<GetAuthTokenResult>

รับโทเค็นเพื่อการเข้าถึง OAuth2 โดยใช้รหัสไคลเอ็นต์และขอบเขตที่ระบุไว้ในส่วน oauth2 ของ manifest.json

Identity API จะแคชโทเค็นเพื่อการเข้าถึงไว้ในหน่วยความจำ ดังนั้นคุณจึงเรียกใช้ getAuthToken แบบไม่โต้ตอบได้ทุกเมื่อที่ต้องการโทเค็น แคชโทเค็นจะจัดการการหมดอายุโดยอัตโนมัติ

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

หมายเหตุ: เมื่อเรียกใช้ด้วย Callback ฟังก์ชันนี้จะแสดงผลพร็อพเพอร์ตี้ 2 รายการเป็นอาร์กิวเมนต์แยกต่างหากที่ส่งไปยัง Callback แทนที่จะแสดงผลออบเจ็กต์

พารามิเตอร์

• รายละเอียด

  TokenDetails ไม่บังคับ

  ตัวเลือกโทเค็น

• callback

  function ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (result: GetAuthTokenResult) => void

  • ผลลัพธ์

    GetAuthTokenResult

    Chrome 105 ขึ้นไป

การคืนสินค้า

• Promise<GetAuthTokenResult>

  Chrome 105 ขึ้นไป

  แสดงผล Promise ซึ่งจะได้รับการแก้ไขด้วยโทเค็นเพื่อการเข้าถึง OAuth2 ตามที่ระบุไว้ในไฟล์ Manifest หรือปฏิเสธหากมีข้อผิดพลาด ระบบจะป้อนข้อมูลพารามิเตอร์ grantedScopes ตั้งแต่ Chrome 87 เมื่อพร้อมใช้งาน พารามิเตอร์นี้จะมีรายการขอบเขตที่ได้รับอนุญาตซึ่งสอดคล้องกับโทเค็นที่แสดงผล

  ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getProfileUserInfo()

Promise

chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
): Promise<ProfileUserInfo>

ดึงข้อมูลอีเมลและรหัส GAIA ที่สร้างความสับสนของผู้ใช้ที่ลงชื่อเข้าใช้โปรไฟล์

ต้องมีสิทธิ์ identity.email ในไฟล์ Manifest ไม่เช่นนั้นจะแสดงผลลัพธ์ที่ว่างเปล่า

API นี้แตกต่างจาก identity.getAccounts ใน 2 ด้าน ข้อมูลที่แสดงจะพร้อมใช้งานแบบออฟไลน์ และใช้ได้กับบัญชีหลักของโปรไฟล์เท่านั้น

พารามิเตอร์

• รายละเอียด

  ProfileDetails ไม่บังคับ

  Chrome 84 ขึ้นไป

  ตัวเลือกโปรไฟล์

• callback

  function ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (userInfo: ProfileUserInfo) => void

  • userInfo

    ProfileUserInfo

การคืนสินค้า

• Promise<ProfileUserInfo>

  Chrome 106 ขึ้นไป

  แสดงผล Promise ซึ่งจะแก้ไขด้วย ProfileUserInfo ของบัญชี Chrome หลัก หรือ ProfileUserInfo ที่ว่างเปล่าหากไม่มีบัญชีที่มี details ที่ระบุ

  ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

getRedirectURL()

chrome.identity.getRedirectURL(
  path?: string,
): string

สร้าง URL การเปลี่ยนเส้นทางเพื่อใช้ใน launchWebAuthFlow

URL ที่สร้างขึ้นตรงกับรูปแบบ https://<app-id>.chromiumapp.org/*

พารามิเตอร์

• เส้นทาง

  สตริง ไม่บังคับ

  เส้นทางที่ต่อท้าย URL ที่สร้างขึ้น

การคืนสินค้า

• สตริง

launchWebAuthFlow()

Promise

chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
): Promise<string | undefined>

เริ่มขั้นตอนการตรวจสอบสิทธิ์ที่ URL ที่ระบุ

วิธีนี้จะเปิดใช้ขั้นตอนการตรวจสอบสิทธิ์กับผู้ให้บริการข้อมูลประจำตัวที่ไม่ใช่ Google โดยเปิดมุมมองเว็บและไปยัง URL แรกในขั้นตอนการตรวจสอบสิทธิ์ของผู้ให้บริการ เมื่อผู้ให้บริการเปลี่ยนเส้นทางไปยัง URL ที่ตรงกับรูปแบบ https://<app-id>.chromiumapp.org/* หน้าต่างจะปิดลง และระบบจะส่ง URL การเปลี่ยนเส้นทางสุดท้ายไปยังฟังก์ชัน callback

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

พารามิเตอร์

• รายละเอียด

  WebAuthFlowDetails

  ตัวเลือกโฟลว์ WebAuth

• callback

  function ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (responseUrl?: string) => void

  • responseUrl

    สตริง ไม่บังคับ

การคืนสินค้า

• Promise<string | undefined>

  Chrome 106 ขึ้นไป

  แสดงผล Promise ซึ่งจะได้รับการแก้ไขด้วย URL ที่เปลี่ยนเส้นทางกลับไปยังแอปพลิเคชันของคุณ

  ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

removeCachedAuthToken()

Promise

chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
): Promise<void>

นำโทเค็นเพื่อการเข้าถึง OAuth2 ออกจากแคชโทเค็นของ Identity API

หากพบว่าโทเค็นเพื่อการเข้าถึงไม่ถูกต้อง ควรส่งโทเค็นดังกล่าวไปยัง removeCachedAuthToken เพื่อนำออกจากแคช จากนั้นแอปอาจดึงข้อมูลโทเค็นใหม่ด้วย getAuthToken

พารามิเตอร์

• รายละเอียด

  InvalidTokenDetails

  ข้อมูลโทเค็น

• callback

  function ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  () => void

การคืนสินค้า

• Promise<void>

  Chrome 106 ขึ้นไป

  แสดงผล Promise ซึ่งจะได้รับการแก้ไขเมื่อนำโทเค็นออกจากแคชแล้ว

  ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

กิจกรรม

onSignInChanged

chrome.identity.onSignInChanged.addListener(
  callback: function,
)

เริ่มทำงานเมื่อสถานะการลงชื่อเข้าใช้มีการเปลี่ยนแปลงสำหรับบัญชีในโปรไฟล์ของผู้ใช้

พารามิเตอร์

• callback

  ฟังก์ชัน

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (account: AccountInfo, signedIn: boolean) => void

  • บัญชี

    AccountInfo

  • signedIn

    บูลีน