chrome.identity

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

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

สิทธิ์

identity

ประเภท

AccountInfo

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

  • id

    สตริง

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

AccountStatus

Chrome 84 ขึ้นไป

ค่าแจกแจง

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

"ANY"
ระบุว่ามีบัญชีหลักหรือไม่

GetAuthTokenResult

Chrome 105 ขึ้นไป

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

  • grantedScopes

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

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

  • โทเค็น

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

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

InvalidTokenDetails

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

  • โทเค็น

    สตริง

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

ProfileDetails

Chrome 84 ขึ้นไป

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

  • accountStatus

    AccountStatus ไม่บังคับ

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

ProfileUserInfo

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

  • อีเมล

    สตริง

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

  • id

    สตริง

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

TokenDetails

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

  • บัญชี

    AccountInfo ไม่บังคับ

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

  • enableGranularPermissions

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

    Chrome 87 ขึ้นไป

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

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

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

    การดึงโทเค็นอาจกำหนดให้ผู้ใช้ต้องลงชื่อเข้าใช้ Chrome หรืออนุมัติขอบเขตที่แอปพลิเคชันร้องขอ หากแฟล็กแบบอินเทอร์แอกทีฟเป็น true getAuthToken จะแจ้งให้ผู้ใช้ทราบตามความจำเป็น เมื่อตั้งค่า Flag เป็น 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

    หมายเลข ไม่บังคับ

    Chrome 113 ขึ้นไป

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

  • URL

    สตริง

    URL ที่เริ่มต้นโฟลว์การให้สิทธิ์

เมธอด

clearAllCachedAuthTokens()

Promise Chrome 87 ขึ้นไป 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
): Promise<void>

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    () => void

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

  • Promise<void>

    Chrome 106 ขึ้นไป

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

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

getAccounts()

Promise เวอร์ชันที่กำลังพัฒนา 
chrome.identity.getAccounts(
  callback?: function,
): Promise<AccountInfo[]>

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

getAccounts รองรับเฉพาะในช่อง Dev

พารามิเตอร์

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (accounts: AccountInfo[]) => void

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

  • Promise<AccountInfo[]>

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

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

    ฟังก์ชัน ไม่บังคับ

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

    (result: GetAuthTokenResult) => void

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

  • Chrome 105 ขึ้นไป

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

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

getProfileUserInfo()

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

ดึงอีเมลและรหัส Gaia ที่มีการปกปิดของผู้ใช้ที่ลงชื่อเข้าใช้โปรไฟล์

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

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

พารามิเตอร์

  • รายละเอียด

    ProfileDetails ไม่บังคับ

    Chrome 84 ขึ้นไป

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

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (userInfo: ProfileUserInfo) => void

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

  • Promise<ProfileUserInfo>

    Chrome 106 ขึ้นไป

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

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

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

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

พารามิเตอร์

  • รายละเอียด

    WebAuthFlowDetails

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

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    (responseUrl?: string) => void

    • responseUrl

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

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

  • Promise<string | undefined>

    Chrome 106 ขึ้นไป

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

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

removeCachedAuthToken()

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

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

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

พารามิเตอร์

  • รายละเอียด

    InvalidTokenDetails

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

  • callback

    ฟังก์ชัน ไม่บังคับ

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

    () => void

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

  • Promise<void>

    Chrome 106 ขึ้นไป

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

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

กิจกรรม

onSignInChanged

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

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