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, które zapewnia interfejs API, ale niektóre z tych ostrzeżeń mogą być niejasne. 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 w przypadku 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ń:

  • Większa ochrona: rozszerzenia działają z mniejszą liczbą uprawnień, ponieważ użytkownicy zezwalają tylko na te, 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 poprosić o hosty, 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 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" 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ł. Poprzedni kod może na przykład 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 między domenami. Po zaakceptowaniu przyznaje stały dostęp do głównego źródła witryny

Parametry

  • żądanie

    Obiekt

    • documentId

      ciąg znaków 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ę na karcie określonego dokumentu i jest usuwana, gdy dokument przejdzie do nowego źródła. Dodanie nowego żądania spowoduje zastąpienie dowolnego istniejącego żądania dotyczącego tabId. Należy określić ten parametr lub parametr tabId.

    • wzór

      ciąg znaków 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 do 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+

    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+

    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

      ciąg znaków 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

      ciąg znaków 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 do 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

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

Zwroty

  • Promise<boolean>

    Chrome 96+

    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 z rozszerzenia usunięto dostęp do uprawnień.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (permissions: Permissions) => void