chrome.permissions

Descrizione

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

Panoramica

Esistono avvisi di autorizzazione per descrivere le funzionalità concesse da un'API, ma alcuni di questi avvisi potrebbero non essere evidenti. L'APIPermissions consente agli sviluppatori di spiegare gli avvisi di autorizzazione 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 intendono concedere e le funzionalità che vogliono abilitare.

Ad esempio, la funzionalità di base dell'estensione di autorizzazioni facoltative ha la precedenza sulla pagina Nuova scheda. Una funzionalità è visualizzare l'obiettivo della giornata dell'utente. Questa funzionalità richiede solo l'autorizzazione per lo spazio di archiviazione, che non include un avviso. L'estensione include una funzionalità aggiuntiva, che gli utenti possono attivare facendo clic sul seguente pulsante:

Pulsante estensione che attiva funzionalità aggiuntive

Per visualizzare i siti principali dell'utente è necessaria l'autorizzazione topSites, che mostra il seguente avviso.

Avviso estensione per l'API topSites

Implementazione di autorizzazioni facoltative

Passaggio 1: decidi quali autorizzazioni sono obbligatorie e quali facoltative

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

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

Vantaggi delle autorizzazioni obbligatorie:

  • Meno prompt:un'estensione può chiedere all'utente una 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 perché gli utenti attivano solo le autorizzazioni 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 i tuoi 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 trovi solo in fase di runtime, includi "https://*/*" nel campo optional_host_permissions della tua estensione. In questo modo puoi specificare qualsiasi origine in Permissions.origins, purché abbia una corrispondenza .

Autorizzazioni che non possono essere specificate come facoltative

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

Autorizzazione Descrizione
"debugger" L'API chrome.debugger funge da trasporto alternativo per il debug remoto di Chrome protocollo.
"declarativeNetRequest" Concede all'estensione l'accesso a chrome.declarativeNetRequest.
"devtools" Consente all'estensione di espandere Chrome DevTools funzionalità.
"experimental" Canary e canale Dev . Concede all'estensione l'accesso alle API chrome.experimental.
"geolocation" Consente all'estensione di utilizzare l'API di geolocalizzazione HTML5.
"mdns" Concede all'estensione l'accesso al chrome.mdns.
"proxy" Concede all'estensione l'accesso all'API chrome.proxy per gestire il proxy di Chrome impostazioni.
"tts" L'API chrome.tts riproduce le immagini sintetizzate la sintesi vocale (TTS).
"ttsEngine" L'API chrome.ttsEngine implementa una proprietà motore di sintesi vocale (TTS) che utilizza un'estensione.
"wallpaper" Solo ChromeOS. Utilizza l'API chrome.wallpaper per modificare ChromeOS sfondo.

Visualizza la pagina Dichiara le autorizzazioni e Avvisa gli utenti per ulteriori informazioni sulle autorizzazioni disponibili e i relativi avvisi.

Passaggio 3: richiedi le autorizzazioni facoltative

Richiedi le autorizzazioni dall'interno di 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 genera messaggi di avviso diversi rispetto a quelli visualizzati. che l'utente ha già visto e accettato. Ad esempio, il codice precedente potrebbe generare un prompt come questo:

esempio di richiesta di conferma dell'autorizzazione

Passaggio 4: controlla le autorizzazioni attuali dell'estensione

Per verificare se l'estensione ha un'autorizzazione o un insieme di autorizzazioni specifici, 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

Dovresti rimuovere le autorizzazioni quando non ti servono più. Dopo la rimozione di un'autorizzazione, chiamando permissions.request() in genere viene aggiunta di nuovo l'autorizzazione senza chiedere conferma 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

    string[] facoltativo

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

  • autorizzazioni

    string[] facoltativo

    Elenco di autorizzazioni con nome (non include host o origini).

Metodi

contains()

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

Controlla se l'estensione dispone delle autorizzazioni specificate.

Parametri

  • autorizzazioni

    Autorizzazioni

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: boolean) => void

    • risultato

      booleano

      True se l'estensione dispone delle autorizzazioni specificate. Se un'origine viene specificata sia come autorizzazione facoltativa sia come pattern di corrispondenza di script di 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 solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getAll()

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

Recupera l'insieme di autorizzazioni corrente dell'estensione.

Parametri

  • callback

    funzione 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 manifest e quelle associate agli script dei contenuti.

Resi

  • Promise<Permissions>

    Chrome 96 e versioni successive .

    Le promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

remove()

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

Rimuove l'accesso alle autorizzazioni specificate. Se si verificano problemi durante la rimozione delle autorizzazioni, verrà impostato runtime.lastError.

Parametri

  • autorizzazioni

    Autorizzazioni

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (removed: boolean) => void

    • rimosso

      booleano

      True se le autorizzazioni sono state rimosse.

Resi

  • Promise<boolean>

    Chrome 96 e versioni successive .

    Le promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

request()

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

Richiedi l'accesso alle autorizzazioni specificate, mostrando una richiesta all'utente, se necessario. Queste autorizzazioni devono essere definite nel campo optional_permissions del file manifest o essere autorizzazioni richieste che sono state trattenute dall'utente. I percorsi sui 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 nella richiesta delle autorizzazioni, runtime.lastError verrà impostato.

Parametri

  • autorizzazioni

    Autorizzazioni

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (granted: boolean) => void

    • concessa

      booleano

      True se l'utente ha concesso le autorizzazioni specificate.

Resi

  • Promise<boolean>

    Chrome 96 e versioni successive .

    Le promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

Eventi

onAdded

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

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,
)

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

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (permissions: Permissions) => void