chrome.identity

คำอธิบาย

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

สิทธิ์

identity

ประเภท

AccountInfo

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

  • id

    string

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

AccountStatus

Chrome เวอร์ชัน 84 ขึ้นไป

ค่าแจกแจง

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

"ใดๆ"
ระบุว่าบัญชีหลักที่มีอยู่ (หากมี)

GetAuthTokenResult

Chrome 105 ขึ้นไป

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

  • grantedScopes

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

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

  • โทเค็น

    string ไม่บังคับ

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

InvalidTokenDetails

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

  • โทเค็น

    string

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

ProfileDetails

Chrome เวอร์ชัน 84 ขึ้นไป

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

  • accountStatus

    AccountStatus ไม่บังคับ

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

ProfileUserInfo

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

  • อีเมล

    string

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

  • id

    string

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

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 จะซ่อนมุมมองเว็บของตัวเองจนกว่าการนำทางครั้งแรกจะเปลี่ยนเส้นทางไปยัง URL สุดท้าย หรือโหลดหน้าเว็บที่จะแสดงจนเสร็จ

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

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

  • timeoutMsForNonInteractive

    ตัวเลข ไม่บังคับ

    Chrome 113 ขึ้นไป

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

  • url

    string

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

วิธีการ

clearAllCachedAuthTokens()

คำมั่นสัญญา Chrome เวอร์ชัน 87 ขึ้นไป 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

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

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

พารามิเตอร์

  • Callback

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

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

    ()=>void

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

  • Promise<void>

    Chrome 106 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getAccounts()

สัญญา เวอร์ชันที่กำลังพัฒนา 
chrome.identity.getAccounts(
  callback?: function,
)

เรียกรายการออบเจ็กต์ AccountInfo ที่อธิบายบัญชีที่ปรากฏในโปรไฟล์

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

พารามิเตอร์

  • Callback

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

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

    (accounts: AccountInfo[])=>void

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

  • Promise<AccountInfo[]>

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getAuthToken()

สัญญา 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
)

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

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

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

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

พารามิเตอร์

  • รายละเอียด

    TokenDetails ไม่บังคับ

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

  • Callback

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

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

    (result: GetAuthTokenResult)=>void

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

  • Chrome 105 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getProfileUserInfo()

สัญญา 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
)

เรียกที่อยู่อีเมลและรหัส GAIA ที่ปรับให้ยากต่อการอ่าน (Obfuscate) ของผู้ใช้ที่ลงชื่อเข้าใช้โปรไฟล์

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

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

พารามิเตอร์

  • รายละเอียด

    ProfileDetails ไม่บังคับ

    Chrome เวอร์ชัน 84 ขึ้นไป

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

  • Callback

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

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

    (userInfo: ProfileUserInfo)=>void

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

  • Promise<ProfileUserInfo>

    Chrome 106 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getRedirectURL()

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

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

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

พารามิเตอร์

  • เส้นทาง

    string ไม่บังคับ

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

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

  • string

launchWebAuthFlow()

สัญญา 
chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
)

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

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

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

พารามิเตอร์

  • รายละเอียด

    WebAuthFlowDetails

    ตัวเลือกขั้นตอน WebAuth

  • Callback

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

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

    (responseUrl?: string)=>void

    • responseUrl

      string ไม่บังคับ

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

  • คำสัญญา<สตริง|ไม่ระบุ>

    Chrome 106 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

removeCachedAuthToken()

สัญญา 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
)

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

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

พารามิเตอร์

  • รายละเอียด

    InvalidTokenDetails

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

  • Callback

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

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

    ()=>void

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

  • Promise<void>

    Chrome 106 ขึ้นไป

    Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

กิจกรรม

onSignInChanged

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

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