chrome.cookies

Описание

Используйте API chrome.cookies для запроса и изменения файлов cookie, а также для получения уведомлений об их изменениях.

Разрешения

cookies

Манифест

Для использования API файлов cookie необходимо указать разрешение "cookies" в манифесте, а также разрешения для хостов , к файлам cookie которых вы хотите получить доступ. Например:

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

Разделение

Разделенные файлы cookie позволяют сайту указывать, что определенные файлы cookie должны быть привязаны к источнику фрейма верхнего уровня. Это означает, что если сайт A встроен с помощью iframe на сайты B и C, то разделенный файл cookie может иметь разное значение на каждом из них.

chrome.cookies не поддерживает разделение файлов cookie, это означает, что все методы читают и записывают cookie из всех разделов. Метод cookies.set() сохраняет cookie в разделе по умолчанию.

Подробную информацию об общем влиянии разделения памяти на разделы для расширений см. в разделе «Хранилище и файлы cookie» .

Примеры

Простой пример использования API cookie можно найти в каталоге examples/api/cookies . Другие примеры и помощь в просмотре исходного кода см. в разделе Samples .

Типы

Представляет информацию о HTTP-куки.

Характеристики

  • домен

    нить

    Домен файла cookie (например, "www.google.com", "example.com").

  • Дата окончания срока

    число необязательно

    Срок действия cookie-файла указывается в секундах с начала эпохи UNIX. Для сессионных cookie-файлов эта информация не предоставляется.

  • hostOnly

    логический

    Значение true, если cookie-файл содержит только информацию о хосте (т.е. хост запроса должен точно совпадать с доменом cookie-файла).

  • httpТолько

    логический

    Значение true, если cookie помечен как HttpOnly (т.е. cookie недоступен для клиентских скриптов).

  • имя

    нить

    Название файла cookie.

  • partitionKey

    CookiePartitionKey необязательный

    Chrome 119+

    Ключ раздела для чтения или изменения файлов cookie с атрибутом Partitioned.

  • путь

    нить

    Путь печенья.

  • тот же сайт

    SameSiteStatus

    Chrome 51+

    Статус cookie-файла в рамках одного сайта (т.е. отправляется ли cookie-файл с межсайтовыми запросами).

  • безопасный

    логический

    Значение true, если cookie помечен как Secure (т.е. его область действия ограничена защищенными каналами, обычно HTTPS).

  • сессия

    логический

    Значение true, если это сессионный cookie, в отличие от постоянного cookie с датой истечения срока действия.

  • storeId

    нить

    Идентификатор хранилища файлов cookie, содержащего этот файл cookie, предоставленный в функции getAllCookieStores().

  • ценить

    нить

    Ценность файла cookie.

CookieDetails

Chrome 88+

Подробная информация для идентификации файла cookie.

Характеристики

  • имя

    нить

    Имя файла cookie, к которому необходимо получить доступ.

  • partitionKey

    CookiePartitionKey необязательный

    Chrome 119+

    Ключ раздела для чтения или изменения файлов cookie с атрибутом Partitioned.

  • storeId

    строка необязательный

    Идентификатор хранилища cookie, в котором следует искать cookie. По умолчанию будет использоваться хранилище cookie текущего контекста выполнения.

  • url

    нить

    URL-адрес, с которым связан cookie-файл. Этот аргумент может представлять собой полный URL-адрес, в этом случае любые данные, следующие за путем URL (например, строка запроса), просто игнорируются. Если в файле манифеста не указаны права доступа к этому URL-адресу, вызов API завершится ошибкой.

CookiePartitionKey

Chrome 119+

Представляет собой ключ раздела для разделенного файла cookie.

Характеристики

  • hasCrossSiteAncestor

    логический необязательный

    Chrome 130+

    Указывает, был ли cookie установлен в контексте межсайтового взаимодействия. Это предотвращает доступ сайта верхнего уровня, встроенного в межсайтовый контекст, к cookie, установленным сайтом верхнего уровня в контексте того же сайта.

  • topLevelSite

    строка необязательный

    Сайт верхнего уровня, на котором доступен разделенный на разделы cookie.

CookieStore

Представляет собой хранилище файлов cookie в браузере. Например, окно в режиме инкогнито использует отдельное хранилище файлов cookie, отличное от окна в обычном режиме.

Характеристики

  • идентификатор

    нить

    Уникальный идентификатор для хранилища файлов cookie.

  • tabIds

    число[]

    Идентификаторы всех вкладок браузера, использующих это хранилище файлов cookie.

FrameDetails

Chrome 132+

Детали, позволяющие идентифицировать раму.

Характеристики

  • documentId

    строка необязательный

    Уникальный идентификатор документа. Если указаны frameId и/или tabId, они будут проверены на соответствие документу, найденному по указанному идентификатору документа.

  • frameId

    число необязательно

    Уникальный идентификатор фрейма внутри вкладки.

  • tabId

    число необязательно

    Уникальный идентификатор вкладки, содержащей фрейм.

OnChangedCause

Chrome 44+

Основная причина изменения cookie-файла. Если cookie-файл был добавлен или удален посредством явного вызова метода "chrome.cookies.remove", значение параметра "cause" будет "explicit". Если cookie-файл был автоматически удален из-за истечения срока действия, значение параметра "cause" будет "expired". Если cookie-файл был удален из-за перезаписи уже истекшей датой истечения срока действия, значение параметра "cause" будет установлено на "expired_overwrite". Если cookie-файл был автоматически удален из-за сборки мусора, значение параметра "cause" будет "evicted". Если cookie-файл был автоматически удален из-за вызова метода "set", который перезаписал его, значение параметра "cause" будет "overwrite". Подготовьте свой ответ соответствующим образом.

Перечисление

"выселен"

"истекший"

"явный"

"expired_overwrite"

"перезапись"

SameSiteStatus

Chrome 51+

Состояние 'SameSite' файла cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' соответствует файлу cookie с атрибутом 'SameSite=None', 'lax' — 'SameSite=Lax', а 'strict' — 'SameSite=Strict'. 'unspecified' соответствует файлу cookie без атрибута SameSite.

Перечисление

"no_restriction"

"слабый"

"строгий"

«неуказанный»

Методы

get()

Обещать
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
): Promise<Cookie | undefined>

Получает информацию об одном файле cookie. Если для заданного URL-адреса существует несколько файлов cookie с одинаковым именем, будет возвращен тот, у которого самый длинный путь. Для файлов cookie с одинаковой длиной пути будет возвращен файл cookie с самым ранним временем создания.

Параметры

  • подробности

    CookieDetails

  • перезвонить

    функция необязательна

    Параметр callback выглядит следующим образом: 

    (cookie?: Cookie) => void

    • печенье

      Печенье ( по желанию)

      Содержит подробную информацию о cookie-файле. Этот параметр имеет значение null, если такой cookie-файл не был найден.

Возвраты

  • Promise< Cookie | undefined>

    Chrome 88+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

getAll()

Обещать
chrome.cookies.getAll(
  details: object,
  callback?: function,
): Promise<Cookie[]>

Извлекает все файлы cookie из одного хранилища файлов cookie, соответствующие заданной информации. Возвращаемые файлы cookie будут отсортированы, начиная с тех, у которых самый длинный путь. Если несколько файлов cookie имеют одинаковую длину пути, первыми будут файлы с самым ранним временем создания. Этот метод извлекает файлы cookie только для доменов, к которым расширение имеет права доступа.

Параметры

  • подробности

    объект

    Информация для фильтрации получаемых файлов cookie.

    • домен

      строка необязательный

      Ограничивает список получаемых файлов cookie теми, домены которых совпадают с данным или являются его поддоменами.

    • имя

      строка необязательный

      Фильтрует файлы cookie по имени.

    • partitionKey

      CookiePartitionKey необязательный

      Chrome 119+

      Ключ раздела для чтения или изменения файлов cookie с атрибутом Partitioned.

    • путь

      строка необязательный

      Ограничивает список полученных файлов cookie теми, путь к которым точно соответствует этой строке.

    • безопасный

      логический необязательный

      Фильтрует файлы cookie по их свойству Secure.

    • сессия

      логический необязательный

      Фильтрует сессионные и постоянные файлы cookie.

    • storeId

      строка необязательный

      Хранилище файлов cookie, из которого будут извлекаться файлы cookie. Если оно опущено, будет использоваться хранилище файлов cookie текущего контекста выполнения.

    • url

      строка необязательный

      Ограничивает список полученных файлов cookie теми, которые соответствуют указанному URL-адресу.

  • перезвонить

    функция необязательна

    Параметр callback выглядит следующим образом: 

    (cookies: Cookie[]) => void

    • файлы cookie

      Печенье []

      Все существующие, непросроченные файлы cookie, соответствующие указанной информации о файле cookie.

Возвраты

  • Обещание< Cookie []>

    Chrome 88+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

getAllCookieStores()

Обещать
chrome.cookies.getAllCookieStores(
  callback?: function,
): Promise<CookieStore[]>

Отображает список всех существующих магазинов, продающих печенье.

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит следующим образом: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore []

      Все существующие магазины файлов cookie.

Возвраты

  • Promise< CookieStore []>

    Chrome 88+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

getPartitionKey()

Promise Chrome 132+
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

Указан ключ раздела для фрейма.

Параметры

  • подробности

    FrameDetails

  • перезвонить

    функция необязательна

    Параметр callback выглядит следующим образом: 

    (details: object) => void

    • подробности

      объект

      Содержит подробную информацию о полученном ключе раздела.

      • partitionKey

        CookiePartitionKey

        Ключ раздела для чтения или изменения файлов cookie с атрибутом Partitioned.

Возвраты

  • Promise<object>

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

remove()

Обещать
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
): Promise<object | undefined>

Удаляет cookie-файл по имени.

Параметры

  • подробности

    CookieDetails

  • перезвонить

    функция необязательна

    Параметр callback выглядит следующим образом: 

    (details?: object) => void

    • подробности

      объект необязательный

      Содержит подробную информацию об удаленном cookie-файле. Если удаление по какой-либо причине не удалось, обещание будет отклонено.

      • имя

        нить

        Название удаленного файла cookie.

      • partitionKey

        CookiePartitionKey необязательный

        Chrome 119+

        Ключ раздела для чтения или изменения файлов cookie с атрибутом Partitioned.

      • storeId

        нить

        Идентификатор хранилища файлов cookie, из которого был удален файл cookie.

      • url

        нить

        URL-адрес, связанный с удаленным cookie-файлом.

Возвраты

  • Promise<object | undefined>

    Chrome 88+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

set()

Обещать
chrome.cookies.set(
  details: object,
  callback?: function,
): Promise<Cookie | undefined>

Устанавливает cookie-файл с заданными данными; может перезаписывать эквивалентные cookie-файлы, если таковые существуют.

Параметры

  • подробности

    объект

    Подробная информация об устанавливаемом cookie-файле.

    • домен

      строка необязательный

      Домен файла cookie. Если он опущен, файл cookie становится файлом cookie, предназначенным только для хоста.

    • Дата окончания срока

      число необязательно

      Срок действия cookie-файла указывается в секундах с начала эпохи UNIX. Если этот параметр опущен, cookie-файл становится сессионным.

    • httpТолько

      логический необязательный

      Указывает, следует ли помечать cookie как HttpOnly. По умолчанию — false.

    • имя

      строка необязательный

      Название cookie-файла. По умолчанию пустое, если не указано.

    • partitionKey

      CookiePartitionKey необязательный

      Chrome 119+

      Ключ раздела для чтения или изменения файлов cookie с атрибутом Partitioned.

    • путь

      строка необязательный

      Путь к cookie-файлу. По умолчанию используется путь, указанный в параметре url.

    • тот же сайт

      SameSiteStatus ( необязательно)

      Chrome 51+

      Статус соединения SameSite для файла cookie. По умолчанию — «не указано», то есть, если этот параметр отсутствует, файл cookie устанавливается без указания атрибута SameSite.

    • безопасный

      логический необязательный

      Указывает, следует ли помечать cookie как «Защищенный». По умолчанию — false.

    • storeId

      строка необязательный

      Идентификатор хранилища cookie, в которое следует установить cookie. По умолчанию cookie устанавливается в хранилище cookie текущего контекста выполнения.

    • url

      нить

      URI запроса, связанный с настройкой cookie. Это значение может влиять на значения домена и пути по умолчанию для создаваемого cookie. Если в файле манифеста не указаны права доступа хоста для этого URL-адреса, вызов API завершится ошибкой.

    • ценить

      строка необязательный

      Значение cookie-файла. По умолчанию пустое, если не указано.

  • перезвонить

    функция необязательна

    Параметр callback выглядит следующим образом: 

    (cookie?: Cookie) => void

    • печенье

      Печенье ( по желанию)

      Содержит подробную информацию об установленном cookie-файле. Если по какой-либо причине установка не удалась, промис будет отклонен.

Возвраты

  • Promise< Cookie | undefined>

    Chrome 88+

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

События

onChanged

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

Событие срабатывает при установке или удалении cookie-файла. В качестве частного случая следует отметить, что обновление свойств cookie-файла реализовано в два этапа: сначала cookie-файл, который необходимо обновить, полностью удаляется, генерируя уведомление с "причиной" "перезаписи". Затем записывается новый cookie-файл с обновленными значениями, генерируя второе уведомление с "причиной" "явной".

Параметры

  • перезвонить

    функция

    Параметр callback выглядит следующим образом: 

    (changeInfo: object) => void

    • changeInfo

      объект

      • причина

        OnChangedCause

        Основная причина изменения файла cookie.

      • печенье

        Печенье

        Информация о файле cookie, который был установлен или удален.

      • удаленный

        логический

        Возвращает true, если cookie был удален.