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

Aby korzystać z interfejsu API plików cookie, zadeklaruj uprawnienia "cookies" w swojej manifestu wraz z uprawnieniami hosta dla wszystkich hostów, których pliki cookie chcesz skonfigurować aby uzyskać dostęp. 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 na przykład jeśli witryna A jest umieszczona za pomocą elementu iframe w witrynie B, i w witrynie C umieszczone na niej wersje partycjonowanego pliku cookie z pliku A mogą mieć różne wartości w miejscach B i C.

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

Szczegółowe informacje o ogólnym wpływie partycjonowania rozszerzeń znajdziesz w sekcji poniżej. Pamięć i pliki cookie.

Przykłady

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

Typy

Przedstawia informacje o pliku cookie HTTP.

Właściwości

  • domena

    ciąg znaków

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

  • expirationDate

    numer opcjonalny

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

  • hostOnly

    wartość logiczna

    Prawda, jeśli plik cookie jest plikiem cookie tworzonym tylko przez hosta (tj. host żądania musi dokładnie odpowiadać domenie pliku cookie).

  • httpOnly

    wartość logiczna

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

  • nazwa

    ciąg znaków

    Nazwa pliku cookie.

  • partitionKey

    Opcjonalny CookiePartitionKey

    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 tej samej witryny (tj. czy plik cookie jest wysyłany z żądaniami z różnych witryn).

  • Bezpieczny

    wartość logiczna

    Prawda, jeśli plik cookie jest oznaczony jako bezpieczny (tzn. jego zakres jest ograniczony do kanałów zabezpieczonych, zwykle 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, 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

    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 opcjonalny

    Identyfikator magazynu plików cookie, w którym ma zostać wyszukany plik cookie. Domyślnie będzie używany 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

    Oczekujący

    Wskazuje, czy plik cookie został ustawiony w kontekście wielu witryn. Dzięki temu witryna najwyższego poziomu osadzona w kontekście innej witryny nie będzie miała dostępu do plików cookie ustawionych przez witrynę najwyższego poziomu w kontekście tej samej witryny.

  • topLevelSite

    ciąg znaków opcjonalny

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

CookieStore

Reprezentuje magazyn plików cookie w przeglądarce. Na przykład okno w trybie incognito korzysta z innego magazynu plików cookie niż okno inne niż 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

Przyczyna zmiany pliku cookie. Jeśli plik cookie został wstawiony lub usunięty za pomocą jednoznacznego wywołania „chrome.cookies.remove”, „cause” będzie „wyraźny”. 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 z powodu zastąpienia nieaktualnej daty ważności, „przyczyna” 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, jako „przyczynę” to „zastąp”. Odpowiednio zaplanuj swoją odpowiedź.

Typ wyliczeniowy

SameSiteStatus

Chrome w wersji 51 lub nowszej

Atrybut „SameSite” w pliku cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). „no_restriction” odpowiada plikowi cookie ustawionemu z wartościami „SameSite=None”, „lax” na „SameSite=Lax” i „strict” na „SameSite=Strict”. „nieokreślony” odpowiada plikowi cookie ustawionemu bez atrybutu SameSite.

Typ wyliczeniowy

„strict” (ścisłe)

Metody

get()

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

Pobiera informacje o jednym pliku cookie. Jeśli dla danego adresu URL istnieje więcej niż jeden plik cookie o tej samej nazwie, zwrócony zostanie ten o najdłuższej ścieżce. W przypadku plików cookie o tej samej długości ścieżki zwracany jest plik o najwcześniejszym czasie utworzenia.

Parametry

  • szczegóły

    CookieDetails

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (cookie?: Cookie) => void
    .

    • ciastko

      Opcjonalny plik cookie

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

Zwroty

  • Promise<Cookie | niezdefiniowane>

    Chrome 88 i nowsze

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getAll()

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

Pobiera z jednego magazynu wszystkie pliki 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 tę samą długość ścieżki, pierwsze będą miały te, które zostały utworzone najwcześniej. Ta metoda pobiera tylko pliki cookie 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 do odczytu lub modyfikacji plików cookie z atrybutem Partycjonowany.

    • ścieżka

      ciąg znaków opcjonalny

      Ogranicza pobrane pliki cookie do tych, których ścieżka dokładnie odpowiada temu ciągowi.

    • Bezpieczny

      Wartość logiczna opcjonalna

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

    • sesja

      Wartość 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 i wygasłe pliki cookie, które pasują do podanych informacji o plikach cookie.

Zwroty

  • Promise<Cookie[]>

    Chrome 88 i nowsze

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getAllCookieStores()

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

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

Parametry

  • wywołanie zwrotne

    funkcja optional

    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 w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

remove()

Promise 
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 uda się z jakiegokolwiek powodu, to pole będzie miało wartość „null” i ustawi się wartość runtime.lastError.

      • nazwa

        ciąg znaków

        Nazwa usuniętego pliku cookie.

      • 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

  • Promise<object | niezdefiniowane>

    Chrome 88 i nowsze

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

set()

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

Ustawia plik cookie z podanymi danymi z pliku cookie. mogą zastąpić równoważne pliki cookie, jeśli istnieją.

Parametry

  • szczegóły

    Obiekt

    Szczegółowe informacje o ustawianiu pliku cookie.

    • domena

      ciąg znaków opcjonalny

      Domena pliku cookie. W przypadku pominięcia tego parametru plik cookie staje się dostępny tylko na potrzeby hosta.

    • expirationDate

      numer opcjonalny

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

    • httpOnly

      Wartość logiczna opcjonalna

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

    • nazwa

      ciąg znaków opcjonalny

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

    • partitionKey

      Opcjonalny CookiePartitionKey

      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

      Opcjonalny SameSiteStatus

      Chrome w wersji 51 lub nowszej

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

    • Bezpieczny

      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ć umieszczany 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 mieć wpływ 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

    funkcja optional

    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 jakiegoś powodu, wartość będzie wynosić „null” i zostanie ustawiona wartość runtime.lastError.

Zwroty

  • Promise<Cookie | niezdefiniowane>

    Chrome 88 i nowsze

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onChanged

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

Uruchamiane, gdy plik cookie zostanie ustawiony lub usunięty. Szczególny przypadek: aktualizacja właściwości pliku cookie składa się z 2 etapów. Aktualizowany plik cookie jest najpierw całkowicie usuwany, co powoduje wygenerowanie powiadomienia z informacją „przyczyna”. funkcji „zastąp” , Następnie zapisywany jest nowy plik cookie ze zaktualizowanymi wartościami, co powoduje wygenerowanie drugiego powiadomienia z komunikatem „cause”. „wulgaryzmy”.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (changeInfo: object) => void
    .

    • changeInfo

      Obiekt

      • przyczyna

        OnChangedCause

        Przyczyna zmiany pliku cookie.

      • ciastko

        Plik cookie

        Informacje o ustawionym lub usuniętym pliku cookie.

      • usunięto

        wartość logiczna

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