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.

Omówienie

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 umożliwiający 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 interfejsu API topSites

Implementacja 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 aktualizacje: gdy zaktualizujesz rozszerzenie, Chrome nie wyłączy go dla użytkowników, jeśli aktualizacja 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 pasujący 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.
"experimental" Tylko na kanale Canary i w wersji deweloperskiej. Przyznaje rozszerzeniu dostęp do interfejsów chrome.experimental.
"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.

Więcej informacji o dostępnych uprawnieniach i ostrzeżeniach znajdziesz w artykule Oświadczanie uprawnień i ostrzeganie użytkowników.

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ładowy monit potwierdzenia 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

addSiteAccessRequest()

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

Dodaje prośbę o dostęp do witryny. Prośba zostanie przekazana użytkownikowi tylko wtedy, gdy rozszerzenie może uzyskać dostęp do witryny 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 witryny. 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, w którym mogą się wyświetlać żądania dostępu do witryny. Jeśli podasz wzór, żądania dostępu do witryny będą wyświetlane tylko w przypadku adresów URL pasujących do tego wzorca.

    • tabId

      number opcjonalny

      Identyfikator karty, na której mogą być wyświetlane żądania dostępu do witryny. 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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

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+

    Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

removeSiteAccessRequest()

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

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

Parametry

  • żądanie

    Obiekt

    • documentId

      ciąg znaków opcjonalny

      Identyfikator dokumentu, z którego prośba o dostęp do witryny 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 do witryny zostanie usunięta. Jeśli zostanie podany, musi dokładnie odpowiadać wzorowi istniejącej prośby o dostęp do witryny.

    • tabId

      number opcjonalny

      Identyfikator karty, z której prośba o dostęp do witryny 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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

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 tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

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