chrome.permissions

Beschrijving

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

Concepten en gebruik

Er bestaan ​​toestemmingswaarschuwingen om de mogelijkheden te beschrijven die door een API worden verleend, maar sommige van deze waarschuwingen zijn misschien niet voor de hand liggend. Met de Permissions API kunnen ontwikkelaars toestemmingswaarschuwingen uitleggen en geleidelijk nieuwe functies introduceren, waardoor gebruikers een risicovrije introductie tot de extensie krijgen. Op deze manier kunnen gebruikers opgeven hoeveel toegang ze willen verlenen en welke functies ze willen inschakelen.

De kernfunctionaliteit van de optionele machtigingsextensie overschrijft bijvoorbeeld de nieuwe tabbladpagina. Eén functie is het weergeven van het doel van de dag van de gebruiker. Voor deze functie zijn alleen opslagrechten vereist, die geen waarschuwing bevatten. De extensie heeft een extra functie die gebruikers kunnen inschakelen door op de volgende knop te klikken:

Een uitbreidingsknop die extra functies mogelijk maakt.
Een uitbreidingsknop die extra functies mogelijk maakt.

Voor het weergeven van de topsites van de gebruiker is de toestemming topSites vereist, die de volgende waarschuwing bevat.

Waarschuwing voor verlenging van de topSites API.
Een extensiewaarschuwing voor topSites API

Implementeer optionele machtigingen

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

Een extensie kan zowel vereiste als optionele machtigingen declareren. Over het algemeen moet u:

  • Gebruik de vereiste machtigingen wanneer deze nodig zijn voor de basisfunctionaliteit van uw extensie.
  • Gebruik optionele machtigingen wanneer deze nodig zijn voor optionele functies in uw extensie.

Voordelen van vereiste machtigingen:

  • Minder prompts: een extensie kan de gebruiker één keer vragen om alle machtigingen te accepteren.
  • Eenvoudiger ontwikkelen: de vereiste machtigingen zijn gegarandeerd aanwezig.

Voordelen van optionele machtigingen:

  • Betere beveiliging: Extensies worden uitgevoerd met minder machtigingen, omdat gebruikers alleen machtigingen inschakelen die nodig zijn.
  • Betere informatie voor gebruikers: Een extensie kan uitleggen waarom deze een bepaalde toestemming nodig heeft wanneer de gebruiker de betreffende functie inschakelt.
  • Gemakkelijkere upgrades: wanneer u uw extensie upgradet, schakelt Chrome deze niet uit voor uw gebruikers als de upgrade optionele rechten toevoegt in plaats van vereiste rechten.

Stap 2: Declareer optionele machtigingen in het manifest

Declareer optionele machtigingen in uw extensiemanifest met de optional_permissions sleutel, met dezelfde indeling als het machtigingsveld :

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

Als u hosts wilt aanvragen die u alleen tijdens runtime ontdekt, neemt u "https://*/*" op in het veld optional_host_permissions van uw extensie. Hiermee kunt u elke oorsprong in "Permissions.origins" opgeven, zolang deze maar een overeenkomend schema heeft.

Machtigingen die niet als optioneel kunnen worden opgegeven

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

Toestemming Beschrijving
"debugger" De chrome.debugger API dient als alternatief transport voor het protocol voor foutopsporing op afstand van Chrome.
"declarativeNetRequest" Verleent de extensie toegang tot de chrome.declarativeNetRequest API.
"devtools" Staat extensie toe om de Chrome DevTools- functionaliteit uit te breiden.
"geolocation" Hiermee kan de extensie de HTML5- geolocatie- API gebruiken.
"mdns" Verleent de extensie toegang tot de chrome.mdns API.
"proxy" Verleent de extensie toegang tot de chrome.proxy API om de proxy-instellingen 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 behulp van een extensie.
"wallpaper" Alleen ChromeOS . Gebruik de chrome.wallpaper API om de ChromeOS-achtergrond te wijzigen.

Bekijk Declare Permissions voor meer informatie over beschikbare machtigingen en de bijbehorende waarschuwingen.

Stap 3: Vraag optionele machtigingen aan

Vraag de machtigingen aan vanuit een gebruikersgebaar met behulp van 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 of het toevoegen van de rechten resulteert in andere waarschuwingsberichten dan de gebruiker al heeft gezien en geaccepteerd. De vorige code kan bijvoorbeeld resulteren in een prompt als deze:

Een voorbeeld van een toestemmingsbevestigingsprompt.
Een voorbeeld van een toestemmingsbevestigingsprompt.

Stap 4: Controleer de huidige rechten van de extensie

Om te controleren of uw extensie een specifieke machtiging of een reeks machtigingen heeft, gebruikt u 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.
  }
});

Stap 5: Verwijder de machtigingen

U moet machtigingen verwijderen wanneer u deze niet langer nodig heeft. Nadat een machtiging is verwijderd, wordt door het aanroepen permissions.request() de machtiging doorgaans weer toegevoegd 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).
  }
});

Soorten

Permissions

Eigenschappen

  • oorsprong

    tekenreeks[] optioneel

    De lijst met hostmachtigingen, inclusief de machtigingen die zijn opgegeven in de optional_permissions of permissions in het manifest, en de machtigingen die zijn gekoppeld aan Content Scripts .

  • machtigingen

    tekenreeks[] optioneel

    Lijst met benoemde machtigingen (exclusief hosts of oorsprong).

Methoden

addHostAccessRequest()

Belofte in afwachting van MV3+
chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

Voegt een hosttoegangsverzoek toe. Verzoek wordt alleen aan de gebruiker gesignaleerd als in het verzoek toegang tot de host kan worden verleend. Verzoek wordt gereset bij cross-origin-navigatie. Indien geaccepteerd, wordt permanente toegang verleend tot de belangrijkste oorsprong van de site

Parameters

  • verzoek

    voorwerp

    • documentId

      tekenreeks optioneel

      De id van een document waarin verzoeken om hosttoegang kunnen worden weergegeven. Moet het document op het hoogste niveau binnen een tabblad zijn. Indien opgegeven, wordt het verzoek weergegeven op het tabblad van het opgegeven document en verwijderd wanneer het document naar een nieuwe oorsprong navigeert. Als u een nieuw verzoek toevoegt, wordt elk bestaand verzoek voor tabId overschreven. Dit of tabId moet worden opgegeven.

    • patroon

      tekenreeks optioneel

      Het URL-patroon waar hosttoegangsverzoeken kunnen worden weergegeven. Indien opgegeven, worden hosttoegangsverzoeken alleen weergegeven op URL's die overeenkomen met dit patroon.

    • tabId

      nummer optioneel

      De id van het tabblad waar hosttoegangsverzoeken kunnen worden weergegeven. Indien opgegeven, wordt het verzoek op het opgegeven tabblad weergegeven en verwijderd wanneer het tabblad naar een nieuwe oorsprong navigeert. Als u een nieuw verzoek toevoegt, wordt een bestaand verzoek om documentId overschreven. Deze of documentId moet worden opgegeven.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

contains()

Belofte
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

Controleert of de extensie de opgegeven rechten heeft.

Parameters

  • machtigingen

    Machtigingen

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (result: boolean) => void

    • resultaat

      Booleaans

      Waar als de extensie de opgegeven machtigingen heeft. Als een oorsprong is opgegeven als zowel een optionele machtiging als een overeenkomstpatroon voor het inhoudsscript, retourneert dit false tenzij beide machtigingen zijn verleend.

Retouren

  • Beloof<boolean>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

getAll()

Belofte
chrome.permissions.getAll(
  callback?: function,
)

Haalt de huidige set machtigingen van de extensie op.

Parameters

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (permissions: Permissions) => void

    • machtigingen

      Machtigingen

      De actieve rechten van de extensie. Houd er rekening mee dat de eigenschap origins toegekende oorsprongen bevat van de bronnen die zijn opgegeven in de permissions en optional_permissions sleutels in het manifest en die zijn gekoppeld aan inhoudsscripts .

Retouren

  • Beloof < Toestemmingen >

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

remove()

Belofte
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

Verwijdert de toegang tot de opgegeven machtigingen. Als er problemen zijn bij het verwijderen van de machtigingen, wordt runtime.lastError ingesteld.

Parameters

  • machtigingen

    Machtigingen

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (removed: boolean) => void

    • VERWIJDERD

      Booleaans

      Waar als de machtigingen zijn verwijderd.

Retouren

  • Beloof<boolean>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

removeHostAccessRequest()

Belofte in behandeling MV3+
chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

Verwijdert een verzoek om hosttoegang, indien aanwezig.

Parameters

  • verzoek

    voorwerp

    • documentId

      tekenreeks optioneel

      De ID van een document waarvan het hosttoegangsverzoek 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 waar het hosttoegangsverzoek wordt verwijderd. Indien opgegeven, moet dit exact overeenkomen met het patroon van een bestaand hosttoegangsverzoek.

    • tabId

      nummer optioneel

      De ID van het tabblad waar het hosttoegangsverzoek wordt verwijderd. Deze of documentId moet worden opgegeven.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

request()

Belofte
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

Vraagt ​​toegang tot de opgegeven machtigingen en geeft indien nodig een prompt aan de gebruiker weer. Deze machtigingen moeten worden gedefinieerd in het veld optional_permissions van het manifest, of het moeten vereiste machtigingen zijn die door de gebruiker zijn ingehouden. Paden op oorsprongspatronen worden genegeerd. U kunt subsets van optionele oorsprongsmachtigingen aanvragen; Als u bijvoorbeeld *://*\/* opgeeft in de sectie optional_permissions van het manifest, kunt u http://example.com/ aanvragen. Als er problemen zijn bij het aanvragen van de machtigingen, wordt runtime.lastError ingesteld.

Parameters

  • machtigingen

    Machtigingen

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (granted: boolean) => void

    • toegekend

      Booleaans

      Waar als de gebruiker de opgegeven machtigingen heeft verleend.

Retouren

  • Beloof<boolean>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

Evenementen

onAdded

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

Wordt geactiveerd wanneer de extensie nieuwe machtigingen verkrijgt.

Parameters

  • terugbellen

    functie

    De callback parameter ziet er als volgt uit: 

    (permissions: Permissions) => void

onRemoved

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

Wordt geactiveerd wanneer de toegang tot machtigingen uit de extensie is verwijderd.

Parameters

  • terugbellen

    functie

    De callback parameter ziet er als volgt uit: 

    (permissions: Permissions) => void