browser.permissions

Opis

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

Pojęcia i użycie

Ostrzeżenia dotyczące uprawnień opisują możliwości, jakie daje interfejs API, ale niektóre z nich mogą nie być oczywiste. Interfejs Permissions API umożliwia deweloperom wyjaśnianie ostrzeżeń dotyczących uprawnień i stopniowe wprowadzanie nowych funkcji, co pozwala użytkownikom na bezpieczne zapoznanie się z rozszerzeniem. Dzięki temu użytkownicy mogą określić, jaki zakres dostępu chcą przyznać i które funkcje chcą włączyć.

Na przykład główną funkcjonalnością rozszerzenia z uprawnieniami opcjonalnymi jest zastępowanie strony nowej karty. Jedna z funkcji wyświetla cel użytkownika na dany dzień. Ta funkcja wymaga tylko uprawnienia storage, które nie powoduje wyświetlenia 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 przez użytkownika witryn wymaga uprawnienia topSites, które wyświetla to ostrzeżenie.

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

Implementowanie uprawnień opcjonalnych

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ń, gdy są one potrzebne do podstawowego działania rozszerzenia.
  • Używaj uprawnień opcjonalnych, gdy są one wymagane przez opcjonalne funkcje rozszerzenia.

Zalety uprawnień wymaganych:

  • Mniej próśb: rozszerzenie może raz poprosić użytkownika o zaakceptowanie wszystkich uprawnień.
  • Prostsze programowanie: wymagane uprawnienia są gwarantowane.

Zalety uprawnień opcjonalnych:

  • Większe bezpieczeństwo: rozszerzenia działają z mniejszą liczbą uprawnień, ponieważ użytkownicy włączają tylko te uprawnienia, które są potrzebne.
  • Lepsze informacje 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 u użytkowników, jeśli uaktualnienie dodaje uprawnienia opcjonalne, a nie wymagane.

Krok 2. Zadeklaruj uprawnienia opcjonalne w pliku manifestu

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

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

Jeśli chcesz wysyłać żądania do hostów, które wykrywasz tylko w czasie działania, dodaj "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 pasujący schemat.

Uprawnienia, których nie można określić jako opcjonalne

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

Uprawnienie Opis
"debugger" Interfejs API browser.debugger służy jako alternatywny transport dla protokołu zdalnego debugowania w Chrome.
"declarativeNetRequest" Przyznaje rozszerzeniu dostęp do interfejsu API browser.declarativeNetRequest.
"devtools" Umożliwia rozszerzeniu rozbudowanie funkcji Narzędzi deweloperskich w Chrome.
"geolocation" Umożliwia rozszerzeniu korzystanie z interfejsu API geolokalizacji HTML5.
"mdns" Zezwala rozszerzeniu na dostęp do interfejsu API browser.mdns.
"proxy" Zezwala rozszerzeniu na dostęp do interfejsu API browser.proxy w celu zarządzania ustawieniami serwera proxy Chrome.
"tts" Interfejs API browser.tts odtwarza syntetyzowaną mowę (TTS).
"ttsEngine" Interfejs API browser.ttsEngine implementuje mechanizm zamiany tekstu na mowę (TTS) za pomocą rozszerzenia.
"wallpaper" Tylko w systemie ChromeOS. Aby zmienić tapetę ChromeOS, użyj interfejsu API browser.wallpaper.

Więcej informacji o dostępnych uprawnieniach i ostrzeżeniach znajdziesz w artykule Deklarowanie uprawnień.

Krok 3. Poproś o uprawnienia opcjonalne

Poproś o uprawnienia w ramach gestu 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.
  browser.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świetli użytkownikowi prośbę o potwierdzenie, jeśli dodanie uprawnień spowoduje wyświetlenie innych komunikatów ostrzegawczych niż te, które użytkownik już widział i zaakceptował. Na przykład poprzedni kod może spowodować wyświetlenie takiego komunikatu:

Przykładowa prośba o potwierdzenie uprawnień.
Przykładowa prośba o potwierdzenie uprawnień.

Krok 4. Sprawdź bieżące uprawnienia rozszerzenia

Aby sprawdzić, czy rozszerzenie ma określone uprawnienie lub zestaw uprawnień, użyj permission.contains():

browser.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

Jeśli nie potrzebujesz już uprawnień, usuń je. Po usunięciu uprawnienia wywołanie permissions.request() zwykle przywraca je bez pytania użytkownika.

browser.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

  • źródła

    string[] opcjonalne

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

  • uprawnienia

    string[] opcjonalne

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

Metody

addHostAccessRequest()

Chrome 133+ browser.* od Chrome 148 MV3+ 
browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

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 wskazanego w prośbie. Żądanie zostanie zresetowane podczas nawigacji między domenami. Po zaakceptowaniu przyznaje stały dostęp do źródła najwyższego poziomu witryny.

Parametry

  • żądanie

    obiekt

    • documentId

      ciąg znaków opcjonalny

      Identyfikator dokumentu, w którym mogą być wyświetlane prośby o dostęp do hosta. Musi to być dokument najwyższego poziomu na karcie. Jeśli zostanie podany, prośba będzie wyświetlana na karcie określonego dokumentu i zostanie usunięta, gdy dokument zostanie przeniesiony do nowego źródła. Dodanie nowej prośby spowoduje zastąpienie wszystkich istniejących próśb dotyczących usługi tabId. Należy podać tę wartość lub tabId.

    • wzór

      ciąg znaków opcjonalny

      Wzorzec adresu URL, w przypadku którego mogą być wyświetlane prośby o dostęp do hosta. Jeśli podasz wzorzec, prośby o dostęp do hosta będą wyświetlane tylko w przypadku adresów URL, które do niego pasują.

    • tabId

      number optional

      Identyfikator karty, na której mogą być wyświetlane prośby o dostęp do hosta. Jeśli zostanie podany, prośba będzie wyświetlana na określonej karcie i zostanie usunięta, gdy karta przejdzie do nowego źródła. Dodanie nowej prośby spowoduje zastąpienie istniejącej prośby dotyczącej: documentId. Należy podać tę wartość lub documentId.

Zwroty

  • thought Promise<void>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

Sprawdza, czy rozszerzenie ma określone uprawnienia.

Parametry

Zwroty

  • Promise<boolean>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

getAll()

browser.permissions.getAll(): Promise<Permissions>

Pobiera bieżący zestaw uprawnień rozszerzenia.

Zwroty

  • Promise<Permissions>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

Usuwa dostęp do określonych uprawnień. Jeśli podczas usuwania uprawnień wystąpią jakiekolwiek problemy, obietnica zostanie odrzucona.

Parametry

Zwroty

  • Promise<boolean>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

removeHostAccessRequest()

Chrome 133+ browser.* od Chrome 148 MV3+ 
browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

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

Parametry

  • żądanie

    obiekt

    • documentId

      ciąg znaków opcjonalny

      Identyfikator dokumentu, z którego zostanie usunięta prośba o dostęp do hosta. Musi to być dokument najwyższego poziomu na karcie. Należy podać tę wartość lub tabId.

    • wzór

      ciąg znaków opcjonalny

      Wzorzec adresu URL, w przypadku którego prośba o dostęp do hosta zostanie usunięta. Jeśli podasz tę wartość, musi ona dokładnie odpowiadać wzorcowi istniejącej prośby o dostęp do hosta.

    • tabId

      number optional

      Identyfikator karty, z której zostanie usunięta prośba o dostęp do hosta. Należy podać tę wartość lub documentId.

Zwroty

  • thought Promise<void>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

Wysyła prośbę o dostęp do określonych uprawnień, w razie potrzeby wyświetlając użytkownikowi odpowiedni komunikat. Te uprawnienia muszą być zdefiniowane w polu optional_permissions pliku manifestu lub muszą być uprawnieniami wymaganymi, które zostały wstrzymane przez użytkownika. Ścieżki we wzorcach źródeł będą ignorowane. Możesz poprosić o podzbiory opcjonalnych uprawnień dotyczących punktu początkowego. Jeśli na przykład w sekcji optional_permissions pliku manifestu podasz *://*\/*, możesz poprosić o http://example.com/. Jeśli wystąpią problemy z prośbą o uprawnienia, obietnica zostanie odrzucona.

Parametry

Zwroty

  • Promise<boolean>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

Wydarzenia

onAdded

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

Uruchamiane, gdy rozszerzenie uzyskuje nowe uprawnienia.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (permissions: Permissions) => void

onRemoved

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

Uruchamiane, gdy uprawnienia dostępu zostaną usunięte z rozszerzenia.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (permissions: Permissions) => void