chrome.cookies

Opis

Używaj interfejsu API chrome.cookies do wysyłania zapytań i modyfikowania plików cookie oraz otrzymywania powiadomień o zmianach.

Uprawnienia

cookies

Plik manifestu

Aby korzystać z interfejsu cookies API, musisz zadeklarować w pliku manifestu uprawnienia „cookies” oraz uprawnienia hosta dla wszystkich hostów, których pliki cookie chcesz odczytać. Na przykład:

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

Partycjonowanie

Pliki cookie partycjonowane umożliwiają witrynie oznaczanie, że określone pliki cookie powinny być powiązane z kluczem początku klatki najwyższego poziomu. Oznacza to, że jeśli witryna A jest umieszczona w witrynie B za pomocą elementu iframe, i witryny C, partycjonowany plik cookie może mieć inną wartość w każdej z nich.

Interfejs chrome.cookies nie obsługuje partycjonowania, co oznacza, że wszystkie metody odczytują i zapisują pliki cookie ze wszystkich partycji. Metoda cookies.set() zapisuje pliki cookie w: partycję domyślną.

Szczegółowe informacje o ogólnym wpływie partycjonowania na rozszerzenia znajdziesz w artykule Miejsce na dane i pliki cookie.

Przykłady

Prosty przykład użycia interfejsu cookies API znajdziesz w katalogu examples/api/cookies. Inne przykłady i pomoc w wyświetlaniu kodu źródłowego znajdziesz w sekcji Przykłady.

Typy

Reprezentuje informacje o pliku cookie HTTP.

Właściwości

  • domena

    ciąg znaków

    Domena pliku cookie (np. „www.google.com”, „example.com”).

  • expirationDate

    liczba opcjonalnie

    Data ważności pliku cookie jako liczba sekund od początku epoki systemu UNIX. Nie dotyczy plików cookie sesji.

  • hostOnly

    wartość logiczna

    Wartość „prawda”, jeśli plik cookie jest plikiem cookie tylko dla hosta (czyli host żądania musi być identyczny z domeną pliku cookie).

  • httpOnly

    wartość logiczna

    Wartość Prawda, jeśli plik cookie jest oznaczony jako HttpOnly (czyli niedostępny dla skryptów po stronie klienta).

  • nazwa

    ciąg znaków

    Nazwa pliku cookie.

  • partitionKey

    CookiePartitionKey opcjonalnie

    Chrome w wersji 119 lub nowszej

    Klucz partycji do odczytu lub modyfikacji plików cookie z atrybutem partycjonowany.

  • ścieżka

    ciąg znaków

    Ścieżka pliku cookie.

  • sameSite

    SameSiteStatus

    Chrome w wersji 51 lub nowszej

    Stan pliku cookie w przypadku witryn na tym samym koncie (czyli czy plik cookie jest wysyłany z żądaniami z innych witryn).

  • Bezpieczny

    wartość logiczna

    Wartość True (prawda), jeśli plik cookie jest oznaczony jako bezpieczny (czyli jego zakres jest ograniczony do bezpiecznych kanałów, zazwyczaj HTTPS).

  • sesja

    wartość logiczna

    Prawda, jeśli plik cookie jest sesją, a nie trwałym plikiem cookie z datą ważności.

  • storeId

    ciąg znaków

    Identyfikator magazynu plików cookie zawierającego ten plik cookie, podany w getAllCookieStores().

  • wartość

    ciąg znaków

    Wartość pliku cookie.

CookieDetails

Chrome 88 i nowsze

Szczegóły umożliwiające identyfikację pliku cookie.

Właściwości

  • nazwa

    ciąg znaków

    Nazwa pliku cookie, do którego chcesz uzyskać dostęp.

  • partitionKey

    CookiePartitionKey opcjonalnie

    Chrome w wersji 119 lub nowszej

    Klucz partycji służący do odczytu lub modyfikowania plików cookie z atrybutem partycji.

  • storeId

    ciąg znaków opcjonalny

    Identyfikator magazynu plików cookie, w którym ma zostać wyszukany plik cookie. Domyślnie używany jest magazyn plików cookie bieżącego kontekstu wykonania.

  • URL

    ciąg znaków

    Adres URL, z którym powiązany jest plik cookie. Może to być pełny adres URL.W takim przypadku wszystkie dane następujące po ścieżce adresu URL (np. ciąg zapytania) są po prostu ignorowane. Jeśli w pliku manifestu nie określono uprawnień hosta dla tego adresu URL, wywołanie interfejsu API się nie powiedzie.

CookiePartitionKey

Chrome w wersji 119 lub nowszej

Reprezentuje klucz partycji pliku cookie partycjonowanego.

Właściwości

  • hasCrossSiteAncestor

    Wartość logiczna opcjonalna

    Chrome 130+

    Wskazuje, czy plik cookie został ustawiony w kontekście wielu witryn. Zapobiega to dostępowi witryny najwyższego poziomu umieszczonej w kontekście innych stron do plików cookie ustawionych przez witrynę najwyższego poziomu w kontekście tej samej strony.

  • topLevelSite

    ciąg znaków opcjonalny

    Witryna najwyższego poziomu, w której dostępny jest oddzielony plik cookie.

CookieStore

Reprezentuje magazyn plików cookie w przeglądarce. Na przykład okno w trybie incognito używa osobnego magazynu plików cookie niż okno bez trybu incognito.

Właściwości

  • id

    ciąg znaków

    Unikalny identyfikator magazynu plików cookie.

  • tabIds

    liczba[]

    Identyfikatory wszystkich kart przeglądarki, które korzystają z tego magazynu plików cookie.

OnChangedCause

Chrome w wersji 44 lub nowszej

Podstawowy powód zmiany pliku cookie. Jeśli plik cookie został wstawiony lub usunięty za pomocą wywołania „chrome.cookies.remove”, „cause” będzie równe „explicit”. Jeśli plik cookie został automatycznie usunięty z powodu wygaśnięcia ważności, „cause” wygaśnie. Jeśli plik cookie został usunięty, ponieważ został zastąpiony przez plik z datą wygaśnięcia, która już minęła, wartość „cause” zostanie ustawiona na „expired_overwrite”. Jeśli plik cookie został automatycznie usunięty z powodu czyszczenia pamięci, „cause” zostaną „usunięte”. Jeśli plik cookie został automatycznie usunięty z powodu „ustawienia” które ją zastąpiły: „przyczyną” to „zastąp”. Odpowiednio zaplanuj swoją odpowiedź.

Typ wyliczeniowy

„evicted”

"expired"

SameSiteStatus

Chrome w wersji 51 lub nowszej

Stan atrybutu „SameSite” pliku cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). Wartość „no_restriction” odpowiada plikowi cookie z ustawieniem „SameSite=None”, „lax” odpowiada „SameSite=Lax”, a „strict” odpowiada „SameSite=Strict”. „nieokreślony” odpowiada plikowi cookie ustawionemu bez atrybutu SameSite.

Typ wyliczeniowy

"nieokreślony"

Metody

get()

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

Pobiera informacje o pojedynczym pliku cookie. Jeśli w przypadku danego adresu URL istnieje więcej niż 1 plik cookie o tej samej nazwie, zwrócony zostanie ten z najdłuższą ścieżką. W przypadku plików cookie o takim samym długości ścieżki zwrócony zostanie plik cookie o najstarszym czasie utworzenia.

Parametry

  • szczegóły

    CookieDetails

  • wywołanie zwrotne

    funkcja optional

    Parametr callback ma postać:

    (cookie?: Cookie) => void

    • ciastko

      Plik cookie opcjonalny

      Zawiera szczegółowe informacje o pliku cookie. Ten parametr ma wartość null, jeśli nie znaleziono takiego pliku cookie.

Zwroty

  • Promise<Cookie | undefined>

    Chrome 88 i nowsze

    Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

getAll()

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

Pobiera wszystkie pliki cookie z pojedynczego magazynu plików cookie, które pasują do podanych informacji. Zwracane pliki cookie zostaną posortowane, a pierwsze będą te o najdłuższej ścieżce. Jeśli wiele plików cookie ma tę samą długość ścieżki, pierwsze będą miały te, które zostały utworzone najwcześniej. Ta metoda pobiera pliki cookie tylko z domen, do których rozszerzenie ma uprawnienia hosta.

Parametry

  • szczegóły

    Obiekt

    Informacje do filtrowania pobieranych plików cookie.

    • domena

      ciąg znaków opcjonalny

      Ogranicza pobrane pliki cookie do tych, których domeny są zgodne lub są subdomenami tego pliku.

    • nazwa

      ciąg znaków opcjonalny

      Filtruje pliki cookie według nazwy.

    • partitionKey

      Opcjonalny CookiePartitionKey

      Chrome w wersji 119 lub nowszej

      Klucz partycji służący do odczytu lub modyfikowania plików cookie z atrybutem partycji.

    • ścieżka

      ciąg znaków opcjonalny

      Ogranicza odzyskane pliki cookie do tych, których ścieżka dokładnie pasuje do tego ciągu znaków.

    • Bezpieczny

      logiczna opcjonalna

      Filtruje pliki cookie według właściwości Secure.

    • sesja

      logiczna opcjonalna

      Odfiltrowuje sesję i trwałe pliki cookie.

    • storeId

      ciąg znaków opcjonalny

      Magazyn plików cookie, z którego pobiera się pliki cookie. Jeśli nazwa zostanie pominięta, zostanie użyty magazyn plików cookie bieżącego kontekstu wykonania.

    • URL

      ciąg znaków opcjonalny

      Ogranicza pobrane pliki cookie do tych, które pasują do podanego adresu URL.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (cookies: Cookie[]) => void

    • ciastka

      Plik cookie[]

      Wszystkie istniejące, niewygasłe pliki cookie, które pasują do podanych informacji o pliku cookie.

Zwroty

  • Obietnica<Cookie[]>

    Chrome 88 lub nowszy

    Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

getAllCookieStores()

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

Wyświetla listę wszystkich istniejących magazynów plików cookie.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback wygląda tak: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      wszystkie istniejące magazyny plików cookie;

Zwroty

  • Promise<CookieStore[]>

    Chrome 88 i nowsze

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

remove()

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

Usuwa plik cookie według nazwy.

Parametry

  • szczegóły

    CookieDetails

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (details?: object) => void

    • szczegóły

      obiekt opcjonalny

      Zawiera szczegółowe informacje o usuniętym pliku cookie. Jeśli usunięcie nie powiodło się z jakiegoś powodu, wartość będzie wynosić „null”, a parametr runtime.lastError zostanie ustawiony.

      • nazwa

        ciąg znaków

        Nazwa pliku cookie, który został usunięty.

      • partitionKey

        Opcjonalny CookiePartitionKey

        Chrome w wersji 119 lub nowszej

        Klucz partycji do odczytu lub modyfikacji plików cookie z atrybutem partycjonowany.

      • storeId

        ciąg znaków

        Identyfikator magazynu plików cookie, z którego został usunięty plik cookie.

      • URL

        ciąg znaków

        Adres URL powiązany z usuniętym plikiem cookie.

Zwroty

  • Obietnica<object | niezdefiniowane>

    Chrome 88 i nowsze

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

set()

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

Ustawia plik cookie z podanymi danymi z pliku cookie. mogą zastąpić odpowiadające im pliki cookie, jeśli istnieją.

Parametry

  • szczegóły

    Obiekt

    Szczegóły dotyczące ustawianego pliku cookie.

    • domena

      ciąg znaków opcjonalny

      Domena pliku cookie. Jeśli nie zostanie podany, plik cookie stanie się plikiem cookie tylko dla gospodarza.

    • expirationDate

      liczba opcjonalnie

      Data ważności pliku cookie jako liczba sekund od początku epoki systemu UNIX. Jeśli nie zostanie podany, plik cookie stanie się plikiem cookie sesji.

    • httpOnly

      logiczna opcjonalna

      Określa, czy plik cookie ma być oznaczony jako HttpOnly. Wartość domyślna to fałsz.

    • nazwa

      ciąg znaków opcjonalny

      Nazwa pliku cookie. Domyślnie puste, jeśli pominięto.

    • partitionKey

      CookiePartitionKey opcjonalnie

      Chrome w wersji 119 lub nowszej

      Klucz partycji do odczytu lub modyfikacji plików cookie z atrybutem partycjonowany.

    • ścieżka

      ciąg znaków opcjonalny

      Ścieżka pliku cookie. Domyślnie jest to część ścieżki parametru adresu URL.

    • sameSite

      SameSiteStatus opcjonalnie

      Chrome w wersji 51 lub nowszej

      Stan pliku cookie w ramach tej samej witryny. Domyślna wartość to „nieokreślona”. Oznacza to, że w przypadku pominięcia plik cookie jest ustawiany bez określania atrybutu SameSite.

    • Bezpieczny

      Wartość logiczna opcjonalna

      Określa, czy plik cookie powinien być oznaczony jako bezpieczny. Wartość domyślna to fałsz.

    • storeId

      ciąg znaków opcjonalny

      Identyfikator magazynu plików cookie, w którym ma być ustawiony plik cookie. Domyślnie plik cookie jest ustawiany w magazynie plików cookie bieżącego kontekstu wykonania.

    • URL

      ciąg znaków

      Identyfikator URI żądania, który ma być powiązany z ustawieniem pliku cookie. Ta wartość może wpływać na domyślne wartości domeny i ścieżki utworzonego pliku cookie. Jeśli w pliku manifestu nie określono uprawnień hosta dla tego adresu URL, wywołanie interfejsu API się nie powiedzie.

    • wartość

      ciąg znaków opcjonalny

      Wartość pliku cookie. Domyślnie puste, jeśli zostanie pominięte.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback wygląda tak: 

    (cookie?: Cookie) => void

    • ciastko

      Opcjonalny plik cookie

      Zawiera szczegółowe informacje o ustawionym pliku cookie. Jeśli ustawienie nie powiedzie się z jakiegokolwiek powodu, to ustawienie będzie miało wartość „null” i zostanie ustawiona wartość runtime.lastError.

Zwroty

  • Obietnica<Cookie | nieokreślony>

    Chrome 88 i nowsze

    Obietnice są obsługiwane tylko w przypadku pliku manifestu w wersji 3 lub nowszej, na innych platformach należy używać wywołań zwrotnych.

Wydarzenia

onChanged

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

Uruchamiane, gdy plik cookie zostanie ustawiony lub usunięty. W szczególnym przypadku aktualizacja właściwości pliku cookie jest realizowana w 2 etapów: najpierw plik cookie, który ma zostać zaktualizowany, jest całkowicie usuwany, co powoduje wygenerowanie powiadomienia z wartością „cause” = „overwrite” (przyczyna = „zastąpienie”). Następnie zapisywany jest nowy plik cookie ze zaktualizowanymi wartościami, co powoduje wygenerowanie drugiego powiadomienia z komunikatem „cause” (przyczyna). „wulgaryzmy”.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback ma postać:

    (changeInfo: object) => void

    • changeInfo

      Obiekt

      • przyczyna

        OnChangedCause

        Podstawowy powód zmiany pliku cookie.

      • ciastko

        Plik cookie

        informacje o pliku cookie, który został ustawiony lub usunięty;

      • usunięto

        wartość logiczna

        Prawda, jeśli plik cookie został usunięty.