chrome.identity

Mô tả

Dùng API chrome.identity để nhận mã truy cập OAuth2.

Quyền

identity

Loại

AccountInfo

Thuộc tính

  • id

    string

    Giá trị nhận dạng duy nhất của tài khoản. Mã này sẽ không thay đổi trong suốt thời gian hoạt động của tài khoản.

AccountStatus

Chrome 84 trở lên

Enum

"SYNC"
Chỉ định rằng tính năng Đồng bộ hoá được bật cho tài khoản chính.

"BẤT KỲ"
Chỉ định sự tồn tại của tài khoản chính, nếu có.

GetAuthTokenResult

Chrome 105 trở lên

Thuộc tính

  • grantedScopes

    string[] không bắt buộc

    Danh sách phạm vi OAuth2 được cấp cho tiện ích.

  • mã thông báo

    chuỗi không bắt buộc

    Mã thông báo cụ thể được liên kết với yêu cầu.

InvalidTokenDetails

Thuộc tính

  • mã thông báo

    string

    Mã thông báo cụ thể cần được xoá khỏi bộ nhớ đệm.

ProfileDetails

Chrome 84 trở lên

Thuộc tính

  • accountStatus

    AccountStatus không bắt buộc

    Trạng thái của tài khoản chính đã đăng nhập vào một hồ sơ có ProfileUserInfo cần được trả về. Mặc định là trạng thái tài khoản là SYNC.

ProfileUserInfo

Thuộc tính

  • email

    string

    Địa chỉ email cho tài khoản người dùng đã đăng nhập vào hồ sơ hiện tại. Để trống nếu người dùng chưa đăng nhập hoặc chưa chỉ định quyền đối với tệp kê khai identity.email.

  • id

    string

    Giá trị nhận dạng duy nhất của tài khoản. Mã này sẽ không thay đổi trong suốt thời gian hoạt động của tài khoản. Để trống nếu người dùng chưa đăng nhập hoặc (trong M41 trở lên) mà không chỉ định quyền đối với tệp kê khai identity.email.

TokenDetails

Thuộc tính

  • tài khoản

    AccountInfo không bắt buộc

    Mã tài khoản có mã thông báo cần được trả về. Nếu không được chỉ định, chức năng sẽ sử dụng một tài khoản trong hồ sơ Chrome: tài khoản Đồng bộ hoá (nếu có) hoặc tài khoản Google web đầu tiên.

  • enableGranularPermissions

    boolean không bắt buộc

    Chrome 87 trở lên

    Cờ enableGranularPermissions cho phép tiện ích chọn sớm sử dụng màn hình xin phép ở cấp quyền chi tiết, trong đó các quyền đã yêu cầu được cấp hoặc từ chối riêng lẻ.

  • tương tác

    boolean không bắt buộc

    Quá trình tìm nạp mã thông báo có thể yêu cầu người dùng đăng nhập vào Chrome hoặc phê duyệt phạm vi mà ứng dụng yêu cầu. Nếu cờ tương tác là true, getAuthToken sẽ nhắc người dùng khi cần thiết. Khi cờ này là false hoặc được bỏ qua, getAuthToken sẽ trả về lỗi bất cứ khi nào cần có lời nhắc.

  • các phạm vi

    string[] không bắt buộc

    Danh sách các phạm vi OAuth2 để yêu cầu.

    Khi xuất hiện trường scopes, trường này sẽ ghi đè danh sách phạm vi được chỉ định trong manifest.json.

WebAuthFlowDetails

Thuộc tính

  • abortOnLoadForNonInteractive

    boolean không bắt buộc

    Chrome 113 trở lên

    Liệu có chấm dứt launchWebAuthFlow cho các yêu cầu không tương tác sau khi tải trang hay không. Tham số này không ảnh hưởng đến các luồng tương tác.

    Khi bạn đặt thành true (mặc định), luồng sẽ chấm dứt ngay sau khi tải trang. Khi được đặt thành false, luồng sẽ chỉ kết thúc sau khi timeoutMsForNonInteractive vượt qua. Điều này sẽ hữu ích đối với những nhà cung cấp danh tính sử dụng JavaScript để thực hiện lệnh chuyển hướng sau khi tải trang.

  • tương tác

    boolean không bắt buộc

    Liệu có khởi chạy quy trình xác thực ở chế độ tương tác hay không.

    Vì một số quy trình xác thực có thể chuyển hướng ngay lập tức đến một URL kết quả, nên launchWebAuthFlow sẽ ẩn chế độ xem web cho đến khi điều hướng đầu tiên chuyển hướng đến URL cuối cùng hoặc hoàn tất việc tải một trang dự định được hiển thị.

    Nếu cờ interactive là true, cửa sổ sẽ hiển thị khi quá trình tải trang hoàn tất. Nếu cờ này có giá trị false hoặc được bỏ qua, thì launchWebAuthFlow sẽ trả về kèm theo lỗi nếu thao tác điều hướng ban đầu không hoàn tất luồng.

    Đối với các luồng sử dụng JavaScript để chuyển hướng, bạn có thể đặt abortOnLoadForNonInteractive thành false kết hợp với việc đặt timeoutMsForNonInteractive để trang có cơ hội thực hiện bất kỳ lượt chuyển hướng nào.

  • timeoutMsForNonInteractive

    số không bắt buộc

    Chrome 113 trở lên

    Tổng thời gian tối đa (tính bằng mili giây) launchWebAuthFlow được phép chạy ở chế độ không tương tác. Chỉ có hiệu lực nếu interactive là false.

  • url

    string

    URL bắt đầu quy trình xác thực.

Phương thức

clearAllCachedAuthTokens()

Lời hứa Chrome 87 trở lên 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

Đặt lại trạng thái của API Danh tính:

  • Xoá tất cả mã truy cập OAuth2 khỏi bộ nhớ đệm của mã thông báo
  • Xoá các lựa chọn ưu tiên về tài khoản của người dùng
  • Ngừng uỷ quyền cho người dùng khỏi tất cả các quy trình xác thực

Tham số

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 106 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getAccounts()

Lời hứa Kênh nhà phát triển 
chrome.identity.getAccounts(
  callback?: function,
)

Truy xuất danh sách đối tượng AccountInfo mô tả các tài khoản có trên hồ sơ.

getAccounts chỉ được hỗ trợ trên kênh nhà phát triển.

Tham số

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (accounts: AccountInfo[]) => void

Giá trị trả về

  • Promise&lt;AccountInfo[]&gt;

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getAuthToken()

Lời hứa 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
)

Lấy mã truy cập OAuth2 bằng mã ứng dụng khách và các phạm vi được chỉ định trong mục oauth2 của manifest.json.

API Danh tính sẽ lưu mã truy cập vào bộ nhớ đệm trong bộ nhớ. Vì vậy, bạn có thể gọi getAuthToken một cách không tương tác bất cứ khi nào cần mã thông báo. Bộ nhớ đệm của mã thông báo sẽ tự động xử lý thời gian hết hạn.

Để mang lại trải nghiệm tốt cho người dùng, các yêu cầu mã thông báo tương tác quan trọng là do giao diện người dùng khởi tạo trong ứng dụng để giải thích mục đích việc uỷ quyền. Nếu bạn không làm được việc này, thì người dùng sẽ nhận được yêu cầu uỷ quyền hoặc màn hình đăng nhập vào Chrome nếu họ chưa đăng nhập mà không kèm theo ngữ cảnh. Cụ thể, đừng sử dụng getAuthToken theo cách có tính tương tác khi khởi chạy ứng dụng lần đầu tiên.

Lưu ý: Khi được gọi bằng lệnh gọi lại, thay vì trả về một đối tượng, hàm này sẽ trả về 2 thuộc tính dưới dạng các đối số riêng biệt được truyền đến lệnh gọi lại.

Tham số

  • chi tiết

    TokenDetails không bắt buộc

    Tuỳ chọn về mã thông báo.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (result: GetAuthTokenResult) => void

Giá trị trả về

  • Promise&lt;GetAuthTokenResult&gt;

    Chrome 105 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getProfileUserInfo()

Lời hứa 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
)

Truy xuất địa chỉ email và mã GAIA bị làm rối của người dùng đã đăng nhập vào hồ sơ.

Cần có quyền truy cập tệp kê khai identity.email. Nếu không, sẽ trả về kết quả trống.

API này khác với Identity.getAccounts ở hai điểm. Thông tin được trả về có thể sử dụng khi không có mạng và chỉ áp dụng cho tài khoản chính cho hồ sơ.

Tham số

  • chi tiết

    ProfileDetails không bắt buộc

    Chrome 84 trở lên

    Tuỳ chọn hồ sơ.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (userInfo: ProfileUserInfo) => void

Giá trị trả về

  • Promise&lt;ProfileUserInfo&gt;

    Chrome 106 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

getRedirectURL()

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

Tạo URL chuyển hướng sẽ được sử dụng trong launchWebAuthFlow.

Các URL đã tạo khớp với mẫu https://<app-id>.chromiumapp.org/*.

Tham số

  • đường dẫn

    chuỗi không bắt buộc

    Đường dẫn được nối vào cuối URL đã tạo.

Giá trị trả về

  • string

launchWebAuthFlow()

Lời hứa 
chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
)

Bắt đầu quy trình xác thực tại URL đã chỉ định.

Phương thức này cho phép quy trình xác thực với nhà cung cấp danh tính không phải của Google bằng cách khởi chạy chế độ xem web và điều hướng chế độ xem đó đến URL đầu tiên trong quy trình xác thực của nhà cung cấp. Khi nhà cung cấp chuyển hướng đến một URL khớp với mẫu https://<app-id>.chromiumapp.org/*, cửa sổ sẽ đóng và URL chuyển hướng cuối cùng sẽ được chuyển cho hàm callback.

Để mang đến trải nghiệm tốt cho người dùng, quy trình xác thực tương tác quan trọng do giao diện người dùng bắt đầu trong ứng dụng của bạn để giải thích mục đích việc ủy quyền. Nếu bạn không làm như vậy, người dùng sẽ nhận được yêu cầu uỷ quyền mà không có ngữ cảnh. Cụ thể, không chạy quy trình xác thực tương tác khi ứng dụng của bạn được khởi chạy lần đầu tiên.

Tham số

  • chi tiết

    WebAuthFlowDetails

    Tuỳ chọn quy trình WebAuth.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    (responseUrl?: string) => void

    • responseUrl

      chuỗi không bắt buộc

Giá trị trả về

  • Cam kết<chuỗi | không xác định>

    Chrome 106 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

removeCachedAuthToken()

Lời hứa 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
)

Xoá mã truy cập OAuth2 khỏi bộ nhớ đệm mã thông báo của API Nhận dạng.

Nếu phát hiện thấy một mã truy cập không hợp lệ, mã đó sẽ được chuyển đến removeCacheAuthToken để xoá mã đó khỏi bộ nhớ đệm. Sau đó, ứng dụng có thể truy xuất mã thông báo mới bằng getAuthToken.

Tham số

  • chi tiết

    InvalidTokenDetails

    Thông tin về mã thông báo.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 106 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.

Sự kiện

onSignInChanged

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

Được kích hoạt khi trạng thái đăng nhập thay đổi cho một tài khoản trên hồ sơ của người dùng.

Tham số

  • số gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

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