chrome.permissions

Mô tả

Hãy dùng API chrome.permissions để yêu cầu các quyền không bắt buộc đã khai báo trong thời gian chạy thay vì trong thời gian cài đặt, để người dùng hiểu lý do vì sao các quyền này lại cần thiết và chỉ cấp những quyền cần thiết.

Khái niệm và cách sử dụng

Cảnh báo quyền tồn tại để mô tả các khả năng do API cấp, nhưng một số cảnh báo trong số này có thể không rõ ràng. API Quyền cho phép nhà phát triển giải thích các cảnh báo về quyền và từng bước giới thiệu các tính năng mới, giúp người dùng được giới thiệu tiện ích mà không có rủi ro. Bằng cách này, người dùng có thể chỉ định mức quyền truy cập mà họ sẵn sàng cấp và những tính năng mà họ muốn bật.

Ví dụ: chức năng cốt lõi của tiện ích quyền không bắt buộc là ghi đè trang thẻ mới. Một tính năng đang hiển thị mục tiêu trong ngày của người dùng. Tính năng này chỉ yêu cầu quyền bộ nhớ và không có cảnh báo. Tiện ích này có một tính năng bổ sung mà người dùng có thể bật bằng cách nhấp vào nút sau:

Nút tiện ích bật các tính năng bổ sung.
Nút tiện ích bật các tính năng bổ sung.

Để hiển thị các trang web hàng đầu của người dùng, bạn cần có quyền topSites và kèm theo cảnh báo sau.

Cảnh báo tăng cường đối với topSites API.
Cảnh báo tiện ích cho API topSites

Triển khai các quyền không bắt buộc

Bước 1: Quyết định quyền nào là bắt buộc và quyền nào là không bắt buộc

Tiện ích có thể khai báo cả quyền bắt buộc và quyền không bắt buộc. Nói chung, bạn nên:

  • Bạn có thể dùng các quyền cần thiết khi cần thiết cho chức năng cơ bản của tiện ích.
  • Sử dụng các quyền không bắt buộc khi cần thiết cho những tính năng không bắt buộc trong tiện ích.

Ưu điểm của các quyền bắt buộc:

  • Ít lời nhắc hơn: Tiện ích có thể nhắc người dùng một lần để chấp nhận tất cả các quyền.
  • Phát triển đơn giản hơn: Đảm bảo có các quyền bắt buộc.

Ưu điểm của quyền không bắt buộc:

  • Bảo mật tốt hơn: Tiện ích chạy với ít quyền hơn vì người dùng chỉ cấp quyền cần thiết.
  • Thông tin tốt hơn cho người dùng: Tiện ích có thể giải thích lý do tiện ích cần một quyền cụ thể khi người dùng bật tính năng có liên quan.
  • Nâng cấp dễ dàng hơn: Khi bạn nâng cấp tiện ích, Chrome sẽ không vô hiệu hoá tiện ích đó đối với người dùng nếu bản nâng cấp sẽ thêm các quyền không bắt buộc thay vì bắt buộc.

Bước 2: Khai báo các quyền không bắt buộc trong tệp kê khai

Khai báo các quyền không bắt buộc trong tệp kê khai tiện ích bằng khoá optional_permissions, sử dụng định dạng giống như trường quyền:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

Nếu bạn muốn yêu cầu các máy chủ mà bạn chỉ phát hiện trong thời gian chạy, hãy thêm "https://*/*" vào trường optional_host_permissions của tiện ích. Điều này cho phép bạn chỉ định nguồn gốc bất kỳ trong "Permissions.origins" miễn là nguồn gốc đó có một hệ thống.

Các quyền không có thể được chỉ định là không bắt buộc

Bạn có thể chỉ định hầu hết các quyền đối với tiện ích của Chrome là không bắt buộc, trừ những trường hợp ngoại lệ sau.

Quyền Mô tả
"debugger" API chrome.debugger đóng vai trò là một phương tiện thay thế cho tính năng gỡ lỗi từ xa của Chrome giao thức.
"declarativeNetRequest" Cấp cho tiện ích quyền truy cập vào API chrome.declarativeNetRequest.
"devtools" Cho phép tiện ích mở rộng Công cụ của Chrome cho nhà phát triển của Google.
"geolocation" Cho phép tiện ích sử dụng API vị trí địa lý HTML5.
"mdns" Cấp cho tiện ích quyền truy cập vào chrome.mdns.
"proxy" Cấp cho tiện ích quyền truy cập vào API chrome.proxy để quản lý proxy của Chrome phần cài đặt.
"tts" API chrome.tts phát tổng hợp chuyển văn bản sang lời nói (TTS).
"ttsEngine" API chrome.ttsEngine triển khai một chuyển văn bản sang lời nói (TTS) bằng tiện ích.
"wallpaper" chỉ dành cho ChromeOS. Dùng API chrome.wallpaper để thay đổi ChromeOS hình nền.

Xem mục Khai báo quyền để biết thêm thông tin về các quyền hiện có và các cảnh báo của họ.

Bước 3: Yêu cầu cấp các quyền không bắt buộc

Yêu cầu cấp quyền ngay trong một cử chỉ của người dùng bằng cách sử dụng permissions.request():

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  chrome.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

Chrome sẽ nhắc người dùng nếu việc thêm quyền dẫn đến thông báo cảnh báo khác với mà người dùng đã xem và chấp nhận. Ví dụ: đoạn mã trước đó có thể đưa ra lời nhắc như sau:

Ví dụ về lời nhắc xác nhận quyền.
Ví dụ về lời nhắc xác nhận quyền.

Bước 4: Kiểm tra các quyền hiện tại của tiện ích

Để kiểm tra xem tiện ích của bạn có quyền hoặc tập hợp quyền cụ thể hay không, hãy sử dụng permission.contains():

chrome.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

Bước 5: Thu hồi quyền

Bạn nên thu hồi quyền khi không cần nữa. Sau khi bạn xoá một quyền, thường thì việc gọi permissions.request() sẽ thêm quyền trở lại mà không nhắc người dùng.

chrome.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

Loại

Permissions

Thuộc tính

  • nguồn gốc

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

    Danh sách quyền của máy chủ lưu trữ, bao gồm những quyền được chỉ định trong khoá optional_permissions hoặc permissions trong tệp kê khai và những quyền liên kết với Tập lệnh nội dung.

  • quyền

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

    Danh sách các quyền đã có tên (không bao gồm máy chủ hoặc nguồn gốc).

Phương thức

contains()

Lời hứa
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

Kiểm tra xem tiện ích đã có các quyền đã chỉ định hay chưa.

Tham số

  • số gọi lại

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

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

    (result: boolean) => void

    • kết quả

      boolean

      Đúng nếu tiện ích đó có các quyền đã chỉ định. Nếu một nguồn gốc vừa được chỉ định là quyền không bắt buộc vừa là mẫu khớp tập lệnh nội dung, thì hàm này sẽ trả về false trừ phi cả hai quyền đều được cấp.

Giá trị trả về

  • Promise<boolean>

    Chrome 96 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.

getAll()

Lời hứa
chrome.permissions.getAll(
  callback?: function,
)

Lấy nhóm quyền hiện tại của tiện ích.

Tham số

  • số gọi lại

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

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

    (permissions: Permissions) => void

    • Các quyền đang hoạt động của tiện ích. Xin lưu ý rằng thuộc tính origins sẽ chứa các nguồn gốc đã cấp từ những nguồn được chỉ định trong khoá permissionsoptional_permissions trong tệp kê khai và những nguồn liên kết với Tập lệnh nội dung.

Giá trị trả về

  • Promise<Permissions>

    Chrome 96 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.

remove()

Lời hứa
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

Xóa quyền truy cập vào các quyền đã chỉ định. Nếu có vấn đề khi xoá quyền, runtime.lastError sẽ được thiết lập.

Tham số

  • số gọi lại

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

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

    (removed: boolean) => void

    • đã xóa

      boolean

      Đúng nếu quyền đã bị thu hồi.

Giá trị trả về

  • Promise<boolean>

    Chrome 96 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.

request()

Lời hứa
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

Yêu cầu truy cập vào các quyền đã chỉ định, hiển thị lời nhắc cho người dùng nếu cần. Các quyền này phải được xác định trong trường optional_permissions của tệp kê khai hoặc là các quyền bắt buộc mà người dùng đã từ chối. Đường dẫn trên các mẫu nguồn gốc sẽ bị bỏ qua. Bạn có thể yêu cầu một nhóm nhỏ các quyền không bắt buộc đối với máy chủ gốc; ví dụ: nếu chỉ định *://*\/* trong phần optional_permissions của tệp kê khai, bạn có thể yêu cầu http://example.com/. Nếu có bất kỳ sự cố nào khi yêu cầu quyền, runtime.lastError sẽ được thiết lập.

Tham số

  • số gọi lại

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

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

    (granted: boolean) => void

    • được cấp

      boolean

      Đúng nếu người dùng đã cấp các quyền đã chỉ định.

Giá trị trả về

  • Promise<boolean>

    Chrome 96 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

onAdded

chrome.permissions.onAdded.addListener(
  callback: function,
)

Được kích hoạt khi tiện ích có được các quyền mới.

Tham số

onRemoved

chrome.permissions.onRemoved.addListener(
  callback: function,
)

Được kích hoạt khi bạn đã xoá quyền truy cập vào tiện ích.

Tham số