chrome.identity

Nội dung 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ã nhận dạng 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

Liệt kê

"SYNC"
Chỉ định chế độ Đồng bộ hoá đang 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 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ể đượ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 hồ sơ có ProfileUserInfo sẽ được trả về. Giá trị mặc định là trạng thái tài khoản SYNC.

ProfileUserInfo

Thuộc tính

  • email

    string

    Đị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 đối với tệp kê khai identity.email không được chỉ định.

  • id

    string

    Giá trị nhận dạng duy nhất của tài khoản. Mã nhận dạng 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) quyền truy cập tệp kê khai identity.email chưa đượ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, chức năng này 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 đầu tiên của Google.

  • enableGranularPermissions

    boolean không bắt buộc

    Chrome 87 trở lên

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

  • có tính tương tác

    boolean không bắt buộc

    Khi 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 các 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 nếu cần. Khi cờ này 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 các phạm vi OAuth2 cần yêu cầu.

    Khi có 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 đối với 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), quy trình sẽ kết thúc ngay sau khi trang tải. Khi bạn đặt thành false, luồng sẽ chỉ kết thúc sau khi timeoutMsForNonInteractive vượt qua. Điều này rất 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 trang tải.

  • có tính 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 khung hiển thị web cho đến khi lệnh đ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 sẽ 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ờ là false hoặc bị bỏ qua, launchWebAuthFlow sẽ trả về lỗi nếu quá trình đ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 cùng với việc đặt timeoutMsForNonInteractive để cho phép trang thực hiện mọi lệnh chuyển hướng.

  • 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()

Cam kết Chrome 87 trở lên 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

Đặt lại trạng thái của API nhận dạng:

  • 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 cấp quyền cho người dùng khỏi tất 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ề

  • Promise<void>

    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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getAccounts()

Hứa hẹn 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ó trong 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<AccountInfo[]>

    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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getAuthToken()

Cam kết 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
)

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

API nhận dạng sẽ lưu các mã truy cập trong bộ nhớ vào bộ nhớ đệm. Vì vậy, bạn có thể gọi getAuthToken mà không cần tương tác bất cứ khi nào cần đến mã thông báo. Bộ nhớ đệm của mã thông báo tự động xử lý ngày 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 phải do giao diện người dùng khởi tạo trong ứng dụng để giải thích mục đích của việc uỷ quyền. Nếu bạn 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 vào Chrome nếu người dùng chưa đăng nhập mà không có ngữ cảnh. Đặc biệt, đừng sử dụng getAuthToken để mang tính tương tác khi ứng dụng của bạn được khởi chạy 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ề 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.

Tham số

  • chi tiết

    TokenDetails không bắt buộc

    Tuỳ chọn 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ề

  • 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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getProfileUserInfo()

Cam kết 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
)

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

Yêu cầu quyền đối với 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 theo 2 cách. Thông tin được trả về có sẵn khi không có mạng và chỉ áp dụng cho tài khoản chính cho trang doanh nghiệp đó.

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<ProfileUserInfo>

    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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getRedirectURL()

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

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

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

Tham số

  • path

    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ề

  • string

launchWebAuthFlow()

Cam kết 
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 các 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 khung hiển thị web và điều hướng khung hiển thị đó đến URL đầu tiên trong quy trình xác thực của nhà cung cấp. Khi trì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, quy trình xác thực tương tác quan trọng phải do giao diện người dùng bắt đầu trong ứng dụng để giải thích mục đích của việc uỷ 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ó bối cảnh. Cụ thể, không khởi 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

    Các 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ề

  • Hứa hẹn<string|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 để có 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. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

removeCachedAuthToken()

Cam kết 
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ệ, bạn nên chuyển mã thông báo này đế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ề

  • Promise<void>

    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 để có 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. Lời hứa sẽ được phân giải bằng cùng một 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 đối với 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