browser.permissions

Beschrijving

Gebruik de chrome.permissions API om gedeclareerde optionele rechten aan te vragen tijdens de runtime in plaats van tijdens de installatie, zodat gebruikers begrijpen waarom de rechten nodig zijn en alleen de rechten verlenen die nodig zijn.

Concepten en gebruik

Rechtenwaarschuwingen beschrijven de mogelijkheden die een API biedt, maar sommige van deze waarschuwingen zijn misschien niet duidelijk. Met de Permissions API kunnen ontwikkelaars rechtenwaarschuwingen uitleggen en nieuwe functies geleidelijk introduceren, zodat gebruikers zonder risico kennis kunnen maken met de extensie. Zo kunnen gebruikers aangeven hoeveel toegang ze willen geven en welke functies ze willen aanzetten.

De kernfunctionaliteit van de extensie met optionele rechten is bijvoorbeeld de pagina Nieuw tabblad overschrijven. Eén functie is het weergeven van het doel van de dag van de gebruiker. Voor deze functie is alleen het recht opslag vereist. Hiervoor wordt geen waarschuwing getoond. De extensie heeft een extra functie die gebruikers kunnen aanzetten door op de volgende knop te klikken:

Een extensieknop waarmee je extra functies kunt gebruiken.

Als je de populairste sites van de gebruiker wilt tonen, heb je het recht topSites nodig. Hiervoor geldt de volgende waarschuwing.

Een extensiewaarschuwing voor de topSites API

Optionele rechten implementeren

Stap 1: Bepaal welke rechten vereist zijn en welke optioneel zijn

Een extensie kan zowel vereiste als optionele rechten declareren. In het algemeen geldt dat u het volgende moet doen:

• Gebruik vereiste rechten als ze nodig zijn voor de basisfuncties van je extensie.
• Gebruik optionele rechten als ze nodig zijn voor optionele functies in je extensie.

Voordelen van vereiste rechten:

• Minder prompts: Een extensie kan de gebruiker één keer vragen om alle rechten te accepteren.
• Eenvoudigere ontwikkeling: De vereiste rechten zijn gegarandeerd aanwezig.

Voordelen van optionele rechten:

• Betere beveiliging: Extensies worden uitgevoerd met minder rechten, omdat gebruikers alleen de rechten aanzetten die nodig zijn.
• Betere informatie voor gebruikers: Een extensie kan uitleggen waarom deze een bepaald recht nodig heeft als de gebruiker de relevante functie aanzet.
• Makkelijkere upgrades: Als je je extensie upgradet, zet Chrome deze niet uit voor je gebruikers als de upgrade optionele in plaats van vereiste rechten toevoegt.

Stap 2: Optionele rechten definiëren in het manifest

Declareer optionele rechten in je extensiemanifest met de sleutel optional_permissions, met dezelfde indeling als het veld permissions:

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

Als je hosts wilt aanvragen die je alleen tijdens de runtime ontdekt, neem je "https://*/*" op in het veld optional_host_permissions van je extensie. Zo kun je elke oorsprong in "Permissions.origins" invoeren, zolang deze een overeenkomend schema heeft.

Rechten die niet als optioneel kunnen worden gespecificeerd

De meeste rechten voor Chrome-extensies kunnen als optioneel worden gespecificeerd, met de volgende uitzonderingen.

Recht	Beschrijving
"debugger"	De API browser.debugger fungeert als een alternatief transport voor het protocol voor externe foutopsporing van Chrome.
"declarativeNetRequest"	Geeft de extensie toegang tot de browser.declarativeNetRequest API.
"devtools"	Hiermee kan de extensie de functionaliteit van Chrome DevTools uitbreiden.
"geolocation"	Hiermee kan de extensie de HTML5-API voor geolocatie gebruiken.
"mdns"	Geeft de extensie toegang tot de API browser.mdns.
"proxy"	Geeft de extensie toegang tot de browser.proxy API om de proxyinstellingen van Chrome te beheren.
"tts"	De API browser.tts speelt gesynthetiseerde tekst-naar-spraak (TTS) af.
"ttsEngine"	De browser.ttsEngine API implementeert een tekst-naar-spraak-engine (TTS) met een extensie.
"wallpaper"	Alleen ChromeOS. Gebruik de browser.wallpaper API om de ChromeOS-achtergrond te wijzigen.

Ga naar Rechten declareren voor meer informatie over beschikbare rechten en de bijbehorende waarschuwingen.

Stap 3: Optionele rechten aanvragen

Vraag de rechten aan vanuit een gebruikersactivatie met 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 vraagt de gebruiker om toestemming als de toevoeging van de rechten leidt tot andere waarschuwingsberichten dan de gebruiker al heeft gezien en geaccepteerd. De vorige code kan bijvoorbeeld resulteren in een prompt zoals deze:

Een voorbeeld van een prompt voor rechtenbevestiging.

Stap 4: Check de huidige rechten van de extensie

Gebruik permission.contains() om te controleren of je extensie een specifiek recht of een specifieke set rechten heeft:

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

Stap 5: Verwijder de rechten

Verwijder rechten als je ze niet meer nodig hebt. Nadat een recht is verwijderd, wordt het recht meestal weer toegevoegd zonder de gebruiker om toestemming te vragen als permissions.request() wordt aangeroepen.

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

Typen

Permissions

Eigenschappen

• oorsprongen

  string[] optioneel

  De lijst met hostrechten, waaronder de rechten die zijn gespecificeerd in de sleutels optional_permissions of permissions in het manifest en de rechten die zijn gekoppeld aan contentscripts.

• rechten

  string[] optioneel

  Lijst met benoemde rechten (bevat geen hosts of oorsprongen).

Methoden

addHostAccessRequest()

Chrome 133+ browser.* sinds Chrome 148 MV3+

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

Voegt een verzoek voor hosttoegang toe. Het verzoek wordt alleen aan de gebruiker gemeld als de extensie toegang kan krijgen tot de host in het verzoek. Het verzoek wordt gereset bij cross-origin-navigatie. Als de gebruiker de uitnodiging accepteert, krijgt deze permanente toegang tot de bovenste oorsprong van de site

Parameters

• verzoek

  object

  • documentId

    tekenreeks optioneel

    De ID van een document waarin verzoeken voor hosttoegang kunnen worden getoond. Moet het document op het hoogste niveau binnen een tabblad zijn. Als dit wordt verstrekt, wordt het verzoek getoond op het tabblad van het aangegeven document en verwijderd als het document naar een nieuwe oorsprong navigeert. Als je een nieuw verzoek toevoegt, wordt een bestaand verzoek voor tabId overschreven. Dit of tabId moet worden opgegeven.

  • patroon

    tekenreeks optioneel

    Het URL-patroon waar verzoeken voor hosttoegang kunnen worden getoond. Als je dit instelt, worden verzoeken voor hosttoegang alleen getoond op URL's die overeenkomen met dit patroon.

  • tabId

    number optioneel

    De ID van het tabblad waar verzoeken voor hosttoegang kunnen worden getoond. Als dit wordt verstrekt, wordt het verzoek getoond op het aangegeven tabblad en verwijderd als het tabblad naar een nieuwe oorsprong navigeert. Als je een nieuw verzoek toevoegt, wordt een bestaand verzoek voor documentId overschreven. Dit of documentId moet worden opgegeven.

Retourzendingen

• Promise<void>

contains()

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

Controleert of de extensie de aangegeven rechten heeft.

Parameters

• rechten

  Rechten

Retourzendingen

• Promise<boolean>

  Chrome 96+ browser.* sinds Chrome 148

getAll()

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

Haalt de huidige set rechten van de extensie op.

Retourzendingen

• Promise<Permissions>

  Chrome 96+ browser.* sinds Chrome 148

remove()

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

Verwijdert de toegang tot de aangegeven rechten. Als er problemen zijn met het verwijderen van de rechten, wordt de promise afgewezen.

Parameters

• rechten

  Rechten

Retourzendingen

• Promise<boolean>

  Chrome 96+ browser.* sinds Chrome 148

removeHostAccessRequest()

Chrome 133+ browser.* sinds Chrome 148 MV3+

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

Verwijdert een verzoek om hosttoegang, indien aanwezig.

Parameters

• verzoek

  object

  • documentId

    tekenreeks optioneel

    De ID van een document waarvoor het verzoek om hosttoegang wordt verwijderd. Moet het document op het hoogste niveau binnen een tabblad zijn. Dit of tabId moet worden opgegeven.

  • patroon

    tekenreeks optioneel

    Het URL-patroon waarvoor het verzoek voor hosttoegang wordt verwijderd. Als je dit opgeeft, moet het exact overeenkomen met het patroon van een bestaand verzoek voor hosttoegang.

  • tabId

    number optioneel

    De ID van het tabblad waar het verzoek om hosttoegang wordt verwijderd. Dit of documentId moet worden opgegeven.

Retourzendingen

• Promise<void>

request()

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

Vraagt toegang tot de opgegeven rechten en toont zo nodig een prompt aan de gebruiker. Deze rechten moeten worden gedefinieerd in het veld optional_permissions van het manifest of moeten vereiste rechten zijn die door de gebruiker zijn geweigerd. Paden in oorsprongspatronen worden genegeerd. Je kunt subsets van optionele oorsprongrechten aanvragen. Als je bijvoorbeeld *://*\/* opgeeft in het gedeelte optional_permissions van het manifest, kun je http://example.com/ aanvragen. Als er problemen zijn met het aanvragen van de rechten, wordt de promise afgewezen.

Parameters

• rechten

  Rechten

Retourzendingen

• Promise<boolean>

  Chrome 96+ browser.* sinds Chrome 148

Evenementen

onAdded

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

Wordt geactiveerd als de extensie nieuwe rechten krijgt.

Parameters

• callback

  functie

  De parameter callback ziet er zo uit:

  (permissions: Permissions) => void

  • rechten

    Rechten

onRemoved

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

Wordt geactiveerd als de toegang tot rechten is verwijderd uit de extensie.

Parameters

• callback

  functie

  De parameter callback ziet er zo uit:

  (permissions: Permissions) => void

  • rechten

    Rechten