chrome.contentSettings

Descrizione

Utilizza l'API chrome.contentSettings per modificare le impostazioni che stabiliscono se i siti web possono utilizzare funzionalità quali cookie, JavaScript e plug-in. Più in generale, le impostazioni dei contenuti ti consentono di personalizzare il comportamento di Chrome in base al sito anziché a livello globale.

Autorizzazioni

contentSettings

Per usare l'API, devi dichiarare l'autorizzazione "contentSettings" nel file manifest dell'estensione. Ad esempio:

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

Concetti e utilizzo

Pattern di impostazione dei contenuti

Puoi utilizzare i pattern per specificare i siti web interessati da ogni impostazione dei contenuti. Ad esempio: https://*.youtube.com/* specifica youtube.com e tutti i relativi sottodomini. La sintassi dei contenuti è lo stesso dei pattern di corrispondenza, con alcune differenze:

  • Per gli URL http, https e ftp, il percorso deve essere un carattere jolly (/*). Per file URL, il percorso deve essere completamente specificato e non deve contenere caratteri jolly.
  • A differenza dei pattern di corrispondenza, i pattern di impostazione dei contenuti possono specificare un numero di porta. Se una porta numero specificato, il pattern associa solo i siti web con quella porta. Se non è presente alcun numero di porta specificato, il pattern corrisponde a tutte le porte.

Precedenza pattern

Se a un determinato sito si applica più di una regola di impostazione dei contenuti, viene applicata la regola con l'impostazione pattern ha la precedenza.

Ad esempio, i seguenti pattern sono ordinati per precedenza:

  1. https://www.example.com/*
  2. https://*.example.com/* (corrispondente a example.com e a tutti i sottodomini)
  3. <all_urls> (corrisponde a ogni URL)

Tre tipi di caratteri jolly influiscono sulla specificità di un pattern:

  • Caratteri jolly nella porta (ad esempio https://www.example.com:*/*)
  • Caratteri jolly nello schema (ad esempio *://www.example.com:123/*)
  • Caratteri jolly nel nome host (ad esempio https://*.example.com:123/*)

Se un pattern è più specifico di un altro in una parte ma meno specifico in un'altra, le varie parti vengono selezionate nel seguente ordine: nome host, schema, porta. Ad esempio, i seguenti pattern sono ordinati per precedenza:

  1. https://www.example.com:*/* Specifica il nome host e lo schema.
  2. *:/www.example.com:123/* Non così alto perché, sebbene specifichi il nome host, non specifica lo schema.
  3. https://*.example.com:123/* Valore minimo perché, sebbene specifichi la porta e lo schema, il nome host contiene un carattere jolly.

Pattern primari e secondari

L'URL preso in considerazione per decidere quale impostazione dei contenuti applicare dipende dal tipo di contenuti. Ad esempio, per contentSettings.notifications le impostazioni si basano sull'URL mostrato nella sezione nella omnibox. Questo URL è chiamato "principale" URL.

Alcuni tipi di contenuti possono prendere in considerazione altri URL. Ad esempio, se un sito può l'oggetto contentSettings.cookies viene deciso in base all'URL della richiesta HTTP (ovvero l'URL principale in questo caso) e l'URL mostrato nella omnibox (l'URL "secondario" URL).

Se più regole hanno pattern primari e secondari, la regola con l'impostazione principale più specifica pattern ha la precedenza. Se più regole hanno lo stesso pattern principale, la regola con un pattern secondario più specifico ha la precedenza. Ad esempio, il seguente elenco di le coppie di pattern primario/secondario sono ordinate per precedenza:

PrecedenzaSequenza principalePattern secondario
1https://www.moose.com/*,https://www.wombat.com/*
2https://www.moose.com/*,<all_urls>
3<all_urls>,https://www.wombat.com/*
4<all_urls>,<all_urls>

Identificatori di risorse

Gli identificatori di risorse consentono di specificare impostazioni dei contenuti per sottotipi specifici di un tipo di contenuto. Attualmente, l'unico tipo di contenuto che supporta gli identificatori di risorsa è contentSettings.plugins, in cui un identificatore di risorsa identifica un plug-in specifico. Quando applichi le impostazioni dei contenuti, le impostazioni del plug-in specifico. Se non sono state trovate impostazioni per l'account plug-in, vengono controllate le impostazioni generali dei contenuti dei plug-in.

Ad esempio, se una regola di impostazione dei contenuti ha l'identificatore di risorsa adobe-flash-player e <all_urls>, ha la precedenza su una regola senza un identificatore di risorsa e il pattern https://www.example.com/*, anche se questo pattern è più specifico.

Puoi ottenere un elenco di identificatori di risorse per un tipo di contenuto chiamando il metodo contentSettings.ContentSetting.getResourceIdentifiers(). L'elenco restituito può cambiare con il set di plug-in installati sul computer dell'utente, ma Chrome cerca di mantenere stabili gli identificatori tra gli aggiornamenti dei plug-in.

Esempi

Per provare questa API, installa l'esempio dell'API contentSettings da chrome-extension-samples repository Git.

Tipi

AutoVerifyContentSetting

Chrome 113 e versioni successive .

Enum

"allow"

"blocca"

CameraContentSetting

Chrome 46 e versioni successive .

Enum

"allow"

"blocca"

"chiedi"

ClipboardContentSetting

Chrome 121 e versioni successive .

Enum

"allow"

"blocca"

"chiedi"

ContentSetting

Proprietà

  • cancella

    null

    Promesso .

    Cancella tutte le regole di impostazione dei contenuti impostate da questa estensione.

    La funzione clear ha questo aspetto: 

    (details: object, callback?: function) => {...}

    • dettagli

      oggetto

      • ambito

        Ambito facoltativo

        Dove cancellare l'impostazione (impostazione predefinita: normale).

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promesso<void>

      Chrome 96 e versioni successive .

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

  • get

    null

    Promesso .

    Recupera l'impostazione dei contenuti corrente per una determinata coppia di URL.

    La funzione get ha questo aspetto: 

    (details: object, callback?: function) => {...}

    • dettagli

      oggetto

      • in incognito

        booleano facoltativo

        Indica se controllare le impostazioni dei contenuti per una sessione in incognito. (valore predefinito: false)

      • primaryUrl

        stringa

        L'URL principale per il quale deve essere recuperata l'impostazione dei contenuti. Tieni presente che il significato di un URL principale dipende dal tipo di contenuti.

      • resourceIdentifier

        ResourceIdentifier facoltativo

        Un identificatore più specifico del tipo di contenuti per cui devono essere recuperate le impostazioni.

      • secondaryUrl

        stringa facoltativo

        L'URL secondario per il quale deve essere recuperata l'impostazione dei contenuti. Il valore predefinito è l'URL principale. Tieni presente che il significato di un URL secondario dipende dal tipo di contenuti e non tutti i tipi di contenuti utilizzano URL secondari.

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto: 

      (details: object) => void

      • dettagli

        oggetto

        • impostazione

          T

          L'impostazione dei contenuti. Consulta la descrizione dei singoli oggetti ContentSetting per conoscere i valori possibili.

    • returns

      Promise&lt;object&gt;

      Chrome 96 e versioni successive .

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

  • getResourceIdentifiers

    null

    Promesso .

    La funzione getResourceIdentifiers ha questo aspetto: 

    (callback?: function) => {...}

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto: 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] facoltativo

        Un elenco di identificatori di risorsa per questo tipo di contenuto oppure undefined se questo tipo di contenuto non utilizza identificatori di risorsa.

    • returns

      Promesso<ResourceIdentifier[]>

      Chrome 96 e versioni successive .

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

  • imposta

    null

    Promesso .

    Consente di applicare una nuova regola di impostazione dei contenuti.

    La funzione set ha questo aspetto: 

    (details: object, callback?: function) => {...}

    • dettagli

      oggetto

      • primaryPattern

        stringa

        Il pattern dell'URL principale. Per informazioni dettagliate sul formato di un pattern, vedi Pattern di impostazione dei contenuti.

      • resourceIdentifier

        ResourceIdentifier facoltativo

        L'identificatore di risorsa per il tipo di contenuto.

      • ambito

        Ambito facoltativo

        Dove configurare l'impostazione (impostazione predefinita: normale).

      • secondaryPattern

        stringa facoltativo

        Il pattern dell'URL secondario. Il valore predefinito corrisponde a tutti gli URL. Per informazioni dettagliate sul formato di un pattern, vedi Pattern di impostazione dei contenuti.

      • impostazione

        qualsiasi

        L'impostazione applicata da questa regola. Consulta la descrizione dei singoli oggetti ContentSetting per conoscere i valori possibili.

    • callback

      funzione facoltativa

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promesso<void>

      Chrome 96 e versioni successive .

      Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

CookiesContentSetting

Chrome 44 e versioni successive .

Enum

"allow"

"blocca"

&quot;session_only&quot;

FullscreenContentSetting

Chrome 44 e versioni successive .

Valore

"allow"

ImagesContentSetting

Chrome 44 e versioni successive .

Enum

"allow"

"blocca"

JavascriptContentSetting

Chrome 44 e versioni successive .

Enum

"allow"

"blocca"

LocationContentSetting

Chrome 44 e versioni successive .

Enum

"allow"

"blocca"

"chiedi"

MicrophoneContentSetting

Chrome 46 e versioni successive .

Enum

"allow"

"blocca"

"chiedi"

MouselockContentSetting

Chrome 44 e versioni successive .

Valore

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 e versioni successive .

Enum

"allow"

"blocca"

"chiedi"

NotificationsContentSetting

Chrome 44 e versioni successive .

Enum

"allow"

"blocca"

"chiedi"

PluginsContentSetting

Chrome 44 e versioni successive .

Valore

"blocca"

PopupsContentSetting

Chrome 44 e versioni successive .

Enum

"allow"

"blocca"

PpapiBrokerContentSetting

Chrome 44 e versioni successive .

Valore

"blocca"

ResourceIdentifier

L'unico tipo di contenuto che utilizza gli identificatori di risorsa è contentSettings.plugins. Per saperne di più, consulta Identificatori di risorse.

Proprietà

  • descrizione

    stringa facoltativo

    Una descrizione leggibile della risorsa.

  • id

    stringa

    L'identificatore di risorsa per il tipo di contenuto specificato.

Scope

Chrome 44 e versioni successive .

L'ambito di ContentSetting. Uno di regular: impostazione del profilo normale (che viene ereditato dal profilo in incognito se non viene sostituito altrove). incognito\_session\_only: impostazione del profilo in incognito che può essere impostata soltanto durante una sessione di navigazione in incognito e viene eliminata al termine di questa sessione (sostituisce le impostazioni standard).

Enum

"regular"

"incognito_session_only"

Proprietà

automaticDownloads

Indica se consentire ai siti di scaricare automaticamente più file. Uno di allow: consenti ai siti di scaricare automaticamente più file, block: non consentire ai siti di scaricare automaticamente più file. ask: chiedi conferma quando un sito vuole scaricare automaticamente file dopo il primo file. Il valore predefinito è ask. L'URL principale è l'URL del frame di primo livello. L'URL secondario non viene utilizzato.

Tipo

ContentSetting&lt;MultipleAutomaticDownloadsContentSetting&gt;

autoVerify

Chrome 113 e versioni successive .

Indica se consentire ai siti di utilizzare l'API Private State Tokens. Uno di allow: consenti ai siti di utilizzare l'API Private State Tokens, block: impedisce ai siti di utilizzare l'API Private State Tokens. Il valore predefinito è allow. L'URL principale è l'URL del frame di primo livello. L'URL secondario non viene utilizzato. NOTA: quando chiami set(), il pattern principale deve essere .

Tipo

ContentSetting&lt;AutoVerifyContentSetting&gt;

camera

Chrome 46 e versioni successive .

Indica se consentire ai siti di accedere alla fotocamera. Uno di allow: consenti ai siti di accedere alla fotocamera; block: non consentire ai siti di accedere alla fotocamera. ask: Chiedi conferma quando un sito vuole accedere alla fotocamera. Il valore predefinito è ask. L'URL principale è l'URL del documento che ha richiesto l'accesso alla fotocamera. L'URL secondario non viene utilizzato. NOTA: il comando "allow" non è valida se entrambi i pattern sono "".

Tipo

ContentSetting&lt;CameraContentSetting&gt;

clipboard

Chrome 121 e versioni successive .

Indica se consentire ai siti di accedere agli appunti tramite le funzionalità avanzate dell'API Async Clipboard. "Avanzato" tra cui scrivere formati integrati dopo un gesto dell'utente, ad esempio la possibilità di leggere, scrivere formati personalizzati e scrivere senza un gesto dell'utente. Uno di allow: consenti ai siti di utilizzare funzionalità avanzate per gli appunti block: non consentire ai siti di utilizzare funzionalità avanzate per gli appunti, ask: Chiedi conferma quando un sito vuole utilizzare funzionalità avanzate per gli appunti. Il valore predefinito è ask. L'URL principale è l'URL del documento che ha richiesto l'accesso agli appunti. L'URL secondario non viene utilizzato.

Tipo

ContentSetting&lt;ClipboardContentSetting&gt;

cookies

Indica se consentire l'impostazione di cookie e altri dati locali da parte dei siti web. Uno di allow: accetta i cookie, block: Blocca i cookie; session\_only: accetta i cookie solo per la sessione corrente. Il valore predefinito è allow. L'URL principale è quello che rappresenta l'origine del cookie. L'URL secondario è l'URL del frame di primo livello.

Tipo

ContentSetting&lt;CookiesContentSetting&gt;

fullscreen

Obsoleta. Non ha più alcun effetto. Ora l'autorizzazione per la modalità a schermo intero viene concessa automaticamente per tutti i siti. Il valore è sempre allow.

Tipo

ContentSetting&lt;FullscreenContentSetting&gt;

images

Indica se mostrare le immagini. Uno di allow: mostra immagini, block: non mostrare immagini. Il valore predefinito è allow. L'URL principale è l'URL del frame di primo livello. L'URL secondario è l'URL dell'immagine.

Tipo

ContentSetting&lt;ImagesContentSetting&gt;

javascript

Indica se eseguire JavaScript. Uno di allow: esegui JavaScript, block: non eseguire JavaScript. Il valore predefinito è allow. L'URL principale è l'URL del frame di primo livello. L'URL secondario non viene utilizzato.

Tipo

ContentSetting&lt;JavascriptContentSetting&gt;

location

Indica se consentire la geolocalizzazione. Uno di allow: consenti ai siti di monitorare la tua posizione fisica block: non consentire ai siti di monitorare la tua posizione fisica, ask: chiedi conferma prima di consentire ai siti di monitorare la tua posizione fisica. Il valore predefinito è ask. L'URL principale è l'URL del documento che ha richiesto i dati sulla posizione. L'URL secondario è l'URL del frame di primo livello (che può essere o meno diverso dall'URL richiedente).

Tipo

ContentSetting&lt;LocationContentSetting&gt;

microphone

Chrome 46 e versioni successive .

Indica se consentire ai siti di accedere al microfono. Uno di allow: consenti ai siti di accedere al microfono block: non consentire ai siti di accedere al microfono. ask: chiedi conferma quando un sito vuole accedere al microfono. Il valore predefinito è ask. L'URL principale è quello del documento che ha richiesto l'accesso al microfono. L'URL secondario non viene utilizzato. NOTA: il comando "allow" non è valida se entrambi i pattern sono "".

Tipo

ContentSetting&lt;MicrophoneContentSetting&gt;

mouselock

Obsoleta. Non ha più alcun effetto. L'autorizzazione di blocco del mouse viene ora concessa automaticamente per tutti i siti. Il valore è sempre allow.

Tipo

ContentSetting&lt;MouselockContentSetting&gt;

notifications

Indica se consentire ai siti di mostrare notifiche desktop. Uno di allow: consenti ai siti di mostrare notifiche desktop, block: non consentire ai siti di mostrare notifiche desktop, ask: chiedi conferma quando un sito vuole mostrare le notifiche desktop. Il valore predefinito è ask. L'URL principale è l'URL del documento che vuole mostrare la notifica. L'URL secondario non viene utilizzato.

Tipo

ContentSetting&lt;NotificationsContentSetting&gt;

plugins

Obsoleta. Poiché il supporto di Flash è stato rimosso in Chrome 88, questa autorizzazione non ha più alcun effetto. Il valore è sempre block. Le chiamate a set() e clear() verranno ignorate.

Tipo

ContentSetting&lt;PluginsContentSetting&gt;

popups

Indica se consentire ai siti di mostrare popup. Uno di allow: consenti ai siti di mostrare popup block: non consentire ai siti di mostrare popup. Il valore predefinito è block. L'URL principale è l'URL del frame di primo livello. L'URL secondario non viene utilizzato.

Tipo

ContentSetting&lt;PopupsContentSetting&gt;

unsandboxedPlugins

Obsoleta. In precedenza, era possibile stabilire se consentire ai siti di eseguire plug-in senza sandbox. Tuttavia, poiché il processo del broker Flash è stato rimosso in Chrome 88, questa autorizzazione non ha più alcun effetto. Il valore è sempre block. Le chiamate a set() e clear() verranno ignorate.

Tipo

ContentSetting&lt;PpapiBrokerContentSetting&gt;