chrome.permissions

Descrizione

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

Concetti e utilizzo

Esistono avvisi relativi alle autorizzazioni per descrivere le funzionalità concesse da un'API, ma alcuni di questi avvisi potrebbero non essere evidenti. L'API Permissions consente agli sviluppatori di spiegare gli avvisi relativi alle autorizzazioni e di introdurre gradualmente nuove funzionalità, offrendo agli utenti un'introduzione all'estensione senza rischi. 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 delle autorizzazioni facoltative sostituisce la pagina Nuova scheda. Una funzionalità è la visualizzazione dell'obiettivo giornaliero dell'utente. Questa funzionalità richiede solo l'autorizzazione Archiviazione, 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 dell'utente richiede l'autorizzazione topSites, che presenta il seguente avviso.

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

Implementare le autorizzazioni facoltative

Passaggio 1: decidi quali autorizzazioni sono obbligatorie e quali facoltative

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

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

Vantaggi delle autorizzazioni obbligatorie:

  • Meno richieste: un'estensione può chiedere all'utente una sola volta di accettare tutte le autorizzazioni.
  • Sviluppo più semplice: le autorizzazioni richieste sono garantite.

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 disattiva per gli utenti se l'upgrade aggiunge autorizzazioni facoltative anziché obbligatorie.

Passaggio 2: dichiara le autorizzazioni facoltative nel file manifest

Dichiara le autorizzazioni facoltative nel file 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 vengono rilevati solo in fase di esecuzione, includi "https://*/*" nel campo optional_host_permissions dell'estensione. In questo modo puoi specificare qualsiasi origine in "Permissions.origins", a condizione che 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 chrome.debugger funge da metodo di trasporto alternativo per il protocollo di debug remoto di Chrome.
"declarativeNetRequest" Consente all'estensione di accedere all'API chrome.declarativeNetRequest.
"devtools" Consente all'estensione di espandere la funzionalità di Chrome DevTools.
"geolocation" Consente all'estensione di utilizzare l'API geolocalizzazione HTML5.
"mdns" Concede all'estensione l'accesso all'API chrome.mdns.
"proxy" Concede all'estensione l'accesso all'API chrome.proxy per gestire le impostazioni del proxy di Chrome.
"tts" L'API chrome.tts riproduce la sintesi vocale (TTS).
"ttsEngine" L'API chrome.ttsEngine implementa un motore di sintesi vocale (TTS) utilizzando un'estensione.
"wallpaper" Solo ChromeOS. Utilizza l'API chrome.wallpaper per cambiare lo sfondo di ChromeOS.

Visualizza Dichiara autorizzazioni per ulteriori informazioni sulle autorizzazioni disponibili e sui relativi avvisi.

Passaggio 3: richiedi le autorizzazioni facoltative

Richiedi le autorizzazioni da un gesto dell'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.
  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 chiede all'utente se l'aggiunta delle autorizzazioni comporta messaggi di avviso diversi da quelli che 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 la tua estensione dispone di un'autorizzazione o di un insieme di autorizzazioni specifiche, utilizza 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.
  }
});

Passaggio 5: rimuovi le autorizzazioni

Devi rimuovere le autorizzazioni quando non ti servono più. Dopo aver rimosso un'autorizzazione, solitamente la chiamata a permissions.request() la aggiunge di nuovo senza chiedere all'utente.

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

Tipi

Permissions

Proprietà

  • origini

    stringa[] facoltativo

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

  • autorizzazioni

    stringa[] facoltativo

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

Metodi

addHostAccessRequest()

Promessa In attesaMV3+ 
chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

Aggiunge una richiesta di accesso all'host. La richiesta verrà segnalata all'utente solo se è possibile concedere all'estensione l'accesso all'host nella richiesta. La richiesta verrà reimpostata durante la navigazione tra origini diverse. Se accettato, concede l'accesso permanente all'origine principale del sito

Parametri

  • richiesta

    oggetto

    • documentId

      stringa facoltativa

      L'ID di un documento in cui è possibile mostrare 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 mostrate le richieste di accesso all'host. Se specificato, le richieste di accesso all'host verranno mostrate solo negli URL corrispondenti a questo pattern.

    • tabId

      number facoltativo

      L'ID della scheda in cui possono essere mostrate le richieste di accesso all'host. Se fornita, 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.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

contains()

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

Controlla se l'estensione dispone delle autorizzazioni specificate.

Parametri

  • autorizzazioni

    Autorizzazioni

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: boolean) => void

    • risultato

      booleano

      True se l'estensione dispone delle autorizzazioni specificate. Se un'origine è specificata sia come autorizzazione facoltativa sia come pattern di corrispondenza dello script dei contenuti, verrà restituito false, a meno che non vengano concesse entrambe le autorizzazioni.

Resi

  • Promise<boolean>

    Chrome 96 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getAll()

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

Recupera l'insieme di autorizzazioni corrente dell'estensione.

Parametri

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (permissions: Permissions) => void

    • autorizzazioni

      Autorizzazioni

      Le autorizzazioni attive dell'estensione. Tieni presente che la proprietà origins conterrà le origini concesse da quelle specificate nelle chiavi permissions e optional_permissions nel file manifest e quelle associate a Script di contenuti.

Resi

  • Promise<Permissions>

    Chrome 96 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

remove()

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

Rimuove l'accesso alle autorizzazioni specificate. In caso di problemi con la rimozione delle autorizzazioni, verrà impostato il valore runtime.lastError.

Parametri

  • autorizzazioni

    Autorizzazioni

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (removed: boolean) => void

    • rimosso

      booleano

      Vero se le autorizzazioni sono state rimosse.

Resi

  • Promise<boolean>

    Chrome 96 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

removeHostAccessRequest()

Promessa In attesaMV3+ 
chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

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

Parametri

  • richiesta

    oggetto

    • documentId

      stringa facoltativa

      L'ID di un documento in 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 specificato, deve corrispondere esattamente al pattern di una richiesta di accesso all'host esistente.

    • tabId

      number facoltativo

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

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

request()

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

Richiede l'accesso alle autorizzazioni specificate, mostrando un messaggio all'utente, se necessario. Queste autorizzazioni devono essere definite nel campo optional_permissions del manifest o essere autorizzazioni richieste che sono state trattenute 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/. In caso di problemi con la richiesta delle autorizzazioni, verrà impostato il valore runtime.lastError.

Parametri

  • autorizzazioni

    Autorizzazioni

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (granted: boolean) => void

    • granted

      booleano

      True se l'utente ha concesso le autorizzazioni specificate.

Resi

  • Promise<boolean>

    Chrome 96 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

Eventi

onAdded

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

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