chrome.cookies

Opis

Interfejs API chrome.cookies pozwala na wysyłanie zapytań i modyfikowanie plików cookie oraz otrzymywanie powiadomień o zmianach.

Uprawnienia

cookies

Aby korzystać z interfejsu cookie API, zadeklaruj w pliku manifestu uprawnienia "cookies" oraz uprawnienia hosta dla wszystkich hostów, do których pliki cookie chcesz mieć dostęp. Na przykład:

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

Partycjonowanie

Partycjonowane pliki cookie umożliwiają witrynie oznaczenie niektórych plików cookie jako klucza dostępu do źródła ramki najwyższego poziomu. Oznacza to, że jeśli na przykład witryna A jest umieszczona w witrynie B i w witrynie C przy użyciu elementu iframe, wersje umieszczonego w witrynie podzielonego pliku cookie pochodzącego z witryny A mogą mieć różne wartości w witrynach B i C.

Domyślnie wszystkie metody interfejsu API działają na niepartycjonowanych plikach cookie. Aby zastąpić to działanie, możesz użyć właściwości partitionKey.

Szczegółowe informacje na temat ogólnego wpływu partycjonowania rozszerzeń znajdziesz w sekcji Pamięć i pliki cookie.

Przykłady

Prosty przykład interfejsu API plików cookie znajdziesz w katalogu examples/api/cookies. Więcej przykładów oraz pomoc dotyczącą wyświetlania kodu źródłowego znajdziesz w sekcji Przykłady.

Typy

Reprezentuje informacje o pliku cookie HTTP.

Właściwości

  • domena

    string,

    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 UNIX. Niewykorzystywane w przypadku plików cookie sesji.

  • hostOnly

    boolean

    Wartość to „prawda”, jeśli plik cookie jest tylko hostem (tzn. host żądania musi dokładnie odpowiadać domenie pliku cookie).

  • httpOnly

    boolean

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

  • nazwa

    string,

    Nazwa pliku cookie.

  • partitionKey

    CookiePartitionKey opcjonalny

    Chrome 119 i nowsze wersje

    Klucz partycji umożliwiający odczytywanie lub modyfikowanie plików cookie z atrybutem Partycjonowanie.

  • ścieżka

    string,

    Ścieżka pliku cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 i nowsze wersje

    Stan pliku cookie w tej samej witrynie (np. czy plik cookie jest wysyłany w ramach żądań z innych witryn).

  • Bezpieczny

    boolean

    Wartość to „prawda”, jeśli plik cookie jest oznaczony jako bezpieczny (tzn. jego zakres jest ograniczony do bezpiecznych kanałów, zwykle HTTPS).

  • sesja

    boolean

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

  • storeId

    string,

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

  • value

    string,

    Wartość pliku cookie.

CookieDetails

Chrome 88 i nowsze wersje

Szczegóły identyfikujące plik cookie.

Właściwości

  • nazwa

    string,

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

  • partitionKey

    CookiePartitionKey opcjonalny

    Chrome 119 i nowsze wersje

    Klucz partycji umożliwiający odczytywanie lub modyfikowanie plików cookie z atrybutem Partycjonowanie.

  • storeId

    ciąg znaków opcjonalny

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

  • URL

    string,

    Adres URL, z którym jest powiązany plik cookie, z którym można uzyskać dostęp. Ten argument może być pełnym adresem URL.W takim przypadku wszelkie dane występujące po ścieżce adresu URL (np. ciąg zapytania) są po prostu ignorowane. Jeśli uprawnienia hosta dla tego adresu URL nie są określone w pliku manifestu, wywołanie interfejsu API się nie uda.

CookiePartitionKey

Chrome 119 i nowsze wersje

Reprezentuje klucz partycji pliku cookie z podzielonym plikiem cookie.

Właściwości

  • topLevelSite

    ciąg znaków opcjonalny

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

CookieStore

Reprezentuje magazyn plików cookie w przeglądarce. Na przykład w oknie trybu incognito znajduje się inny magazyn plików cookie niż okno trybu normalnego.

Właściwości

  • id

    string,

    Unikalny identyfikator magazynu plików cookie.

  • tabIds

    liczba[]

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

OnChangedCause

Chrome 44 i nowsze wersje

Przyczyna zmiany pliku cookie. Jeśli plik cookie został wstawiony lub usunięty przez jawne wywołanie „chrome.cookies.remove”, „powodem” będzie „dla pełnoletnich”. Jeśli plik cookie został automatycznie usunięty z powodu wygaśnięcia ważności, atrybut „powod” ma wartość „wygasł”. Jeśli plik cookie został usunięty z powodu zastąpienia jego datą ważności, która już wygasła, atrybut „cause” będzie miał wartość „expired_overwrite”. Jeśli plik cookie został automatycznie usunięty z powodu czyszczenia pamięci, parametr „cause” będzie miał wartość „wykluczone”. Jeśli plik cookie został automatycznie usunięty z powodu wywołania „set”, które go zastąpiło, „powod” to „zastąp”. Weź to pod uwagę, planując swoją odpowiedź.

Enum

"expired_overwrite"

SameSiteStatus

Chrome 51 i nowsze wersje

Stan „SameSite” pliku cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). Parametr „no_restriction” odpowiada ustawieniu „SameSite=None”, „lax” dotyczące „SameSite=Lax” i „strict” do „SameSite=Strict”. Wartość „nieokreślony” odpowiada zestawowi plików cookie bez atrybutu SameSite.

Enum

"no_restriction"

"lax"

Metody

get()

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

Pobiera informacje o pojedynczym pliku cookie. Jeśli pod danym adresem URL istnieje więcej niż 1 plik cookie o tej samej nazwie, zwracany jest ten o najdłuższej ścieżce. W przypadku plików cookie o tej samej długości ścieżki zwracany jest plik z najwcześniejszym czasem utworzenia.

Parametry

  • szczegóły

    CookieDetails

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (cookie?: Cookie)=>void

    • ciastko

      Plik cookie opcjonalnie

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

Akcje powrotne

  • Obietnica<Plik cookie|undefined>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getAll()

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

Pobiera wszystkie pliki cookie z jednego magazynu plików cookie, które pasują do podanych informacji. Zwrócone pliki cookie zostaną posortowane, zaczynając od tych o najdłuższej ścieżce. Jeśli wiele plików cookie ma taką samą długość ścieżki, jako pierwsze pojawią się pliki, które wykonano najwcześniej. Ta metoda pobiera pliki cookie tylko z domen, do których rozszerzenie ma uprawnienia hosta.

Parametry

  • szczegóły

    obiekt

    Informacje służące do filtrowania pobieranych plików cookie.

    • domena

      ciąg znaków opcjonalny

      Ogranicza pobieranie plików cookie do tych, których domeny pasują do tej domeny lub są jej subdomenami.

    • nazwa

      ciąg znaków opcjonalny

      Filtruje pliki cookie według nazwy.

    • partitionKey

      CookiePartitionKey opcjonalny

      Chrome 119 i nowsze wersje

      Klucz partycji umożliwiający odczytywanie lub modyfikowanie plików cookie z atrybutem Partycjonowanie.

    • ścieżka

      ciąg znaków opcjonalny

      Ogranicza pobrane pliki cookie do tych, których ścieżka ściśle pasuje do tego ciągu.

    • Bezpieczny

      wartość logiczna opcjonalna

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

    • sesja

      wartość logiczna opcjonalna

      Odfiltrowuje pliki cookie sesji i trwałe pliki cookie.

    • storeId

      ciąg znaków opcjonalny

      Magazyn plików cookie, z którego mają być pobierane pliki cookie. Jeśli nazwa zostanie pominięta, używany będzie magazyn plików cookie bieżącego kontekstu wykonywania.

    • URL

      ciąg znaków opcjonalny

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (cookies: Cookie[])=>void

    • ciastka

      Plik cookie[]

      Wszystkie istniejące i aktualne pliki cookie, które pasują do podanych informacji o plikach cookie.

Akcje powrotne

  • Promise<Cookie[]>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getAllCookieStores()

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

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

Parametry

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

      Wszystkie dotychczasowe magazyny plików cookie.

Akcje powrotne

  • Promise<CookieStore[]>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

remove()

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

Usuwa plik cookie według nazwy.

Parametry

  • szczegóły

    CookieDetails

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (details?: object)=>void

    • szczegóły

      obiekt opcjonalnie

      Zawiera szczegółowe informacje o usuniętym pliku cookie. Jeśli z jakiegoś powodu usunięcie nie uda się usunąć, ta wartość będzie mieć wartość „null”, a wartość runtime.lastError zostanie ustawiona.

      • nazwa

        string,

        Nazwa usuniętego pliku cookie.

      • partitionKey

        CookiePartitionKey opcjonalny

        Chrome 119 i nowsze wersje

        Klucz partycji umożliwiający odczytywanie lub modyfikowanie plików cookie z atrybutem Partycjonowanie.

      • storeId

        string,

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

      • URL

        string,

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

Akcje powrotne

  • Promise<object|undefined>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

set()

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

Ustawianie pliku cookie z podanymi danymi z pliku cookie. Może zastąpić odpowiadające mu pliki cookie, jeśli istnieją.

Parametry

  • szczegóły

    obiekt

    Szczegółowe informacje o ustawionym pliku cookie.

    • domena

      ciąg znaków opcjonalny

      Domena pliku cookie. W przypadku pominięcia tego parametru plik cookie stanie się plikiem cookie wyłącznie na poziomie hosta.

    • expirationDate

      Liczba opcjonalnie

      Data ważności pliku cookie jako liczba sekund od początku epoki UNIX. W przypadku jego pominięcia plik cookie staje się plikiem cookie sesji.

    • httpOnly

      wartość 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. Jeśli zostanie pominięty, pole domyślnie puste.

    • partitionKey

      CookiePartitionKey opcjonalny

      Chrome 119 i nowsze wersje

      Klucz partycji umożliwiający odczytywanie lub modyfikowanie plików cookie z atrybutem Partycjonowanie.

    • ścieżka

      ciąg znaków opcjonalny

      Ścieżka pliku cookie. Domyślnie jest to ścieżka parametru adresu URL.

    • sameSite

      SameSiteStatus – opcjonalny

      Chrome 51 i nowsze wersje

      Stan pliku cookie w tej samej witrynie. Wartość domyślna to „nieokreślony”, co oznacza, że jeśli zostanie pominięty, plik cookie zostanie ustawiony bez określania atrybutu SameSite.

    • Bezpieczny

      wartość logiczna opcjonalna

      Określa, czy plik cookie ma 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 zostać ustawiony plik cookie. Domyślnie plik cookie jest umieszczony w magazynie plików cookie bieżącego kontekstu wykonywania.

    • URL

      string,

      Identyfikator URI żądania powiązany z ustawieniem pliku cookie. Ta wartość może mieć wpływ na domyślne wartości domeny i ścieżek tworzonego pliku cookie. Jeśli uprawnienia hosta dla tego adresu URL nie są określone w pliku manifestu, wywołanie interfejsu API się nie uda.

    • value

      ciąg znaków opcjonalny

      Wartość pliku cookie. Jeśli zostanie pominięty, pole domyślnie puste.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (cookie?: Cookie)=>void

    • ciastko

      Plik cookie opcjonalnie

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

Akcje powrotne

  • Obietnica<Plik cookie|undefined>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onChanged

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

Uruchamiane, gdy plik cookie jest ustawiony lub usunięty. W szczególnym przypadku aktualizowanie właściwości pliku cookie jest procesem dwuetapowym: plik cookie przeznaczony do aktualizacji jest najpierw całkowicie usuwany, co powoduje wygenerowanie powiadomienia o treści „przyczyna” „zastąp” . Następnie zapisywany jest nowy plik cookie ze zaktualizowanymi wartościami, generując drugie powiadomienie z wartością „cause” „explicit”.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (changeInfo: object)=>void

    • changeInfo

      obiekt

      • Przyczyna zmiany pliku cookie.

      • ciastko

        Plik cookie

        Informacje o ustawionym lub usuniętym pliku cookie.

      • usunięto

        boolean

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