chrome.permissions

Opis

Używaj interfejsu chrome.permissions API, aby w czasie działania, a nie podczas instalacji, żądać zadeklarowanych opcjonalnych uprawnień. Dzięki temu użytkownicy będą rozumieć, do czego potrzebne są uprawnienia, i przyznają tylko niezbędne.

Pojęcia i zastosowanie

Istnieją ostrzeżenia dotyczące uprawnień, które opisują możliwości interfejsu API, ale niektóre z nich mogą nie być oczywiste. Interfejs Permissions API pozwala deweloperom objaśniać ostrzeżenia o uprawnieniach i stopniowo wprowadzać nowe funkcje, dzięki czemu użytkownicy mogą bez ryzyka wdrożyć rozszerzenie. W ten sposób użytkownicy mogą określić, jaki zakres dostępu chcą przyznać i które funkcje chcą włączyć.

Na przykład główna funkcja opcjonalnego rozszerzenia uprawnień zastępuje stronę nowej karty. Jedna z funkcji wyświetla cel dnia użytkownika. Ta funkcja wymaga tylko uprawnienia do miejsca na dane, co nie oznacza, że wyświetla się ostrzeżenie. Rozszerzenie ma dodatkową funkcję, którą użytkownicy mogą włączyć, klikając ten przycisk:

Przycisk rozszerzenia, który włącza dodatkowe funkcje.
Przycisk rozszerzenia, który włącza dodatkowe funkcje.

Aby wyświetlić najpopularniejsze witryny użytkownika, musisz mieć uprawnienie topSites, które zawiera następujące ostrzeżenie.

Ostrzeżenie o naruszeniu zasad interfejsu topSites API.
Ostrzeżenie o rozszerzeniu interfejsu API topSites

Wdrażanie uprawnień opcjonalnych

Krok 1. Określ, które uprawnienia są wymagane, a które opcjonalne

Rozszerzenie może zadeklarować zarówno wymagane, jak i opcjonalne uprawnienia. Ogólnie zalecamy:

  • Stosuj wymagane uprawnienia, gdy są potrzebne do obsługi podstawowych funkcji rozszerzenia.
  • Używaj uprawnień opcjonalnych, gdy są potrzebne do korzystania z opcjonalnych funkcji w rozszerzeniu.

Zalety uprawnień wymaganych:

  • Mniej próśb: rozszerzenie może raz wyświetlić użytkownikowi prośbę o zaakceptowanie wszystkich uprawnień.
  • Prostsze tworzenie aplikacji: wymagane uprawnienia będą zawsze dostępne.

Zalety uprawnień opcjonalnych:

  • Większe bezpieczeństwo: rozszerzenia działają z mniejszymi uprawnieniami, ponieważ użytkownicy włączają tylko te uprawnienia, które są konieczne.
  • Lepsze informacje dla użytkowników: rozszerzenie może wyjaśnić, dlaczego potrzebuje określonych uprawnień, gdy użytkownik włączy daną funkcję.
  • Łatwiejsze uaktualnienia: gdy uaktualnisz rozszerzenie, Chrome nie wyłączy go dla użytkowników, jeśli aktualizacja dodaje uprawnienia opcjonalne, a nie wymagane.

Krok 2. Zadeklaruj opcjonalne uprawnienia w pliku manifestu

Zadeklaruj opcjonalne uprawnienia w pliku manifestu rozszerzenia za pomocą klucza optional_permissions, korzystając z tego samego formatu co w przypadku pola uprawnień:

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

Jeśli chcesz wysyłać żądania hostów wykrywanych tylko w czasie działania, podaj "https://*/*" w polu optional_host_permissions rozszerzenia. Dzięki temu możesz określić w polu "Permissions.origins" dowolny punkt początkowy, o ile ma on schemat dopasowania.

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

Uprawnienia Opis
"debugger" Interfejs API chrome.debugger służy jako alternatywny transport dla protokołu zdalnego debugowania w Chrome.
"declarativeNetRequest" Przyznaje rozszerzeniu dostęp do interfejsu API chrome.declarativeNetRequest.
"devtools" Zezwala rozszerzeniu na rozwijanie funkcji Narzędzi deweloperskich w Chrome.
"geolocation" Umożliwia rozszerzeniu korzystanie z interfejsu API geolocation HTML5.
"mdns" Przyznaje rozszerzeniu dostęp do interfejsu API chrome.mdns.
"proxy" Przyznaje rozszerzeniu dostęp do interfejsu API chrome.proxy w celu zarządzania ustawieniami serwera proxy Chrome.
"tts" Interfejs API chrome.tts odtwarza tekst syntezowany na mowę (TTS).
"ttsEngine" Interfejs API chrome.ttsEngine implementuje mechanizm zamiany tekstu na mowę przy użyciu rozszerzenia.
"wallpaper" Tylko w ChromeOS. Użyj interfejsu API chrome.wallpaper, aby zmienić tapetę ChromeOS.

Więcej informacji o dostępnych uprawnieniach i związanych z nimi ostrzeżeniach znajdziesz w sekcji Deklarowanie uprawnień.

Krok 3. Poproś o opcjonalne uprawnienia

Poproś o uprawnienia gestami 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 pyta użytkownika, czy dodanie uprawnień skutkuje innymi komunikatami z ostrzeżeniem niż te, które użytkownik już zobaczył i zaakceptował. Poprzedni kod może np. wyświetlić taki komunikat:

Przykładowy komunikat z prośbą o potwierdzenie uprawnień.
Przykładowy komunikat z prośbą o potwierdzenie uprawnień.

Krok 4. Sprawdź bieżące uprawnienia rozszerzenia

Aby sprawdzić, czy rozszerzenie ma określone uprawnienia lub zestaw uprawnień, użyj polecenia 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 uprawnień wywołanie permissions.request() zwykle dodaje je z powrotem bez pytania użytkownika o zgodę.

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

  • źródła

    string[] opcjonalny

    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[] opcjonalny

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

Metody

contains()

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

Sprawdza, czy rozszerzenie ma określone uprawnienia.

Parametry

  • uprawnienia

    Uprawnienia

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (result: boolean)=>void

    • wynik

      boolean

      Prawda, jeśli rozszerzenie ma określone uprawnienia. Jeśli źródło jest określone zarówno jako uprawnienie opcjonalne, jak i jako wzorzec dopasowania skryptu treści, funkcja zwraca wartość false, chyba że przyznano oba uprawnienia.

Akcje powrotne

  • Promise<boolean>

    Chrome 96 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getAll()

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

Pobiera bieżący zestaw uprawnień rozszerzenia.

Parametry

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (permissions: Permissions)=>void

    • uprawnienia

      Uprawnienia

      Aktywne uprawnienia rozszerzenia. Pamiętaj, że właściwość origins będzie zawierać przyznane źródła pochodzące z kluczy permissions i optional_permissions w pliku manifestu oraz tych powiązanych ze skryptami treści.

Akcje powrotne

  • Obietnica<Permissions>

    Chrome 96 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

remove()

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

Usuwa dostęp do określonych uprawnień. Jeśli wystąpią problemy z usunięciem uprawnień, zostanie ustawiona wartość runtime.lastError.

Parametry

  • uprawnienia

    Uprawnienia

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (removed: boolean)=>void

    • usunięto

      boolean

      Prawda, jeśli uprawnienia zostały usunięte.

Akcje powrotne

  • Promise<boolean>

    Chrome 96 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

request()

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

Żąda dostępu do określonych uprawnień i w razie potrzeby wyświetla użytkownikowi prośbę. Te uprawnienia muszą być zdefiniowane w polu optional_permissions pliku manifestu lub być wymagane. Uprawnienia przyznane przez użytkownika. Ścieżki we wzorcach źródeł będą ignorowane. Możesz prosić o podzbiory opcjonalnych uprawnień do źródła, na przykład jeśli w sekcji optional_permissions pliku manifestu podasz *://*\/*, możesz poprosić o http://example.com/. Jeśli podczas wysyłania próśb o uprawnienia pojawią się problemy, skonfigurowana zostanie wartość runtime.lastError.

Parametry

  • uprawnienia

    Uprawnienia

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (granted: boolean)=>void

    • przyznane

      boolean

      Prawda, jeśli użytkownik przyznał określone uprawnienia.

Akcje powrotne

  • Promise<boolean>

    Chrome 96 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onAdded

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

Uruchamiane, gdy rozszerzenie uzyska nowe uprawnienia.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (permissions: Permissions)=>void

onRemoved

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

Uruchamiane po usunięciu dostępu do uprawnień z rozszerzenia.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (permissions: Permissions)=>void