chrome.permissions

Opis

Użyj interfejsu chrome.permissions API, aby poprosić o deklarowane opcjonalne uprawnienia w czasie działania aplikacji, a nie w czasie instalacji. Dzięki temu użytkownicy będą rozumieć, do czego są potrzebne te uprawnienia, i przyznawać tylko te, które są niezbędne.

Pojęcia i zastosowanie

Ostrzeżenia o wymaganych uprawnieniach opisują możliwości udostępniane przez interfejs API, ale niektóre z tych ostrzeżeń mogą nie być oczywiste. Interfejs Permissions API umożliwia deweloperom wyjaśnienie ostrzeżeń dotyczących uprawnień i stopniowe wprowadzanie nowych funkcji, co pozwala użytkownikom zapoznać się z rozszerzeniem bez ryzyka. Dzięki temu użytkownicy mogą określić, jaki dostęp chcą przyznać i które funkcje chcą włączyć.

Na przykład główna funkcja rozszerzenia opcjonalnych uprawnień zastępuje stronę nowej karty. Jedną z nich jest wyświetlanie celu na dany dzień. Ta funkcja wymaga tylko uprawnienia dostęp do pamięci, które nie zawiera ostrzeżenia. Rozszerzenie ma dodatkową funkcję, którą użytkownicy mogą włączyć, klikając ten przycisk:

Przycisk rozszerzenia, który umożliwia korzystanie z dodatkowych funkcji.
Przycisk rozszerzenia, który umożliwia korzystanie z dodatkowych funkcji.

Wyświetlanie najczęściej odwiedzanych witryn użytkownika wymaga uprawnienia topSites, które jest opatrzone tym ostrzeżeniem.

Ostrzeżenie dotyczące rozszerzenia dla interfejsu topSites API.
Ostrzeżenie dotyczące rozszerzenia dla interfejsu API topSites

Wdrażanie opcjonalnych uprawnień

Krok 1. Zdecyduj, które uprawnienia są wymagane, a które opcjonalne

Rozszerzenie może deklarować zarówno wymagane, jak i opcjonalne uprawnienia. Ogólnie rzecz biorąc, wykonaj te czynności:

  • Używaj wymaganych uprawnień tylko wtedy, gdy są one potrzebne do działania podstawowych funkcji rozszerzenia.
  • Używaj opcjonalnych uprawnień, gdy są one potrzebne do opcjonalnych funkcji rozszerzenia.

Zalety wymaganych uprawnień:

  • Mniej promptów: rozszerzenie może poprosić użytkownika o przyznanie wszystkich uprawnień tylko raz.
  • Prostszy rozwój: wymagane uprawnienia są zawsze dostępne.

Zalety opcjonalnych uprawnień:

  • Lepsze bezpieczeństwo: rozszerzenia działają z mniejszą liczbą uprawnień, ponieważ użytkownicy zezwalają tylko na uprawnienia, które są potrzebne.
  • Więcej informacji dla użytkowników: rozszerzenie może wyjaśnić, dlaczego potrzebuje określonego uprawnienia, gdy użytkownik włączy odpowiednią funkcję.
  • Łatwiejsze uaktualnienia: gdy uaktualnisz rozszerzenie, Chrome nie wyłączy go dla użytkowników, jeśli uaktualnienie dodaje opcjonalne, a nie wymagane uprawnienia.

Krok 2. Zadeklaruj opcjonalne uprawnienia w pliku manifestu

Zadeklaruj opcjonalne uprawnienia w pliku manifestu rozszerzenia za pomocą klucza optional_permissions, używając tego samego formatu co pole Uprawnienia:

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

Jeśli chcesz żądać hostów, które wykryto dopiero w czasie działania, umieść wartość "https://*/*" w polu optional_host_permissions rozszerzenia. Dzięki temu możesz określić dowolne źródło w "Permissions.origins", o ile ma ono odpowiedni schemat.

Uprawnienia, które nie mogą być określone jako opcjonalne

Większość uprawnień rozszerzeń do Chrome można określić jako opcjonalne, z tymi wyjątkami:

Uprawnienie Opis
"debugger" Interfejs chrome.debugger API służy jako alternatywny transport dla protokołu zdalnego debugowania w Chrome.
"declarativeNetRequest" Przyznaje rozszerzeniu dostęp do interfejsu API chrome.declarativeNetRequest.
"devtools" Umożliwia rozszerzeniu rozszerzenie funkcjonalności Chrome DevTools.
"geolocation" Umożliwia rozszerzeniu korzystanie z interfejsu geolokalizacji HTML5.
"mdns" Przyznaje rozszerzeniu dostęp do interfejsu API chrome.mdns.
"proxy" Przyznaje rozszerzeniu dostęp do interfejsu API chrome.proxy, aby zarządzać ustawieniami proxy w Chrome.
"tts" Interfejs API chrome.tts odtwarza syntezę mowy (TTS).
"ttsEngine" Interfejs API chrome.ttsEngine implementuje mechanizm zamiany tekstu na mowę (TTS) za pomocą rozszerzenia.
"wallpaper" Tylko w ChromeOS. Użyj interfejsu API chrome.wallpaper, aby zmienić tapetę w ChromeOS.

Aby uzyskać więcej informacji o dostępnych uprawnieniach i ich ostrzeżeniach, otwórz Deklarację uprawnień.

Krok 3. Poproś o opcjonalne uprawnienia

Wyślij prośbę o uprawnienia w ramach działania użytkownika za pomocą 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 wyświetla użytkownikowi komunikat, jeśli dodanie uprawnień spowoduje wyświetlenie innych ostrzeżeń niż te, które użytkownik już widział i zaakceptował. Na przykład poprzedni kod może spowodować wyświetlenie promptu:

Przykład prośby o potwierdzenie uprawnień
Przykład prośby o potwierdzenie uprawnień.

Krok 4. Sprawdź bieżące uprawnienia rozszerzenia

Aby sprawdzić, czy rozszerzenie ma określone uprawnienia lub zestaw uprawnień, użyj: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.
  }
});

Krok 5. Usuń uprawnienia

Usuń uprawnienia, gdy nie są już potrzebne. Po usunięciu uprawnienia wywołanie funkcji permissions.request() zwykle powoduje przywrócenie uprawnienia bez wyświetlania prośby o potwierdzenie.

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).
  }
});

Typy

Permissions

Właściwości

  • origins

    string[] opcjonalnie

    Lista uprawnień hosta, w tym tych określonych w kluczach optional_permissions lub permissions w pliku manifestu, oraz tych powiązanych z skryptami treści.

  • uprawnienia

    string[] opcjonalnie

    Lista nazwanych uprawnień (nie obejmuje hostów ani źródeł).

Metody

addHostAccessRequest()

Promise OczekujeMV3+ 
chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

Dodaje prośbę o dostęp do hosta. Prośba zostanie przekazana użytkownikowi tylko wtedy, gdy rozszerzenie może uzyskać dostęp do hosta w ramach prośby. Żądanie zostanie zresetowane podczas nawigacji w innej domenie. Po zaakceptowaniu przyznaje stały dostęp do głównego źródła witryny

Parametry

  • żądanie

    Obiekt

    • documentId

      string opcjonalny

      Identyfikator dokumentu, w którym można wyświetlać prośby o dostęp do hosta. Musi być dokumentem najwyższego poziomu na karcie. Jeśli prośba została podana, wyświetla się ona na karcie określonego dokumentu i jest usuwana, gdy dokument przejdzie do nowego źródła. Dodanie nowego żądania spowoduje zastąpienie istniejącego żądania dotyczącego tabId. Należy określić ten parametr lub parametr tabId.

    • wzór

      string opcjonalny

      Wzór adresu URL, pod którym mogą być wyświetlane żądania dostępu do hosta. Jeśli podasz adres URL, prośby o dostęp hosta będą wyświetlane tylko w przypadku adresów URL pasujących do tego wzoru.

    • tabId

      number opcjonalny

      Identyfikator karty, na której mogą być wyświetlane żądania dostępu hosta. Jeśli jest podany, prośba jest wyświetlana na określonej karcie i usuwana, gdy karta przejdzie do nowego źródła. Dodanie nowego żądania spowoduje zastąpienie istniejącego żądania dotyczącego documentId. Należy określić ten parametr lub parametr documentId.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

contains()

Obietnice 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

Sprawdza, czy rozszerzenie ma określone uprawnienia.

Parametry

  • uprawnienia

    Uprawnienia

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (result: boolean) => void

    • wynik

      wartość logiczna

      Wartość „Prawda”, jeśli rozszerzenie ma określone uprawnienia. Jeśli pochodzenie jest określone zarówno jako opcjonalne uprawnienie, jak i wzór dopasowania skryptu treści, zwróci wartość false, chyba że oba te uprawnienia zostaną przyznane.

Zwroty

  • Promise<boolean>

    Chrome 96 i nowsze

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getAll()

Obietnice 
chrome.permissions.getAll(
  callback?: function,
)

Pobiera bieżący zestaw uprawnień rozszerzenia.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (permissions: Permissions) => void

    • uprawnienia

      Uprawnienia

      Aktywne uprawnienia rozszerzenia. Pamiętaj, że usługa origins będzie zawierać przyznane pochodzenie z tych określonych w kluczach permissions i optional_permissions w pliku manifestu oraz tych powiązanych z skryptami treści.

Zwroty

  • Promise<Permissions>

    Chrome 96 i nowsze

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

remove()

Obietnice 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

Usuwanie dostępu do określonych uprawnień. Jeśli wystąpią problemy z usunięciem uprawnień, zostanie ustawione runtime.lastError.

Parametry

  • uprawnienia

    Uprawnienia

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (removed: boolean) => void

    • usunięto

      wartość logiczna

      Wartość „prawda”, jeśli uprawnienia zostały usunięte.

Zwroty

  • Promise<boolean>

    Chrome 96 i nowsze

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

removeHostAccessRequest()

Promise OczekujeMV3+ 
chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

usuwa prośbę o dostęp do hosta, jeśli taka istnieje.

Parametry

  • żądanie

    Obiekt

    • documentId

      string opcjonalny

      Identyfikator dokumentu, z którego prośba o dostęp hosta zostanie usunięta. Musi być dokumentem najwyższego poziomu na karcie. Należy określić ten parametr lub parametr tabId.

    • wzór

      string opcjonalny

      Wzorzec adresu URL, w którym prośba o dostęp hosta zostanie usunięta. Jeśli zostanie podany, musi dokładnie odpowiadać wzorowi istniejącego żądania dostępu hosta.

    • tabId

      number opcjonalny

      Identyfikator karty, z której prośba o dostęp hosta zostanie usunięta. Należy określić ten parametr lub parametr documentId.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

request()

Obietnice 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

Prośba o dostęp do określonych uprawnień, w razie potrzeby z wyświetleniem odpowiedniego prompta. Te uprawnienia muszą być zdefiniowane w polu optional_permissions w pliku manifestu lub muszą być wymagane uprawnienia, których użytkownik nie wyraził. Ścieżki w wzorach pochodzenia są ignorowane. Możesz poprosić o podzbiór opcjonalnych uprawnień źródła. Jeśli na przykład w sekcji optional_permissions w pliku manifestu podasz wartość *://*\/*, możesz poprosić o uprawnienia http://example.com/. Jeśli wystąpią problemy z uzyskaniem uprawnień, zostanie ustawiona wartość runtime.lastError.

Parametry

  • uprawnienia

    Uprawnienia

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (granted: boolean) => void

    • przyznane

      wartość logiczna

      Wartość „prawda”, jeśli użytkownik przyznał określone uprawnienia.

Zwroty

  • Promise<boolean>

    Chrome 96 i nowsze

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Wydarzenia

onAdded

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

Wywoływane, gdy rozszerzenie uzyska nowe uprawnienia.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (permissions: Permissions) => void

onRemoved

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

Wywoływany, gdy rozszerzeniu zostanie odebrany dostęp do uprawnień.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (permissions: Permissions) => void