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 из всех разделов. Метод cookies.set() сохраняет файлы cookie в разделе по умолчанию.

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

Примеры

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

Типы

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

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

  • домен

    нить

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

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

    номер необязательно

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

  • только хост

    булев

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

  • httpOnly

    булев

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

  • имя

    нить

    Имя файла cookie.

  • partitionKey

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

    Хром 119+

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

  • путь

    нить

    Путь файла cookie.

  • тот жеСайт

    SameSiteStatus

    Хром 51+

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

  • безопасный

    булев

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

  • сессия

    булев

    True, если cookie-файл является сеансовым, а не постоянным cookie-файлом с датой истечения срока действия.

  • storeId

    нить

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

  • ценить

    нить

    Ценность куки-файла.

CookieDetails

Хром 88+

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

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

  • имя

    нить

    Имя куки-файла для доступа.

  • partitionKey

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

    Хром 119+

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

  • storeId

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

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

  • URL-адрес

    нить

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

CookiePartitionKey

Хром 119+

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

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

  • hasCrossSiteAncestor

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

    Хром 130+

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

  • topLevelSite

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

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

CookieStore

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

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

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

    нить

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

  • tabIds

    число[]

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

FrameDetails

Хром 132+

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

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

  • documentId

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

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

  • frameId

    номер необязательно

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

  • tabId

    номер необязательно

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

OnChangedCause

Хром 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

Хром 51+

Состояние cookie-файла «SameSite» (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 необязателен

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

Возврат

  • Обещание< Файл cookie | не определено>

    Хром 88+

    Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

getAll()

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

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

Параметры

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

    объект

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

    • домен

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

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

    • имя

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

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

    • partitionKey

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

      Хром 119+

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

    • путь

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

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

    • безопасный

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

      Фильтрует файлы cookie по их свойству «Безопасность».

    • сессия

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

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

    • storeId

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

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

    • URL-адрес

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

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

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

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

    Параметр callback выглядит так: 

    (cookies: Cookie[]) => void

    • печенье

      Файл cookie []

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

Возврат

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

    Хром 88+

    Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

getAllCookieStores()

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

Перечисляет все существующие хранилища файлов cookie.

Параметры

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

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

    Параметр callback выглядит так: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore []

      Все существующие хранилища файлов cookie.

Возврат

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

    Хром 88+

    Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

getPartitionKey()

Обещание Chrome 132+
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

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

Параметры

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

    Детали рамы

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

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

    Параметр callback выглядит так: 

    (details: object) => void

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

      объект

      Содержит сведения о полученном ключе раздела.

      • partitionKey

        CookiePartitionKey

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

Возврат

  • Обещание<объект>

    Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

remove()

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

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

Параметры

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

    CookieDetails

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

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

    Параметр callback выглядит так: 

    (details?: object) => void

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

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

      Содержит информацию об удалённом cookie-файле. Если удаление по какой-либо причине не удалось, это значение будет равно «null» и будет установлено исключение runtime.lastError .

      • имя

        нить

        Имя удаленного cookie-файла.

      • partitionKey

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

        Хром 119+

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

      • storeId

        нить

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

      • URL-адрес

        нить

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

Возврат

  • Обещание<объект | неопределенный>

    Хром 88+

    Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

set()

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

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

Параметры

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

    объект

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

    • домен

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

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

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

      номер необязательно

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

    • httpOnly

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

      Следует ли помечать cookie как HttpOnly. Значение по умолчанию — false.

    • имя

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

      Имя файла cookie. Если не указано, по умолчанию пусто.

    • partitionKey

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

      Хром 119+

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

    • путь

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

      Путь к файлу cookie. По умолчанию соответствует части пути параметра URL.

    • тот жеСайт

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

      Хром 51+

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

    • безопасный

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

      Следует ли пометить файл cookie как безопасный. Значение по умолчанию — false.

    • storeId

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

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

    • URL-адрес

      нить

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

    • ценить

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

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

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

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

    Параметр callback выглядит так: 

    (cookie?: Cookie) => void

    • печенье

      Файл cookie необязателен

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

Возврат

  • Обещание< Файл cookie | не определено>

    Хром 88+

    Обещания поддерживаются только для Manifest V3 и более поздних версий, на других платформах необходимо использовать обратные вызовы.

События

onChanged

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

Срабатывает при установке или удалении файла cookie. Обратите внимание, что обновление свойств файла cookie реализовано в виде особого случая: сначала файл cookie, подлежащий обновлению, полностью удаляется, что приводит к появлению уведомления с причиной «overwrite». После этого записывается новый файл cookie с обновлёнными значениями, что приводит к появлению второго уведомления с причиной «explicit».

Параметры

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

    функция

    Параметр callback выглядит так: 

    (changeInfo: object) => void

    • changeInfo

      объект

      • причина

        OnChangedCause

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

      • печенье

        Печенье

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

      • удаленный

        булев

        True, если файл cookie был удален.