chrome.cookies

Descrizione

Utilizza l'API chrome.cookies per eseguire query e modificare i cookie, nonché per ricevere una notifica quando cambiano.

Autorizzazioni

cookies

Per utilizzare l'API dei cookie, dichiara l'autorizzazione "cookies" nel tuo manifest insieme alle autorizzazioni host per tutti gli host di cui desideri i cookie per accedere. Ad esempio:

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}

Partizionamento

I cookie partizionati consentono a un sito di contrassegnare che determinati cookie devono essere codificati in base al l'origine del frame di primo livello. Ciò significa che, ad esempio, se il sito A è incorporato utilizzando un iframe nel sito B e il sito C, le versioni incorporate di un cookie partizionato da A possono avere valori diversi su B e C.

Per impostazione predefinita, tutti i metodi dell'API operano su cookie non partizionati. La La proprietà partitionKey può essere utilizzata per eseguire l'override di questo comportamento.

Per maggiori dettagli sull'impatto generale del partizionamento per le estensioni, consulta Archiviazione e cookie.

Esempi

Puoi trovare un semplice esempio di utilizzo dell'API dei cookie nella examples/api/cookies. Per altri esempi e per assistenza nella visualizzazione il codice sorgente, consulta Esempi.

Tipi

Rappresenta informazioni su un cookie HTTP.

Proprietà

  • dominio

    stringa

    Il dominio del cookie (ad es. "www.google.com", "example.com").

  • expirationDate

    numero facoltativo

    La data di scadenza del cookie espressa come numero di secondi dall'epoca UNIX. Non fornito per i cookie di sessione.

  • hostOnly

    booleano

    True se il cookie è solo dell'host (ad esempio, l'host della richiesta deve corrispondere esattamente al dominio del cookie).

  • httpOnly

    booleano

    True se il cookie è contrassegnato come HttpOnly (ovvero, il cookie non è accessibile agli script lato client).

  • nome

    stringa

    Il nome del cookie.

  • partitionKey

    CookiePartitionKey facoltativo

    Chrome 119 e versioni successive .

    La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

  • percorso

    stringa

    Il percorso del cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 e versioni successive .

    Lo stato dello stesso sito del cookie (ovvero se il cookie viene inviato con richieste tra siti).

  • sicuro

    booleano

    True se il cookie è contrassegnato come sicuro (ossia il suo ambito è limitato a canali sicuri, in genere HTTPS).

  • sessione

    booleano

    True se il cookie è un cookie di sessione e non un cookie persistente con data di scadenza.

  • storeId

    stringa

    L'ID dell'archivio cookie contenente questo cookie, come fornito in getAllCookieStores().

  • valore

    stringa

    Il valore del cookie.

CookieDetails

Chrome 88 e versioni successive .

Dettagli per identificare il cookie.

Proprietà

  • nome

    stringa

    Il nome del cookie a cui accedere.

  • partitionKey

    CookiePartitionKey facoltativo

    Chrome 119 e versioni successive .

    La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

  • storeId

    stringa facoltativo

    L'ID dell'archivio cookie in cui cercare il cookie. Per impostazione predefinita, verrà utilizzato l'archivio cookie del contesto di esecuzione corrente.

  • url

    stringa

    L'URL a cui è associato il cookie di accesso. Questo argomento può essere un URL completo, nel qual caso tutti i dati che seguono il percorso dell'URL (ad es. la stringa di query) vengono semplicemente ignorati. Se le autorizzazioni dell'host per questo URL non sono specificate nel file manifest, la chiamata API non riuscirà.

CookiePartitionKey

Chrome 119 e versioni successive .

Rappresenta la chiave di partizione di un cookie partizionato.

Proprietà

  • hasCrossSiteAncestor

    booleano facoltativo

    In attesa

    Indica se il cookie è stato impostato in un contesto cross-cross-site. Questo impedisce a un sito di primo livello incorporato in un contesto cross-site di accedere ai cookie impostati dal sito di primo livello in un contesto dello stesso sito.

  • topLevelSite

    stringa facoltativo

    Il sito di primo livello in cui è disponibile il cookie partizionato.

CookieStore

Rappresenta un archivio cookie nel browser. Una finestra di modalità di navigazione in incognito, ad esempio, utilizza un archivio di cookie separato da una finestra di navigazione non in incognito.

Proprietà

  • id

    stringa

    L'identificatore univoco dell'archivio cookie.

  • tabIds

    numero[]

    Identificatori di tutte le schede del browser che condividono questo archivio di cookie.

OnChangedCause

Chrome 44 e versioni successive .

Il motivo alla base della modifica del cookie. Se un cookie è stato inserito o rimosso tramite una chiamata esplicita a "chrome.cookies.remove", "cause" sarà "esplicita". Se un cookie è stato rimosso automaticamente per scadenza, "cause" sarà "scaduta". Se un cookie è stato rimosso perché è stato sovrascritto con una data di scadenza già scaduta, "cause" sarà impostato su "expired_overwrite". Se un cookie è stato rimosso automaticamente a causa della garbage collection, "cause" sarà "rimosso". Se un cookie è stato rimosso automaticamente a causa di un "insieme" che lo ha sovrascritto, "causa" sarà "sovrascrittura". Pianifica la tua risposta di conseguenza.

Enum

SameSiteStatus

Chrome 51 e versioni successive .

Il "SameSite" di un cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). "no_restriction" corrisponde a un insieme di cookie con "SameSite=None", "lax" a "SameSite=Lax" e "strict" in 'SameSite=Strict'. 'non specificato' corrisponde a un insieme di cookie senza l'attributo SameSite.

Enum

Metodi

get()

Promise .
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

Recupera le informazioni su un singolo cookie. Se esiste più di un cookie con lo stesso nome per l'URL specificato, verrà restituito quello con il percorso più lungo. Per i cookie con la stessa lunghezza di percorso, verrà restituito il cookie con la prima ora di creazione.

Parametri

  • dettagli

    CookieDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (cookie?: Cookie) => void

    • biscotto

      Cookie facoltativo

      Contiene dettagli sul cookie. Questo parametro è nullo se non è stato trovato alcun cookie di questo tipo.

Resi

  • Promise<Cookie | non definito>

    Chrome 88 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.

getAll()

Promise .
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

Recupera tutti i cookie da un unico archivio di cookie che corrispondono alle informazioni fornite. I cookie restituiti verranno ordinati, partendo da quelli con il percorso più lungo. Se più cookie hanno la stessa lunghezza del percorso, quelli con l'ora di creazione meno recente saranno i primi. Questo metodo recupera i cookie solo per i domini per i quali l'estensione dispone delle autorizzazioni di host.

Parametri

  • dettagli

    oggetto

    Informazioni per filtrare i cookie recuperati.

    • dominio

      stringa facoltativo

      Limita i cookie recuperati a quelli i cui domini corrispondono o sono sottodomini di questo.

    • nome

      stringa facoltativo

      Filtra i cookie per nome.

    • partitionKey

      CookiePartitionKey facoltativo

      Chrome 119 e versioni successive

      La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

    • percorso

      stringa facoltativo

      Limita i cookie recuperati a quelli il cui percorso corrisponde esattamente a questa stringa.

    • sicuro

      booleano facoltativo

      Filtra i cookie in base alla relativa proprietà sicura.

    • sessione

      booleano facoltativo

      Esclude i cookie di sessione e quelli permanenti.

    • storeId

      stringa facoltativo

      L'archivio dei cookie da cui recuperare i cookie. Se omesso, verrà utilizzato l'archivio cookie del contesto di esecuzione corrente.

    • url

      stringa facoltativo

      Limita i cookie recuperati a quelli che corrispondono all'URL specificato.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (cookies: Cookie[]) => void

    • cookie

      Cookie[]

      Tutti i cookie esistenti e non scaduti che corrispondono alle informazioni dei cookie fornite.

Resi

  • Promise<Cookie[]>

    Chrome 88 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.

getAllCookieStores()

Promise .
chrome.cookies.getAllCookieStores(
  callback?: function,
)

Elenca tutti gli archivi di cookie esistenti.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      Tutti gli archivi di cookie esistenti.

Resi

  • Promise<CookieStore[]>

    Chrome 88 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.

remove()

Promise .
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

Elimina un cookie per nome.

Parametri

  • dettagli

    CookieDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (details?: object) => void

    • dettagli

      oggetto facoltativo

      Contiene i dettagli sul cookie che è stato rimosso. Se per qualsiasi motivo la rimozione non è andata a buon fine, il valore sarà "nullo" e verrà impostato runtime.lastError.

      • nome

        stringa

        Il nome del cookie che è stato rimosso.

      • partitionKey

        CookiePartitionKey facoltativo

        Chrome 119 e versioni successive .

        La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

      • storeId

        stringa

        L'ID dell'archivio cookie da cui è stato rimosso il cookie.

      • url

        stringa

        L'URL associato al cookie che è stato rimosso.

Resi

  • Promise<object | non definito>

    Chrome 88 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.

set()

Promise .
chrome.cookies.set(
  details: object,
  callback?: function,
)

Imposta un cookie con i dati dei cookie specificati. possono sovrascrivere i cookie equivalenti, se presenti.

Parametri

  • dettagli

    oggetto

    Dettagli sul cookie impostato.

    • dominio

      stringa facoltativo

      Il dominio del cookie. Se omesso, il cookie diventa un cookie solo dell'host.

    • expirationDate

      numero facoltativo

      La data di scadenza del cookie espressa come numero di secondi dall'epoca UNIX. Se omesso, il cookie diventa un cookie di sessione.

    • httpOnly

      booleano facoltativo

      Indica se il cookie deve essere contrassegnato come HttpOnly. Il valore predefinito è false.

    • nome

      stringa facoltativo

      Il nome del cookie. Vuota per impostazione predefinita se omessa.

    • partitionKey

      CookiePartitionKey facoltativo

      Chrome 119 e versioni successive .

      La chiave di partizione per leggere o modificare i cookie con l'attributo Partizionato.

    • percorso

      stringa facoltativo

      Il percorso del cookie. Il valore predefinito è la parte del percorso del parametro URL.

    • sameSite

      SameSiteStatus facoltativo

      Chrome 51 e versioni successive .

      Lo stato dello stesso sito del cookie. Il valore predefinito è "unspecified", ovvero, se omesso, il cookie viene impostato senza specificare un attributo SameSite.

    • sicuro

      booleano facoltativo

      Se il cookie deve essere contrassegnato come sicuro. Il valore predefinito è false.

    • storeId

      stringa facoltativo

      L'ID del datastore in cui impostare il cookie. Per impostazione predefinita, il cookie viene impostato nell'archivio cookie del contesto di esecuzione corrente.

    • url

      stringa

      L'URI della richiesta da associare all'impostazione del cookie. Questo valore può influire sui valori predefiniti di dominio e percorso del cookie creato. Se le autorizzazioni dell'host per questo URL non sono specificate nel file manifest, la chiamata API non andrà a buon fine.

    • valore

      stringa facoltativo

      Il valore del cookie. Vuota per impostazione predefinita se omessa.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (cookie?: Cookie) => void

    • biscotto

      Cookie facoltativo

      Contiene i dettagli sul cookie che è stato impostato. Se per qualsiasi motivo l'impostazione non riesce, il valore sarà "nullo" e verrà impostato runtime.lastError.

Resi

  • Promise<Cookie | non definito>

    Chrome 88 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 promessa viene risolta con lo stesso tipo passato al callback.

Eventi

onChanged

chrome.cookies.onChanged.addListener(
  callback: function,
)

Viene attivato quando un cookie viene impostato o rimosso. Come caso speciale, tieni presente che l'aggiornamento delle proprietà di un cookie è implementato come un processo in due passaggi: il cookie da aggiornare viene prima rimosso completamente, generando una notifica con "causa" di "sovrascrittura" di Google. In seguito, viene scritto un nuovo cookie con i valori aggiornati, generando una seconda notifica con "cause" "esplicita".

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (changeInfo: object) => void

    • changeInfo

      oggetto

      • Il motivo alla base della modifica del cookie.

      • biscotto

        Biscotto

        Informazioni sul cookie che è stato impostato o rimosso.

      • rimosso

        booleano

        True se un cookie è stato rimosso.