chrome.permissions

refresh date: 2026-09-25 robots: noindex

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.

Overzicht

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 voor 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:

Extensieknop die aanvullende functies aanzet

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

Extensiewaarschuwing voor 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 pas tijdens de runtime ontdekt, neem je "https://*/*" op in het veld optional_host_permissions van je extensie. Zo kun je elke oorsprong opgeven in Permissions.origins, 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 chrome.debugger dient als alternatief transport voor het protocol voor externe foutopsporing van Chrome.
"declarativeNetRequest" Geeft de extensie toegang tot de chrome.declarativeNetRequest API.
"devtools" Hiermee kan de extensie de functionaliteit van Chrome DevTools uitbreiden.
"experimental" Alleen Canary- en Dev-kanaal. Geeft de extensie toegang tot chrome.experimental API's.
"geolocation" Hiermee kan de extensie de HTML5-API voor geolocatie gebruiken.
"mdns" Geeft de extensie toegang tot de chrome.mdns API.
"proxy" Geeft de extensie toegang tot de chrome.proxy API om de proxyinstellingen van Chrome te beheren.
"tts" De chrome.tts API speelt gesynthetiseerde tekst-naar-spraak (TTS) af.
"ttsEngine" De chrome.ttsEngine API implementeert een tekst-naar-spraak-engine (TTS) met een extensie.

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

Stap 3: Optionele rechten aanvragen

Vraag de rechten aan vanuit een gebruikersgebaar 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.
  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 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 leiden tot een prompt zoals deze:

voorbeeld van een prompt voor toestemmingsbevestiging

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:

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

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 als permissions.request() wordt aangeroepen, zonder dat de gebruiker hierom wordt gevraagd.

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

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

contains()

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

Controleert of de extensie de aangegeven rechten heeft.

Parameters

  • rechten
  • callback

    functie optioneel

    De parameter callback ziet er zo uit:

    (result: boolean) => void

    • resultaat

      booleaans

      True als de extensie de aangegeven rechten heeft. Als een oorsprong is opgegeven als zowel een optioneel recht als een overeenkomstpatroon voor contentscripts, wordt false geretourneerd, tenzij beide rechten zijn verleend.

Retourzendingen

  • Promise<boolean>

    Chrome 96+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

getAll()

Promise
chrome.permissions.getAll(
  callback?: function,
)
: Promise<Permissions>

Haalt de huidige set rechten van de extensie op.

Parameters

  • callback

    functie optioneel

    De parameter callback ziet er zo uit:

    (permissions: Permissions) => void

    • rechten

      De actieve rechten van de extensie. De property origins bevat toegestane herkomsten van de herkomsten die zijn opgegeven in de sleutels permissions en optional_permissions in het manifest en de herkomsten die zijn gekoppeld aan contentscripts.

Retourzendingen

  • Promise<Permissions>

    Chrome 96+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

remove()

Promise
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)
: 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
  • callback

    functie optioneel

    De parameter callback ziet er zo uit:

    (removed: boolean) => void

    • verwijderd

      booleaans

      True als de rechten zijn verwijderd.

Retourzendingen

  • Promise<boolean>

    Chrome 96+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

request()

Promise
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)
: 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 ingehouden. 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
  • callback

    functie optioneel

    De parameter callback ziet er zo uit:

    (granted: boolean) => void

    • verleend

      booleaans

      True als de gebruiker de aangegeven rechten heeft gegeven.

Retourzendingen

  • Promise<boolean>

    Chrome 96+

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

Evenementen

onAdded

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

onRemoved

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