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 из A могут иметь разные значения на B и C.

По умолчанию все методы API работают с неразделенными файлами cookie. Свойство partitionKey можно использовать для переопределения этого поведения.

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

Примеры

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

Типы

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

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

  • домен

    нить

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

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

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

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

  • только хост

    логическое значение

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

  • httpOnly

    логическое значение

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

  • имя

    нить

    Имя файла cookie.

  • Ключ раздела

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

    Хром 119

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

  • путь

    нить

    Путь файла cookie.

  • Хром 51

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

  • безопасный

    логическое значение

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

  • сессия

    логическое значение

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

  • идентификатор магазина

    нить

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

  • ценить

    нить

    Значение файла cookie.

CookieDetails

Хром 88

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

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

  • имя

    нить

    Имя файла cookie для доступа.

  • Ключ раздела

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

    Хром 119

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

  • идентификатор магазина

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

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

  • URL

    нить

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

CookiePartitionKey

Хром 119

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

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

  • topLevelSite

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

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

CookieStore

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

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

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

    нить

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

  • tabIds

    число[]

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

OnChangedCause

Хром 44

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

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

"выселен"

"истекший"

"явный"

"истек_перезаписать"

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

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.

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

"без ограничений"

"слабый"

"строгий"

"неопределенные"

Методы

get()

Обещать
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

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

Параметры

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

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

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

    (cookie?: Cookie) => void

    • печенье

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

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

Возврат

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

    Хром 88

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getAll()

Обещать
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

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

Параметры

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

    объект

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

    • домен

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

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

    • имя

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

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

    • Ключ раздела

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

      Хром 119

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

    • путь

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

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

    • безопасный

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

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

    • сессия

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

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

    • идентификатор магазина

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

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

    • URL

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

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

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

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

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

    (cookies: Cookie[]) => void

    • печенье

      Файл cookie []

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

Возврат

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

    Хром 88

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getAllCookieStores()

Обещать
chrome.cookies.getAllCookieStores(
  callback?: function,
)

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

Параметры

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

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

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

    (cookieStores: CookieStore[]) => void

Возврат

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

    Хром 88

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

remove()

Обещать
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

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

Параметры

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

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

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

    (details?: object) => void

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

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

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

      • имя

        нить

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

      • Ключ раздела

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

        Хром 119

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

      • идентификатор магазина

        нить

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

      • URL

        нить

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

Возврат

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

    Хром 88

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

set()

Обещать
chrome.cookies.set(
  details: object,
  callback?: function,
)

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

Параметры

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

    объект

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

    • домен

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

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

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

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

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

    • httpOnly

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

      Должен ли файл cookie быть помечен как HttpOnly. По умолчанию ложь.

    • имя

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

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

    • Ключ раздела

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

      Хром 119

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

    • путь

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

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

    • тот же сайт

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

      Хром 51

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

    • безопасный

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

      Должен ли файл cookie быть помечен как безопасный. По умолчанию ложь.

    • идентификатор магазина

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

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

    • URL

      нить

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

    • ценить

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

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

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

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

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

    (cookie?: Cookie) => void

    • печенье

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

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

Возврат

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

    Хром 88

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onChanged

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

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

Параметры

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

    функция

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

    (changeInfo: object) => void

    • изменениеИнформация

      объект

      • причина

        OnChangedCause

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

      • печенье

        печенье

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

      • удаленный

        логическое значение

        Истинно, если файл cookie был удален.