chrome.identity

refresh date: 2026-09-25 robots: noindex

Mô tả

Sử dụng API chrome.identity để lấy mã truy cập OAuth2.

Quyền

identity

Loại

AccountInfo

Thuộc tính

  • id

    chuỗi

    Giá trị nhận dạng riêng biệt của tài khoản. Mã này sẽ không thay đổi trong suốt thời gian tồn tại 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.

"ANY"
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 các 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ể liên kết với yêu cầu.

InvalidTokenDetails

Thuộc tính

  • mã thông báo

    chuỗi

    Mã thông báo cụ thể cần 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 SYNC.

ProfileUserInfo

Thuộc tính

  • email

    chuỗi

    Địa chỉ email của 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 quyền identity.email trong tệp kê khai không được chỉ định.

  • id

    chuỗi

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

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, hàm 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 web Google đầ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ử dụng sớm màn hình xin phép cấp quyền chi tiết, trong đó các quyền được yêu cầu sẽ được cấp hoặc từ chối riêng lẻ.

  • tương tác

    boolean không bắt buộc

    Để tìm nạp mã thông báo, người dùng có thể phải đă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. Khi cờ là false hoặc bị 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 phạm vi OAuth2 cần yêu cầu.

    Khi trường scopes xuất hiện, 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

    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 quy trình tương tác.

    Khi được đặ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 hữu ích cho các nhà cung cấp danh tính sử dụng JavaScript để thực hiện lệnh chuyển hướng sau khi trang tải.

  • tương tác

    boolean không bắt buộc

    Có 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 lần đ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 cần hiển thị.

    Nếu cờ interactive là true, thì cửa sổ sẽ xuất hiện khi quá trình tải trang hoàn tất. Nếu cờ là false hoặc bị bỏ qua, launchWebAuthFlow sẽ trả về lỗi nếu thao tác điều hướng ban đầu không hoàn tất quy trình.

    Đố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 mọi lệnh chuyển hướng.

  • timeoutMsForNonInteractive

    number 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) mà 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

    chuỗi

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

Phương thức

clearAllCachedAuthTokens()

Promise Chrome 87 trở lên 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
): Promise<void>

Đặt lại trạng thái của Identity API:

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

Thông số

  • callback

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

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 106 trở lên

    Trả về một Lời hứa sẽ được thực hiện khi trạng thái đã được xoá.

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getAccounts()

Promise Kênh nhà phát triển 
chrome.identity.getAccounts(
  callback?: function,
): Promise<AccountInfo[]>

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

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

Thông số

  • callback

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

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

    (accounts: AccountInfo[]) => void

Giá trị trả về

  • <AccountInfo[]> hứa hẹn

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getAuthToken()

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

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

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

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

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ề hai 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.

Thông số

  • chi tiết

    TokenDetails không bắt buộc

    Các lựa chọn về mã thông báo.

  • callback

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

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

    (result: GetAuthTokenResult) => void

Giá trị trả về

  • Chrome 105 trở lên

    Trả về một Promise phân giải bằng mã truy cập OAuth2 như được chỉ định trong tệp kê khai hoặc từ chối nếu có lỗi. Tham số grantedScopes được điền sẵn kể từ Chrome 87. Khi có, tham số này chứa danh sách các phạm vi được cấp tương ứng với mã thông báo được trả về.

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getProfileUserInfo()

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

Lấy địa chỉ email và mã gaia bị làm rối mã nguồn của người dùng đã đăng nhập vào một hồ sơ.

Yêu cầu quyền identity.email trong tệp kê khai. Nếu không, hàm 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ể xem khi không có mạng và chỉ áp dụng cho tài khoản chính của hồ sơ.

Thông số

  • chi tiết

    ProfileDetails không bắt buộc

    Chrome 84 trở lên

    Tuỳ chọn hồ sơ.

  • callback

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

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

    (userInfo: ProfileUserInfo) => void

Giá trị trả về

  • Promise<ProfileUserInfo>

    Chrome 106 trở lên

    Trả về một Lời hứa sẽ phân giải bằng ProfileUserInfo của tài khoản Chrome chính hoặc ProfileUserInfo trống nếu tài khoản có details đã cho không tồn tại.

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getRedirectURL()

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

Tạo một URL chuyển hướng để sử dụng trong launchWebAuthFlow.

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

Thông số

  • đường dẫn

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

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

Giá trị trả về

  • chuỗi

launchWebAuthFlow()

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

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

Phương thức này cho phép quy trình xác thực với các nhà cung cấp danh tính không phải của Google bằng cách chạy một chế độ xem web và chuyển 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 đến hàm callback.

Để mang lại trải nghiệm tốt cho người dùng, điều quan trọng là quy trình uỷ quyền tương tác phải được bắt đầu bằng giao diện người dùng trong ứng dụng, giải thích mục đích của việc uỷ quyền. Nếu không làm như vậy, người dùng của bạn sẽ nhận được yêu cầu uỷ quyền mà không có bối cảnh. Cụ thể, đừ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.

Thông số

  • chi tiết

    WebAuthFlowDetails

    Tuỳ chọn quy trình WebAuth.

  • callback

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

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

    (responseUrl?: string) => void

    • responseUrl

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

Giá trị trả về

  • <string | undefined> hứa hẹn

    Chrome 106 trở lên

    Trả về một Lời hứa sẽ phân giải bằng URL được chuyển hướng trở lại ứng dụng của bạn.

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

removeCachedAuthToken()

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

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ã truy cập không hợp lệ, bạn nên chuyển mã đó đến removeCachedAuthToken để 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.

Thông số

  • chi tiết

    InvalidTokenDetails

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

  • callback

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

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

    () => void

Giá trị trả về

  • Promise<void>

    Chrome 106 trở lên

    Trả về một Lời hứa sẽ giải quyết khi mã thông báo đã bị xoá khỏi bộ nhớ đệm.

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng 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 đối với một tài khoản trong hồ sơ của người dùng.

Thông số

  • callback

    hàm

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

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