chrome.permissions

Beschrijving

Overzicht

Toestemmingswaarschuwingen beschrijven de mogelijkheden die een API biedt, maar sommige van deze waarschuwingen zijn mogelijk niet direct duidelijk. De Permissions API stelt ontwikkelaars in staat om toestemmingswaarschuwingen toe te lichten en nieuwe functies geleidelijk te introduceren, waardoor gebruikers op een risicovrije manier met de extensie kennis kunnen maken. Op deze manier kunnen gebruikers zelf aangeven hoeveel toegang ze willen verlenen en welke functies ze willen inschakelen.

De kernfunctionaliteit van de optionele machtigingsuitbreiding is bijvoorbeeld het overschrijven van de pagina voor nieuwe tabbladen. Een van de functies is het weergeven van het doel van de gebruiker voor die dag. Deze functie vereist alleen de machtiging voor opslag , waarvoor geen waarschuwing wordt gegeven. De uitbreiding heeft een extra functie die gebruikers kunnen inschakelen door op de volgende knop te klikken:

Om de meest bezochte sites van de gebruiker weer te geven, is de machtiging `topSites` vereist. Deze machtiging bevat de volgende waarschuwing.

Optionele machtigingen implementeren

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

Een extensie kan zowel verplichte als optionele machtigingen declareren. Over het algemeen geldt het volgende:

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

Voordelen van vereiste vergunningen:

• Minder meldingen: Een extensie kan de gebruiker slechts één keer vragen om alle machtigingen te accepteren.
• Eenvoudigere ontwikkeling: De benodigde machtigingen zijn gegarandeerd aanwezig.

Voordelen van optionele machtigingen:

• Betere beveiliging: Extensies werken met minder machtigingen, omdat gebruikers alleen de benodigde machtigingen inschakelen.
• Betere informatie voor gebruikers: Een extensie kan uitleggen waarom een ​​bepaalde toestemming nodig is wanneer de gebruiker de betreffende functie inschakelt.
• Eenvoudigere upgrades: Wanneer u uw extensie bijwerkt, zal Chrome deze niet uitschakelen voor uw gebruikers als de upgrade optionele in plaats van verplichte machtigingen toevoegt.

Stap 2: Declareer optionele machtigingen in het manifest

Declareer optionele machtigingen in uw extensiemanifest met de sleutel optional_permissions , in hetzelfde formaat als het veld permissions :

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

Als u hosts wilt opvragen die u pas tijdens de uitvoering ontdekt, voeg dan "https://*/*" toe aan het veld optional_host_permissions van uw extensie. Hiermee kunt u elke oorsprong in Permissions.origins specificeren, zolang deze maar een overeenkomend schema heeft.

Machtigingen die niet als optioneel kunnen worden gespecificeerd.

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

Raadpleeg 'Machtigingen declareren' en 'Gebruikers waarschuwen' voor meer informatie over beschikbare machtigingen en de bijbehorende waarschuwingen.

Stap 3: Vraag optionele machtigingen aan

Vraag de benodigde machtigingen aan vanuit een gebruikersactie 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 om bevestiging als het toevoegen van de machtigingen andere waarschuwingsberichten oplevert dan de gebruiker al heeft gezien en geaccepteerd. De bovenstaande code zou bijvoorbeeld een melding als deze kunnen opleveren:

Stap 4: Controleer de huidige machtigingen van de extensie.

Om te controleren of uw extensie een specifieke machtiging of een set 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

Je moet machtigingen verwijderen wanneer je ze niet meer nodig hebt. Nadat een machtiging is verwijderd, voegt de functie permissions.request() de machtiging meestal automatisch weer toe, 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).
  }
});

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

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

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

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

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

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

Beschrijving

Overzicht

Toestemmingswaarschuwingen beschrijven de mogelijkheden die een API biedt, maar sommige van deze waarschuwingen zijn mogelijk niet direct duidelijk. De Permissions API stelt ontwikkelaars in staat om toestemmingswaarschuwingen toe te lichten en nieuwe functies geleidelijk te introduceren, waardoor gebruikers op een risicovrije manier met de extensie kennis kunnen maken. Op deze manier kunnen gebruikers zelf aangeven hoeveel toegang ze willen verlenen en welke functies ze willen inschakelen.

De kernfunctionaliteit van de optionele machtigingsuitbreiding is bijvoorbeeld het overschrijven van de pagina voor nieuwe tabbladen. Een van de functies is het weergeven van het doel van de gebruiker voor die dag. Deze functie vereist alleen de machtiging voor opslag , waarvoor geen waarschuwing wordt gegeven. De uitbreiding heeft een extra functie die gebruikers kunnen inschakelen door op de volgende knop te klikken:

Om de meest bezochte sites van de gebruiker weer te geven, is de machtiging `topSites` vereist. Deze machtiging bevat de volgende waarschuwing.

Optionele machtigingen implementeren

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

Een extensie kan zowel verplichte als optionele machtigingen declareren. Over het algemeen geldt het volgende:

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

Voordelen van vereiste vergunningen:

• Minder meldingen: Een extensie kan de gebruiker slechts één keer vragen om alle machtigingen te accepteren.
• Eenvoudigere ontwikkeling: De benodigde machtigingen zijn gegarandeerd aanwezig.

Voordelen van optionele machtigingen:

• Betere beveiliging: Extensies werken met minder machtigingen, omdat gebruikers alleen de benodigde machtigingen inschakelen.
• Betere informatie voor gebruikers: Een extensie kan uitleggen waarom een ​​bepaalde toestemming nodig is wanneer de gebruiker de betreffende functie inschakelt.
• Eenvoudigere upgrades: Wanneer u uw extensie bijwerkt, zal Chrome deze niet uitschakelen voor uw gebruikers als de upgrade optionele in plaats van verplichte machtigingen toevoegt.

Stap 2: Declareer optionele machtigingen in het manifest

Declareer optionele machtigingen in uw extensiemanifest met de sleutel optional_permissions , in hetzelfde formaat als het veld permissions :

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

Als u hosts wilt opvragen die u pas tijdens de uitvoering ontdekt, voeg dan "https://*/*" toe aan het veld optional_host_permissions van uw extensie. Hiermee kunt u elke oorsprong in Permissions.origins specificeren, zolang deze maar een overeenkomend schema heeft.

Machtigingen die niet als optioneel kunnen worden gespecificeerd.

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

Raadpleeg 'Machtigingen declareren' en 'Gebruikers waarschuwen' voor meer informatie over beschikbare machtigingen en de bijbehorende waarschuwingen.

Stap 3: Vraag optionele machtigingen aan

Vraag de benodigde machtigingen aan vanuit een gebruikersactie 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 om bevestiging als het toevoegen van de machtigingen andere waarschuwingsberichten oplevert dan de gebruiker al heeft gezien en geaccepteerd. De bovenstaande code zou bijvoorbeeld een melding als deze kunnen opleveren:

Stap 4: Controleer de huidige machtigingen van de extensie.

Om te controleren of uw extensie een specifieke machtiging of een set 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

Je moet machtigingen verwijderen wanneer je ze niet meer nodig hebt. Nadat een machtiging is verwijderd, voegt de functie permissions.request() de machtiging meestal automatisch weer toe, 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).
  }
});

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

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

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

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

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

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