chrome.identity

Mô tả

Sử dụng API chrome.identity để nhận 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ã nhận dạng 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"
Cho biết 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ơ mà ProfileUserInfo sẽ đượ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. Rỗng nếu người dùng chưa đăng nhập hoặc bạn chưa chỉ định quyền identity.email trong tệp kê khai.

  • id

    chuỗi

    Giá trị nhận dạng riêng biệ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 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 trở lên) quyền identity.email trong tệp kê khai 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 Google trên web đầu tiên.

  • enableGranularPermissions

    boolean không bắt buộc

    Chrome 87 trở lên

    Cờ enableGranularPermissions cho phép các tiện ích chọn sử dụng sớm màn hình đồng ý cấp quyền ở cấp độ 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 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 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 các 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 các 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ó nên chấm dứt launchWebAuthFlow cho các yêu cầu không tương tác sau khi trang tải hay không. Tham số này không ảnh hưởng đến các luồng tương tác.

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

  • tương tác

    boolean không bắt buộc

    Có khởi chạy quy trình uỷ quyền ở chế độ tương tác hay không.

    Vì một số quy trình uỷ quyền có thể chuyển hướng ngay đến một URL kết quả, nên launchWebAuthFlow sẽ ẩn chế độ xem web cho đến khi thao tác đ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ự kiến sẽ hiển thị.

    Nếu cờ interactive là true, 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 những 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 mà launchWebAuthFlow được phép chạy ở chế độ không tương tác là tính bằng mili giây. Chỉ có hiệu lực nếu interactive là false.

  • url

    chuỗi

    URL bắt đầu quy trình uỷ quyền.

Phương thức

clearAllCachedAuthTokens()

Chrome 87 trở lên 
chrome.identity.clearAllCachedAuthTokens(): 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á các lựa chọn ưu tiên về tài khoản của người dùng
  • Huỷ uỷ quyền người dùng khỏi tất cả các quy trình uỷ quyền

Giá trị trả về

  • Promise<void>

    Chrome 106 trở lên

getAccounts()

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

Truy xuất danh sách các đố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 dành cho nhà phát triển.

Giá trị trả về

getAuthToken()

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

Lấy mã truy cập OAuth2 bằng mã ứng dụng và các 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 về mã thông báo tương tác phải do giao diện người dùng trong ứng dụng của bạn khởi tạo, 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 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 biệt, đừng sử dụng getAuthToken một cách tương tác khi ứng dụng của bạn chạy lần đầu.

Lưu ý: Khi được gọi bằng một 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.

Giá trị trả về

getProfileUserInfo()

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

Truy xuất địa chỉ email và mã nhận dạng gaia bị làm rối 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, sẽ trả về một kết quả trống.

API này khác với identity.getAccounts ở hai điểm. Thông tin được trả về có sẵn ở chế độ ngoại tuyến 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ơ.

Giá trị trả về

getRedirectURL()

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

Tạo 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()

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

Bắt đầu một quy trình uỷ quyền tại URL đã chỉ định.

Phương thức này cho phép các luồng 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 một khung hiển thị web và chuyển hướng khung hiển thị đó đến URL đầu tiên trong luồng 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 truyề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à giao diện người dùng trong ứng dụng của bạn phải bắt đầu các quy trình xác thực tương tác, đồng thời 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 sẽ nhận được các yêu cầu uỷ quyền mà không có ngữ cảnh. Cụ thể, đừng chạy một quy trình xác thực tương tác khi ứng dụng của bạn chạy lần đầu.

Thông số

Giá trị trả về

  • Promise<string | undefined>

    Chrome 106 trở lên

removeCachedAuthToken()

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

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

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

Thông số

Giá trị trả về

  • Promise<void>

    Chrome 106 trở lên

Sự kiện

onSignInChanged

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

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

Thông số

  • callback

    hàm

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

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