설명
chrome.cookies API를 사용하여 쿠키를 쿼리 및 수정하고 쿠키가 변경될 때 알림을 받으세요.
권한
cookies매니페스트
쿠키 API를 사용하려면 사용자가 사용하는 쿠키의 '쿠키'를 선언해야 합니다. 권한을 매니페스트 및 해당 쿠키를 사용하려는 모든 호스트에 대한 호스트 권한 액세스할 수 있습니다. 예를 들면 다음과 같습니다.
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
파티션 나누기
파티션을 나눈 쿠키를 사용하면 사이트에서 특정 쿠키를 최상위 프레임의 시작점입니다. 즉, 사이트 A가 사이트 B의 iframe을 사용하여 삽입되고 사이트 C의 경우 파티션을 나눈 쿠키는 각각 다른 값을 가질 수 있습니다.
chrome.cookies는 파티션 나누기를 지원하지 않습니다. 즉, 모든 메서드가
모든 파티션에서 쿠키를 읽고 쓸 수 있습니다. cookies.set() 메서드는 쿠키를 다음 위치에 저장합니다.
기본 파티션입니다
확장 프로그램의 파티셔닝이 미치는 일반적인 영향에 대한 자세한 내용은 다음을 참고하세요. 저장소 및 쿠키.
예
쿠키 API를 사용하는 간단한 예는 examples/api/cookies 디렉터리에 있는지 확인합니다. 다른 예 및 보기 도움말 샘플을 참고하세요.
유형
Cookie
HTTP 쿠키에 대한 정보를 나타냅니다.
속성
-
도메인
문자열
쿠키의 도메인입니다 (예: 'www.google.com', 'example.com').
-
expirationDate
숫자 선택사항
UNIX 기점을 기준으로 초 단위로 쿠키의 만료일입니다. 세션 쿠키에는 제공되지 않습니다.
-
hostOnly
부울
쿠키가 호스트 전용 쿠키인 경우 true입니다 (즉, 요청의 호스트가 쿠키의 도메인과 정확하게 일치해야 함).
-
httpOnly
부울
쿠키가 HttpOnly로 표시된 경우 (즉, 클라이언트 측 스크립트에서 쿠키에 액세스할 수 없는 경우) true입니다.
-
이름
문자열
쿠키의 이름입니다.
-
partitionKey
CookiePartitionKey 선택사항
Chrome 119 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.
-
경로
문자열
쿠키의 경로입니다.
-
sameSiteChrome 51 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.
쿠키의 동일 사이트 상태 (예: 쿠키가 크로스 사이트 요청과 함께 전송되는지 여부)
-
보안
부울
쿠키가 보안으로 표시된 경우(즉, 범위가 보안 채널(일반적으로 HTTPS)로 제한되는 경우) true입니다.
-
세션
부울
만료일이 있는 영구 쿠키와 달리 쿠키가 세션 쿠키인 경우 true입니다.
-
storeId
문자열
getAllCookieStores()에서 제공된 이 쿠키가 포함된 쿠키 스토어의 ID입니다.
-
값
문자열
쿠키의 값입니다.
CookieDetails
쿠키를 식별하기 위한 세부정보입니다.
속성
-
이름
문자열
액세스할 쿠키의 이름입니다.
-
partitionKey
CookiePartitionKey 선택사항
Chrome 119 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.
-
storeId
문자열(선택사항)
쿠키를 찾을 쿠키 스토어의 ID입니다. 기본적으로 현재 실행 컨텍스트의 쿠키 저장소가 사용됩니다.
-
URL
문자열
액세스할 쿠키가 연결된 URL입니다. 이 인수는 전체 URL일 수 있으며, 이 경우 URL 경로 다음에 오는 모든 데이터 (예: 쿼리 문자열)는 무시됩니다. 이 URL에 대한 호스트 권한이 매니페스트 파일에 지정되어 있지 않으면 API 호출이 실패합니다.
CookiePartitionKey
파티션을 나눈 쿠키의 파티션 키를 나타냅니다.
속성
-
topLevelSite
문자열(선택사항)
파티셔닝된 쿠키를 사용할 수 있는 최상위 사이트입니다.
CookieStore
브라우저의 쿠키 저장소를 나타냅니다. 예를 들어 시크릿 모드 창은 시크릿 모드가 아닌 창과는 별도의 쿠키 저장소를 사용합니다.
속성
-
id
문자열
쿠키 저장소의 고유 식별자입니다.
-
tabIds
숫자[]
이 쿠키 저장소를 공유하는 모든 브라우저 탭의 식별자입니다.
OnChangedCause
쿠키가 변경되는 근본적인 이유입니다. 쿠키가 삽입되었거나 'chrome.cookies.remove'에 대한 명시적 호출을 통해 삭제된 경우 '원인'입니다. '명시적'입니다 만료로 인해 쿠키가 자동으로 삭제된 경우 '원인'입니다. '만료'됩니다. 이미 만료된 만료일로 덮어써져 쿠키가 삭제된 경우 "원인"입니다. 'expired_overwrite'로 설정됩니다. 가비지 컬렉션으로 인해 쿠키가 자동으로 삭제된 경우 "cause" '제거'됩니다. '설정'으로 인해 쿠키가 자동으로 삭제된 경우 그것을 덮어쓴 호출, "원인" '덮어쓰기'입니다. 이에 따라 대응 계획을 수립하십시오.
열거형
"evicted"
'만료됨'
'음란한 가사'
"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'로 변경합니다. '지정되지 않음' SameSite 속성이 없는 쿠키 집합에 해당합니다.
열거형
"no_restriction"
"느슨한"
'엄격'
'지정되지 않음'
메서드
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
단일 쿠키에 대한 정보를 검색합니다. 주어진 URL에 대해 이름이 같은 쿠키가 두 개 이상 있으면 경로가 가장 긴 쿠키가 반환됩니다. 경로 길이가 동일한 쿠키의 경우 생성 시간이 가장 이른 쿠키가 반환됩니다.
매개변수
반환 값
-
Promise<Cookie | 정의되지 않음>
Chrome 88 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
지정된 정보와 일치하는 단일 쿠키 저장소에서 모든 쿠키를 검색합니다. 반환된 쿠키는 경로가 가장 긴 쿠키 순으로 정렬됩니다. 여러 쿠키의 경로 길이가 동일한 경우 생성 시간이 가장 빠른 쿠키가 먼저 적용됩니다. 이 방법은 확장 프로그램에 호스트 권한이 있는 도메인의 쿠키만 검색합니다.
매개변수
-
세부정보
객체
검색 중인 쿠키를 필터링하기 위한 정보입니다.
-
도메인
문자열(선택사항)
가져온 쿠키를 도메인이 일치하거나 이 도메인의 하위 도메인인 쿠키로 제한합니다.
-
이름
문자열(선택사항)
이름별로 쿠키를 필터링합니다.
-
partitionKey
CookiePartitionKey 선택사항
Chrome 119 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.
-
경로
문자열(선택사항)
검색된 쿠키를 경로가 이 문자열과 정확히 일치하는 쿠키로 제한합니다.
-
보안
불리언 선택사항
보안 속성별로 쿠키를 필터링합니다.
-
세션
불리언 선택사항
세션과 영구 쿠키를 필터링합니다.
-
storeId
문자열(선택사항)
쿠키를 가져올 쿠키 저장소입니다. 생략하면 현재 실행 컨텍스트의 쿠키 저장소가 사용됩니다.
-
URL
문자열(선택사항)
검색된 쿠키를 지정된 URL과 일치하는 쿠키로 제한합니다.
-
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(cookies: Cookie[]) => void
-
쿠키
쿠키[]
특정 쿠키 정보와 일치하는 만료되지 않은 모든 기존 쿠키입니다.
-
반환 값
-
Promise<Cookie[]>
Chrome 88 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
모든 기존 쿠키 저장소를 나열합니다.
매개변수
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(cookieStores: CookieStore[]) => void
-
cookieStores
모든 기존 쿠키 저장소
-
반환 값
-
Promise<CookieStore[]>
Chrome 88 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
이름별로 쿠키를 삭제합니다.
매개변수
-
세부정보
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(details?: object) => void
-
세부정보
객체(선택사항)
삭제된 쿠키에 대한 세부정보가 포함됩니다. 어떠한 이유로든 삭제에 실패하면 'null'이 되고
runtime.lastError가 설정됩니다.-
이름
문자열
삭제된 쿠키의 이름입니다.
-
partitionKey
CookiePartitionKey 선택사항
Chrome 119 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.
-
storeId
문자열
쿠키가 삭제된 쿠키 스토어의 ID입니다.
-
URL
문자열
삭제된 쿠키와 연결된 URL입니다.
-
-
반환 값
-
Promise<object | 정의되지 않음>
Chrome 88 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
set()
chrome.cookies.set(
details: object,
callback?: function,
)
지정된 쿠키 데이터로 쿠키를 설정합니다. 상응하는 쿠키가 있는 경우 해당 쿠키를 덮어쓸 수 있습니다.
매개변수
-
세부정보
객체
설정 중인 쿠키에 대한 세부정보입니다.
-
도메인
문자열(선택사항)
쿠키의 도메인입니다. 생략할 경우 쿠키는 호스트 전용 쿠키가 됩니다.
-
expirationDate
숫자 선택사항
UNIX 기점을 기준으로 초 단위로 쿠키의 만료일입니다. 생략할 경우 쿠키는 세션 쿠키가 됩니다.
-
httpOnly
불리언 선택사항
쿠키를 HttpOnly로 표시할지 여부입니다. 기본값은 false입니다.
-
이름
문자열(선택사항)
쿠키의 이름입니다. 생략할 경우 기본적으로 비어 있습니다.
-
partitionKey
CookiePartitionKey 선택사항
Chrome 119 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.
-
경로
문자열(선택사항)
쿠키의 경로입니다. 기본값은 URL 매개변수의 경로 부분입니다.
-
sameSite
SameSiteStatus 선택사항
Chrome 51 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.쿠키의 동일 사이트 상태입니다. 기본값은 '미지정'입니다. 즉, 생략된 경우 SameSite 속성을 지정하지 않고 쿠키가 설정됩니다.
-
보안
불리언 선택사항
쿠키를 '보안'으로 표시해야 하는지 여부입니다. 기본값은 false입니다.
-
storeId
문자열(선택사항)
쿠키를 설정할 쿠키 저장소의 ID입니다. 기본적으로 쿠키는 현재 실행 컨텍스트의 쿠키 저장소에 설정됩니다.
-
URL
문자열
쿠키 설정과 연결할 요청 URI입니다. 이 값은 생성된 쿠키의 기본 도메인 및 경로 값에 영향을 줄 수 있습니다. 이 URL에 대한 호스트 권한이 매니페스트 파일에 지정되어 있지 않으면 API 호출이 실패합니다.
-
값
문자열(선택사항)
쿠키의 값입니다. 생략할 경우 기본적으로 비어 있습니다.
-
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(cookie?: Cookie) => void
-
쿠키
쿠키 선택사항
설정된 쿠키에 대한 세부정보가 포함됩니다. 어떠한 이유로든 설정에 실패하면 'null'이 되고
runtime.lastError가 설정됩니다.
-
반환 값
-
Promise<Cookie | 정의되지 않음>
Chrome 88 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
이벤트
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
쿠키가 설정되거나 삭제되면 실행됩니다. 특별한 경우에는 쿠키의 속성 업데이트가 2단계 프로세스로 구현됩니다. 즉, 업데이트할 쿠키가 먼저 완전히 삭제되고 '원인'이 포함된 알림이 생성됩니다. (삭제 중) 에서 자세한 내용을 확인하실 수 있습니다. 이후 업데이트된 값으로 새 쿠키가 작성되어 '원인'이 포함된 두 번째 알림이 생성됩니다. '명시적'입니다.
매개변수
-
콜백
함수
callback매개변수는 다음과 같습니다.(changeInfo: object) => void
-
changeInfo
객체
-
cause
쿠키가 변경되는 근본적인 이유입니다.
-
쿠키
설정되거나 삭제된 쿠키에 대한 정보입니다.
-
삭제됨
부울
쿠키가 삭제된 경우 true입니다.
-
-