chrome.permissions

Opis

Pojęcia i zastosowanie

Ostrzeżenia o uprawnieniach opisują możliwości przyznane przez interfejs API, ale niektóre z nich mogą być nieoczywiste. Interfejs Permissions API umożliwia deweloperom wyjaśnianie ostrzeżeń dotyczących uprawnień i stopniowe wprowadzanie nowych funkcji, dzięki czemu użytkownicy mogą bez ryzyka zapoznać 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 podstawową funkcją rozszerzenia z opcjonalnymi uprawnieniami jest zastępowanie strony nowej karty. Jedną z nich jest wyświetlanie celu użytkownika na dany dzień. Ta funkcja wymaga tylko uprawnienia pamięć, które nie obejmuje ostrzeżenia. Rozszerzenie ma dodatkową funkcję, którą użytkownicy mogą włączyć, klikając ten przycisk:

Wyświetlanie najpopularniejszych witryn użytkownika wymaga uprawnienia topSites, które wiąże się z tym ostrzeżeniem:

Wdrażanie uprawnień opcjonalnych

Krok 1. Określ, 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 potrzebne do opcjonalnych funkcji w rozszerzeniu.

Zalety uprawnień wymaganych:

• Mniej próśb: rozszerzenie może poprosić użytkownika o zaakceptowanie wszystkich uprawnień tylko raz.
• Prostsze tworzenie: wymagane uprawnienia są zawsze dostępne.

Zalety uprawnień opcjonalnych:

• Większe bezpieczeństwo: rozszerzenia działają z mniejszą liczbą uprawnień, ponieważ użytkownicy włączają tylko te, 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 uaktualnianie: gdy uaktualnisz rozszerzenie, Chrome nie wyłączy go użytkownikom, jeśli uaktualnienie doda uprawnienia opcjonalne, a nie wymagane.

Krok 2. Zadeklaruj uprawnienia opcjonalne w pliku manifestu

Zadeklaruj opcjonalne uprawnienia w pliku manifestu rozszerzenia za pomocą klucza optional_permissions w tym samym formacie co pole 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 są wykrywane tylko w czasie działania, w polu optional_host_permissions rozszerzenia umieść "https://*/*". 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 wyjątkiem tych:

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

Krok 3. Poproś o opcjonalne uprawnienia

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.
  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 prośbę o potwierdzenie, jeśli dodanie uprawnień powoduje wyświetlanie 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 promptu:

Krok 4. Sprawdź bieżące uprawnienia rozszerzenia

Aby sprawdzić, czy rozszerzenie ma określone uprawnienie lub zestaw uprawnień, użyj tego kodu: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

Gdy nie będziesz już potrzebować uprawnień, usuń je. Po usunięciu uprawnienia wywołanie funkcji permissions.request() zwykle powoduje ponowne dodanie uprawnienia bez wyświetlania użytkownikowi odpowiedniego komunikatu.

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

chrome.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

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

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

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

chrome.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

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

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

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