browser.permissions

Descrizione

Utilizza l'API chrome.permissions per richiedere le autorizzazioni facoltative dichiarate in fase di runtime anziché di installazione, in modo che gli utenti capiscano perché sono necessarie e concedano solo quelle necessarie.

Concetti e utilizzo

Gli avvisi relativi alle autorizzazioni servono a descrivere le funzionalità concesse da un'API, ma alcuni di questi avvisi potrebbero non essere ovvi. L'API Permissions consente agli sviluppatori di spiegare gli avvisi relativi alle autorizzazioni e di introdurre gradualmente nuove funzionalità, offrendo agli utenti un'introduzione senza rischi all'estensione. In questo modo, gli utenti possono specificare il livello di accesso che sono disposti a concedere e le funzionalità che vogliono attivare.

Ad esempio, la funzionalità di base dell'estensione per le autorizzazioni facoltative è l'override della pagina Nuova scheda. Una funzionalità mostra l'obiettivo giornaliero dell'utente. Questa funzionalità richiede solo l'autorizzazione storage, che non include un avviso. L'estensione ha una funzionalità aggiuntiva che gli utenti possono attivare facendo clic sul seguente pulsante:

Un pulsante di estensione che attiva funzionalità aggiuntive.
Un pulsante di estensione che attiva funzionalità aggiuntive.

La visualizzazione dei siti più visitati dall'utente richiede l'autorizzazione topSites, che presenta il seguente avviso.

Avviso di estensione per l'API topSites.
Un avviso di estensione per l'API topSites

Implementa le autorizzazioni facoltative

Passaggio 1: decidi quali autorizzazioni sono obbligatorie e quali facoltative

Un'estensione può dichiarare autorizzazioni sia obbligatorie che facoltative. In generale, devi:

  • Utilizza le autorizzazioni obbligatorie quando sono necessarie per la funzionalità di base dell'estensione.
  • Utilizza le autorizzazioni facoltative quando sono necessarie per le funzionalità facoltative dell'estensione.

Vantaggi delle autorizzazioni obbligatorie:

  • Meno prompt: un'estensione può chiedere all'utente una sola volta di accettare tutte le autorizzazioni.
  • Sviluppo più semplice: è garantita la presenza delle autorizzazioni richieste.

Vantaggi delle autorizzazioni facoltative:

  • Maggiore sicurezza: le estensioni vengono eseguite con meno autorizzazioni, poiché gli utenti attivano solo quelle necessarie.
  • Informazioni migliori per gli utenti: un'estensione può spiegare perché ha bisogno di una determinata autorizzazione quando l'utente attiva la funzionalità pertinente.
  • Upgrade più semplici: quando esegui l'upgrade dell'estensione, Chrome non la disattiverà per gli utenti se l'upgrade aggiunge autorizzazioni facoltative anziché obbligatorie.

Passaggio 2: dichiara le autorizzazioni facoltative nel manifest

Dichiara le autorizzazioni facoltative nel manifest dell'estensione con la chiave optional_permissions, utilizzando lo stesso formato del campo permissions:

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

Se vuoi richiedere host che scopri solo in fase di runtime, includi "https://*/*" nel campo optional_host_permissions dell'estensione. In questo modo puoi specificare qualsiasi origine in "Permissions.origins", purché abbia uno schema corrispondente.

Autorizzazioni che non possono essere specificate come facoltative

La maggior parte delle autorizzazioni delle estensioni di Chrome può essere specificata come facoltativa, con le seguenti eccezioni.

Autorizzazione Descrizione
"debugger" L'API browser.debugger funge da trasporto alternativo per il protocollo di debug remoto di Chrome.
"declarativeNetRequest" Concede all'estensione l'accesso all'API browser.declarativeNetRequest.
"devtools" Consente all'estensione di espandere la funzionalità di Chrome DevTools.
"geolocation" Consente all'estensione di utilizzare l'API di geolocalizzazione HTML5.
"mdns" Concede all'estensione l'accesso all'API browser.mdns.
"proxy" Concede all'estensione l'accesso all'API browser.proxy per gestire le impostazioni del proxy di Chrome.
"tts" L'API browser.tts riproduce la sintesi vocale (TTS) sintetizzata.
"ttsEngine" L'API browser.ttsEngine implementa un motore di sintesi vocale (TTS) utilizzando un'estensione.
"wallpaper" Solo ChromeOS. Utilizza l'API browser.wallpaper per modificare lo sfondo di ChromeOS.

Per ulteriori informazioni sulle autorizzazioni disponibili e sui relativi avvisi, consulta Dichiarare le autorizzazioni.

Passaggio 3: richiedi le autorizzazioni facoltative

Richiedi le autorizzazioni dall'interno di un'attivazione dall'utente utilizzando 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 chiede all'utente se l'aggiunta delle autorizzazioni genera messaggi di avviso diversi da quelli che l'utente ha già visto e accettato. Ad esempio, il codice precedente potrebbe generare un prompt come questo:

Un esempio di richiesta di conferma dell'autorizzazione.
Un esempio di richiesta di conferma dell'autorizzazione.

Passaggio 4: controlla le autorizzazioni correnti dell'estensione

Per verificare se l'estensione dispone di un'autorizzazione o di un insieme di autorizzazioni specifici, utilizza permission.contains():

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

Passaggio 5: rimuovi le autorizzazioni

Ti consigliamo di rimuovere le autorizzazioni quando non ne hai più bisogno. Dopo che un'autorizzazione è stata rimossa, la chiamata a permissions.request() di solito aggiunge nuovamente l'autorizzazione senza chiedere conferma all'utente.

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

Tipi

Permissions

Proprietà

  • origins

    string[] facoltativo

    L'elenco delle autorizzazioni host, incluse quelle specificate nelle chiavi optional_permissions o permissions nel manifest e quelle associate agli script di contenuti.

  • autorizzazioni

    string[] facoltativo

    Elenco di autorizzazioni denominate (non include host o origini).

Metodi

addHostAccessRequest()

Chrome 133+ browser.* da Chrome 148 MV3+ 
browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

Aggiunge una richiesta di accesso dell'host. La richiesta verrà segnalata all'utente solo se all'estensione può essere concesso l'accesso all'host nella richiesta. La richiesta verrà reimpostata durante la navigazione multiorigine. Se accettata, concede l'accesso permanente all'origine principale del sito

Parametri

  • richiesta

    oggetto

    • documentId

      stringa facoltativa

      L'ID di un documento in cui possono essere visualizzate le richieste di accesso all'host. Deve essere il documento di primo livello all'interno di una scheda. Se fornita, la richiesta viene visualizzata nella scheda del documento specificato e viene rimossa quando il documento passa a una nuova origine. L'aggiunta di una nuova richiesta sostituirà qualsiasi richiesta esistente per tabId. È necessario specificare questo valore o tabId.

    • pattern

      stringa facoltativa

      Il pattern URL in cui possono essere visualizzate le richieste di accesso all'host. Se specificato, le richieste di accesso dell'host verranno mostrate solo sugli URL che corrispondono a questo pattern.

    • tabId

      number optional

      L'ID della scheda in cui possono essere visualizzate le richieste di accesso all'host. Se fornito, la richiesta viene mostrata nella scheda specificata e viene rimossa quando la scheda passa a una nuova origine. L'aggiunta di una nuova richiesta sostituirà una richiesta esistente per documentId. È necessario specificare questo valore o documentId.

Resi

  • Promise<void>

contains()

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

Controlla se l'estensione dispone delle autorizzazioni specificate.

Parametri

Resi

  • Promise<boolean>

    Browser Chrome 96+ .* da Chrome 148

getAll()

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

Recupera l'insieme di autorizzazioni corrente dell'estensione.

Resi

  • Promise<Permissions>

    Browser Chrome 96+ .* da Chrome 148

remove()

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

Rimuove l'accesso alle autorizzazioni specificate. Se si verificano problemi durante la rimozione delle autorizzazioni, la promise verrà rifiutata.

Parametri

Resi

  • Promise<boolean>

    Browser Chrome 96+ .* da Chrome 148

removeHostAccessRequest()

Chrome 133+ browser.* da Chrome 148 MV3+ 
browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

Rimuove una richiesta di accesso dell'host, se esistente.

Parametri

  • richiesta

    oggetto

    • documentId

      stringa facoltativa

      L'ID di un documento da cui verrà rimossa la richiesta di accesso all'host. Deve essere il documento di primo livello all'interno di una scheda. È necessario specificare questo valore o tabId.

    • pattern

      stringa facoltativa

      Il pattern URL in cui verrà rimossa la richiesta di accesso all'host. Se fornito, deve corrispondere esattamente al pattern di una richiesta di accesso all'host esistente.

    • tabId

      number optional

      L'ID della scheda in cui verrà rimossa la richiesta di accesso dell'host. È necessario specificare questo valore o documentId.

Resi

  • Promise<void>

request()

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

Richiede l'accesso alle autorizzazioni specificate, mostrando un messaggio all'utente, se necessario. Queste autorizzazioni devono essere definite nel campo optional_permissions del file manifest o essere autorizzazioni richieste che sono state negate dall'utente. I percorsi nei pattern di origine verranno ignorati. Puoi richiedere sottoinsiemi di autorizzazioni di origine facoltative; ad esempio, se specifichi *://*\/* nella sezione optional_permissions del manifest, puoi richiedere http://example.com/. Se si verificano problemi durante la richiesta delle autorizzazioni, la promise verrà rifiutata.

Parametri

Resi

  • Promise<boolean>

    Browser Chrome 96+ .* da Chrome 148

Eventi

onAdded

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

Viene attivato quando l'estensione acquisisce nuove autorizzazioni.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (permissions: Permissions) => void

onRemoved

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

Viene attivato quando l'accesso alle autorizzazioni è stato rimosso dall'estensione.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (permissions: Permissions) => void