설명
chrome.cookies API를 사용하여 쿠키를 쿼리하고 수정하며 쿠키가 변경될 때 알림을 받습니다.
권한
cookies쿠키 API를 사용하려면 액세스하려는 쿠키가 있는 호스트의 호스트 권한과 함께 매니페스트에서 "cookies" 권한을 선언하세요. 예를 들면 다음과 같습니다.
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
파티션 나누기
파티셔닝된 쿠키를 사용하면 사이트에서 특정 쿠키가 최상위 프레임의 출처에 대해 키가 지정되어야 한다고 표시할 수 있습니다. 즉, 예를 들어 사이트 A가 사이트 B와 사이트 C에 iframe을 사용하여 삽입된 경우 A의 파티셔닝된 쿠키의 삽입된 버전은 B와 C에서 서로 다른 값을 가질 수 있습니다.
기본적으로 모든 API 메서드는 파티셔닝되지 않은 쿠키에서 작동합니다. partitionKey 속성을 사용하여 이 동작을 재정의할 수 있습니다.
확장 프로그램의 파티셔닝이 미치는 일반적인 영향에 관한 자세한 내용은 스토리지 및 쿠키를 참고하세요.
예
쿠키 API 사용의 간단한 예는 examples/api/cookies 디렉터리에서 확인할 수 있습니다. 다른 예시와 소스 코드 보기 도움말은 샘플을 참고하세요.
유형
Cookie
HTTP 쿠키에 관한 정보를 나타냅니다.
속성
-
도메인
문자열
쿠키의 도메인입니다 (예: 'www.google.com', 'example.com').
-
expirationDate
번호 선택사항
UNIX epoch 이후의 시간(초)으로 표시된 쿠키의 만료일입니다. 세션 쿠키에는 제공되지 않습니다.
-
hostOnly
부울
쿠키가 호스트 전용 쿠키인 경우 (즉, 요청의 호스트가 쿠키의 도메인과 정확히 일치해야 함) true입니다.
-
httpOnly
부울
쿠키가 HttpOnly로 표시된 경우 (즉, 클라이언트 측 스크립트에서 쿠키에 액세스할 수 없는 경우) true입니다.
-
이름
문자열
쿠키의 이름입니다.
-
partitionKey
CookiePartitionKey 선택사항
Chrome 119 이상Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.
-
경로
문자열
쿠키의 경로입니다.
-
sameSiteChrome 51 이상
쿠키의 동일 사이트 상태 (즉, 쿠키가 크로스 사이트 요청과 함께 전송되는지 여부)입니다.
-
보안
부울
쿠키가 보안으로 표시된 경우(즉, 범위가 보안 채널(일반적으로 HTTPS)로 제한됨) true입니다.
-
세션
부울
쿠키가 만료일이 있는 영구 쿠키가 아닌 세션 쿠키인 경우 True입니다.
-
storeId
문자열
이 쿠키를 포함하는 쿠키 저장소의 ID입니다(getAllCookieStores()에 제공됨).
-
값
문자열
쿠키의 값입니다.
CookieDetails
쿠키를 식별하는 세부정보입니다.
속성
-
이름
문자열
액세스할 쿠키의 이름입니다.
-
partitionKey
CookiePartitionKey 선택사항
Chrome 119 이상Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.
-
storeId
문자열 선택사항
쿠키를 찾을 쿠키 저장소의 ID입니다. 기본적으로 현재 실행 컨텍스트의 쿠키 저장소가 사용됩니다.
-
URL
문자열
액세스할 쿠키가 연결된 URL입니다. 이 인수는 전체 URL일 수 있으며, 이 경우 URL 경로 뒤에 오는 데이터 (예: 쿼리 문자열)는 무시됩니다. 이 URL의 호스트 권한이 매니페스트 파일에 지정되지 않���면 API 호출이 실패합니다.
CookiePartitionKey
파티셔닝된 쿠키의 파티션 키를 나타냅니다.
속성
-
hasCrossSiteAncestor
불리언 선택사항
Chrome 130 이상쿠키가 크로스 사이트 컨텍스트에서 설정되었는지 여부를 나타냅니다. 이렇게 하면 크로스 사이트 컨텍스트에 삽입된 최상위 사이트가 동일한 사이트 컨텍스트에서 최상위 사이트에 의해 설정된 쿠키에 액세스할 수 없습니다.
-
topLevelSite
문자열 선택사항
파티셔닝된 쿠키를 사용할 수 있는 최상위 사이트입니다.
CookieStore
브라우저의 쿠키 저장소를 나타냅니다. 예를 들어 시크릿 모드 창은 비시크릿 창과 별도의 쿠키 저장소를 사용합니다.
속성
-
id
문자열
쿠키 저장소의 고유 식별자입니다.
-
tabIds
number[]
이 쿠키 저장소를 공유하는 모든 브라우저 탭의 식별자입니다.
FrameDetails
프레임을 식별하는 세부정보입니다.
속성
-
documentId
문자열 선택사항
문서의 고유 식별자입니다. frameId 또는 tabId가 제공되면 제공된 문서 ID로 찾은 문서와 일치하는지 확인합니다.
-
frameId
번호 선택사항
탭 내 프레임의 고유 식별자입니다.
-
tabId
번호 선택사항
프레임이 포함된 탭의 고유 식별자입니다.
OnChangedCause
쿠키 변경의 근본적인 이유���니다. 'chrome.cookies.remove'에 대한 명시적 호출을 통해 쿠키가 삽입되거나 삭제된 경우 'cause'는 'explicit'입니다. 만료로 인해 쿠키가 자동으로 삭제된 경우 '원인'은 '만료됨'입니다. 이미 만료된 만료일로 덮어쓰여 쿠키가 삭제된 경우 '원인'이 'expired_overwrite'로 설정됩니다. 가비지 컬렉션으로 인해 쿠키가 자동으로 삭제된 경우 '원인'은 '삭제됨'입니다. 쿠키가 덮어쓰는 'set' 호출로 인해 자동으로 삭제된 경우 '원인'은 '덮어쓰기'가 됩니다. 이에 따라 대답을 계획하세요.
열거형
'evicted'
"expired"
"explicit"
"expired_overwrite"
'overwrite'
SameSiteStatus
쿠키의 'SameSite' 상태 (https://tools.ietf.org/html/draft-west-first-party-cookies)입니다. 'no_restriction'은 'SameSite=None'으로 설정된 쿠키에 해당하고, 'lax'는 'SameSite=Lax'에, 'strict'는 'SameSite=Strict'에 해당합니다. 'unspecified'는 SameSite 속성 없이 설정된 쿠키에 해당합니다.
열거형
'no_restriction'
"lax"
'strict'
"unspecified"
메서드
get()
chrome.cookies.get(
details: CookieDetails,
): Promise<Cookie | undefined>
단일 쿠키에 관한 정보를 가져옵니다. 지정된 URL에 이름이 동일한 쿠키가 두 개 이상 있는 경우 경로가 가장 긴 쿠키가 반환됩니다. 경로 길이가 동일한 쿠키의 경우 생성 시간이 가장 빠른 쿠키가 반환됩니다.
매개변수
-
세부정보
반환 값
-
Promise<Cookie | undefined>
Chrome 88 이상
getAll()
chrome.cookies.getAll(
details: object,
): Promise<Cookie[]>
지정된 정보와 일치하는 모든 쿠키를 단일 쿠키 저장소에서 검색합니다. 반환된 쿠키는 경로가 가장 긴 쿠키가 먼저 오도록 정렬됩니다. 여러 쿠키의 경로 길이가 동일한 경우 생성 시간이 가장 빠른 쿠키가 먼저 표시됩니다. 이 메서드는 확장 프로그램에 호스트 권한이 있는 도메인의 쿠키만 가져옵니다.
매개변수
-
세부정보
객체
가져올 쿠키를 필터링하는 정보입니다.
-
도메인
문자열 선택사항
가져온 쿠키를 도메인이 이 도메인과 일치하거나 이 도메인의 하위 도메인인 쿠키로 제한합니다.
-
이름
문자열 선택사항
이름으로 쿠키를 필터링합니다.
-
partitionKey
CookiePartitionKey 선택사항
Chrome 119 이상Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.
-
경로
문자열 선택사항
경로가 이 문자열과 정확히 일치하는 쿠키로 가져온 쿠키를 제한합니다.
-
보안
불리언 선택사항
쿠키를 Secure 속성으로 필터링합니다.
-
세션
불리언 선택사항
세션 쿠키와 영구 쿠키를 필터링합니다.
-
storeId
문자열 선택사항
쿠키를 가져올 쿠키 저장소입니다. 생략하면 현재 실행 컨텍스트의 쿠키 저장소가 사용됩니다.
-
URL
문자열 선택사항
가져온 쿠키를 지정된 URL과 일치하는 쿠키로 제한합니다.
-
반환 값
-
Promise<Cookie[]>
Chrome 88 이상
getAllCookieStores()
chrome.cookies.getAllCookieStores(): Promise<CookieStore[]>
기존 쿠키 스토어를 모두 나열합니다.
반환 값
-
Promise<CookieStore[]>
Chrome 88 이상
getPartitionKey()
chrome.cookies.getPartitionKey(
details: FrameDetails,
): Promise<object>
표시된 프레임의 파티션 키입니다.
매개변수
-
세부정보
반환 값
-
Promise<object>
remove()
chrome.cookies.remove(
details: CookieDetails,
): Promise<object | undefined>
이름으로 쿠키를 삭제합니다.
매개변수
-
세부정보
반환 값
-
Promise<object | undefined>
Chrome 88 이상
set()
chrome.cookies.set(
details: object,
): Promise<Cookie | undefined>
지정된 쿠키 데이터로 쿠키를 설정합니다. 동일한 쿠키가 있는 경우 덮어쓸 수 있습니다.
매개변수
-
세부정보
객체
설정되는 쿠키에 관한 세부정보입니다.
-
도메인
문자열 선택사항
쿠키의 도메인입니다. 생략하면 쿠키가 호스트 전용 쿠키가 됩니다.
-
expirationDate
번호 선택사항
UNIX epoch 이후의 시간(초)으로 표시된 쿠키의 만료일입니다. 생략하면 쿠키가 세션 쿠키가 됩니다.
-
httpOnly
불리언 선택사항
쿠키를 HttpOnly로 표시해야 하는지 여부입니다. 기본값은 false입니다.
-
이름
문자열 선택사항
쿠키의 이름입니다. 생략하면 기본적으로 비어 있습니다.
-
partitionKey
CookiePartitionKey 선택사항
Chrome 119 이상Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.
-
경로
문자열 선택사항
쿠키의 경로입니다. 기본값은 URL 매개변수의 경로 부분입니다.
-
sameSite
SameSiteStatus 선택사항
Chrome 51 이상쿠키의 동일 사이트 상태입니다. 기본값은 'unspecified'입니다. 즉, 생략하면 SameSite 속성을 지정하지 않고 쿠키가 설정됩니다.
-
보안
불리언 선택사항
쿠키가 Secure로 표시되어야 하는지 여부입니다. 기본값은 false입니다.
-
storeId
문자열 선택사항
쿠키를 설정할 쿠키 스토어의 ID입니다. 기본적으로 쿠키는 현재 실행 컨텍스트의 쿠키 저장소에 설정됩니다.
-
URL
문자열
쿠키 설정과 연결할 request-URI입니다. 이 값은 생성된 쿠키의 기본 도메인 및 경로 값에 영향을 줄 수 있습니다. 이 URL의 호스트 권한이 매니페스트 파일에 지정되지 않으면 API 호출이 실패합니다.
-
값
문자열 선택사항
쿠키의 값입니다. 생략하면 기본적으로 비어 있습니다.
-
반환 값
-
Promise<Cookie | undefined>
Chrome 88 이상
이벤트
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
쿠키가 설정되거나 삭제될 때 발생합니다. 특수한 경우로, 쿠키의 속성 업데이트는 2단계 프로세스로 구현됩니다. 업데이트할 쿠키가 먼저 완전히 삭제되어 '원인'이 '덮어쓰기'인 알림이 생성됩니다. 그런 다음 업데이트된 값으로 새 쿠키가 작성되어 '원인'이 '명시적'인 두 번째 알림이 생성됩니다.
매개변수
-
callback
함수
callback매개변수는 다음과 같습니다.(changeInfo: object) => void
-
changeInfo
객체
-
cause
쿠키 변경의 근본적인 이유입니다.
-
쿠키
설정되거나 삭제된 쿠키에 관한 정보입니다.
-
삭제됨
부울
쿠키가 삭제된 경우 True입니다.
-
-