chrome.cookies

설명

chrome.cookies API를 사용하여 쿠키를 쿼리 및 수정하고 쿠키가 변경될 때 알림을 받으세요.

권한

cookies

매니페스트

cookies API를 사용하려면 매니페스트에서 'cookies' 권한과 액세스하려는 쿠키가 있는 호스트의 호스트 권한을 선언해야 합니다. 예를 들면 다음과 같습니다.

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

파티션 나누기

파티션을 나눈 쿠키를 사용하면 사이트에서 특정 쿠키를 최상위 프레임의 시작점입니다. 즉, 사이트 A가 사이트 B에서 iframe을 사용하여 삽입되고 사이트 C의 경우 파티션을 나눈 쿠키는 각각 다른 값을 가질 수 있습니다.

chrome.cookies는 파티셔닝을 지원하지 않습니다. 즉, 모든 메서드는 모든 파티션에서 쿠키를 읽고 씁니다. cookies.set() 메서드는 쿠키를 다음 위치에 저장합니다. 기본 파티션입니다

확장 프로그램 파티션의 일반적인 영향에 관한 자세한 내용은 저장소 및 쿠키를 참고하세요.

예

쿠키 API를 사용하는 간단한 예는 examples/api/cookies 디렉터리에 있는지 확인합니다. 다른 예 및 보기 도움말 샘플을 참고하세요.

유형

HTTP 쿠키에 대한 정보를 나타냅니다.

속성

  • 도메인

    문자열

    쿠키의 도메인입니다 (예: 'www.google.com', 'example.com').

  • expirationDate

    숫자 선택사항

    UNIX 기점을 기준으로 초 단위로 쿠키의 만료일입니다. 세션 쿠키에는 제공되지 않습니다.

  • hostOnly

    부울

    쿠키가 호스트 전용 쿠키인 경우 true입니다 (즉, 요청의 호스트가 쿠키의 도메인과 정확하게 일치해야 함).

  • httpOnly

    부울

    쿠키가 HttpOnly로 표시된 경우(즉, 클라이언트 측 스크립트에서 쿠키에 액세스할 수 없는 경우) true입니다.

  • 이름

    문자열

    쿠키의 이름입니다.

  • partitionKey

    CookiePartitionKey 선택사항

    Chrome 119 이상

    Partitioned 속성을 사용하여 쿠키를 읽거나 수정하기 위한 파티션 키입니다.

  • 경로

    문자열

    쿠키의 경로입니다.

  • sameSite

    SameSiteStatus

    Chrome 51 이상

    쿠키의 동일 사이트 상태 (예: 쿠키가 크로스 사이트 요청과 함께 전송되는지 여부)

  • 보안

    부울

    쿠키가 보안으로 표시된 경우(즉, 범위가 보안 채널(일반적으로 HTTPS)로 제한되는 경우) true입니다.

  • 세션

    부울

    만료일이 있는 영구 쿠키와 달리 쿠키가 세션 쿠키인 경우 true입니다.

  • storeId

    문자열

    getAllCookieStores()에서 제공된 이 쿠키가 포함된 쿠키 스토어의 ID입니다.

  • 값

    문자열

    쿠키의 값입니다.

CookieDetails

Chrome 88 이상

쿠키를 식별하기 위한 세부정보입니다.

속성

  • 이름

    문자열

    액세스할 쿠키의 이름입니다.

  • partitionKey

    CookiePartitionKey 선택사항

    Chrome 119 이상

    Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.

  • storeId

    문자열(선택사항)

    쿠키를 찾을 쿠키 스토어의 ID입니다. 기본적으로 현재 실행 컨텍스트의 쿠키 저장소가 사용됩니다.

  • URL

    문자열

    액세스할 쿠키가 연결된 URL입니다. 이 인수는 전체 URL일 수 있으며, 이 경우 URL 경로 다음에 오는 모든 데이터 (예: 쿼리 문자열)는 무시됩니다. 이 URL의 호스트 권한이 매니페스트 파일에 지정되지 않으면 API 호출이 실패합니다.

CookiePartitionKey

Chrome 119 이상

파티션을 나눈 쿠키의 파티션 키를 나타냅니다.

속성

  • hasCrossSiteAncestor

    불리언 선택사항

    Chrome 130 이상

    쿠키가 교차 교차 사이트 컨텍스트에서 설정되었는지를 나타냅니다. 이렇게 하면 크로스 사이트 컨텍스트에 삽입된 최상위 사이트가 동일 사이트 컨텍스트의 최상위 사이트에서 설정한 쿠키에 액세스할 수 없습니다.

  • topLevelSite

    문자열 선택사항

    파티셔닝된 쿠키를 사용할 수 있는 최상위 사이트입니다.

CookieStore

브라우저의 쿠키 저장소를 나타냅니다. 예를 들어 시크릿 모드 창은 시크릿 모드가 아닌 창과는 별도의 쿠키 저장소를 사용합니다.

속성

  • id

    문자열

    쿠키 저장소의 고유 식별자입니다.

  • tabIds

    숫자[]

    이 쿠키 저장소를 공유하는 모든 브라우저 탭의 식별자입니다.

OnChangedCause

Chrome 44 이상

쿠키가 변경된 근본적인 이유입니다. 쿠키가 삽입되었거나 'chrome.cookies.remove'에 대한 명시적 호출을 통해 삭제된 경우 '원인'입니다. '명시적'입니다 만료로 인해 쿠키가 자동으로 삭제된 경우 'cause'는 'expired'입니다. 이미 만료된 만료일로 덮어쓰여 쿠키가 삭제된 경우 'cause'가 'expired_overwrite'로 설정됩니다. 가비지 컬렉션으로 인해 쿠키가 자동으로 삭제된 경우 "cause" '제거'됩니다. 덮어쓴 'set' 호출로 인해 쿠키가 자동으로 삭제된 경우 'cause'는 'overwrite'입니다. 이에 따라 응답을 계획합니다.

열거형

'evicted'

"expired_overwrite"

SameSiteStatus

Chrome 51 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

쿠키의 'SameSite' 상태(https://tools.ietf.org/html/draft-west-first-party-cookies) 'no_restriction'은 'SameSite=None'으로 설정된 쿠키에 해당하며, 'lax'는 'SameSite=Lax'에, 'strict'는 'SameSite=Strict'에 해당합니다. '지정되지 않음' SameSite 속성이 없는 쿠키 집합에 해당합니다.

열거형

'strict'

메서드

get()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

단일 쿠키에 관한 정보를 검색합니다. 주어진 URL에 대해 이름이 같은 쿠키가 두 개 이상 있으면 가장 긴 경로를 가진 쿠키가 반환됩니다. 경로 길이가 동일한 쿠키의 경우 생성 시간이 가장 빠른 쿠키가 반환됩니다.

매개변수

  • 세부정보

    CookieDetails

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (cookie?: Cookie) => void

    • 쿠키

      쿠키 선택사항

      쿠키에 관한 세부정보를 포함합니다. 그러한 쿠키가 없는 경우 이 매개변수는 null입니다.

반환 값

  • 프라미스<쿠키 | 정의되지 않음>

    Chrome 88 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼은 콜백을 사용해야 합니다.

getAll()

Promise 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

지정된 정보와 일치하는 단일 쿠키 저장소에서 모든 쿠키를 검색합니다. 반환된 쿠키는 경로가 가장 긴 쿠키 순으로 정렬됩니다. 경로 길이가 동일한 쿠키가 여러 개 있는 경우 생성 시간이 가장 빠른 쿠키가 먼저 표시됩니다. 이 메서드는 확장 프로그램에 호스트 권한이 있는 도메인의 쿠키만 검색합니다.

매개변수

  • 세부정보

    객체

    검색 중인 쿠키를 필터링하기 위한 정보입니다.

    • 도메인

      문자열(선택사항)

      검색된 쿠키를 이 도메인과 일치하거나 이 도메인의 하위 도메인인 쿠키로 제한합니다.

    • 이름

      문자열(선택사항)

      이름으로 쿠키를 필터링합니다.

    • partitionKey

      CookiePartitionKey 선택사항

      Chrome 119 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

      Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.

    • 경로

      문자열(선택사항)

      검색된 쿠키를 이 문자열과 경로가 정확하게 일치하는 쿠키로 제한합니다.

    • 보안

      불리언 선택사항

      보안 속성별로 쿠키를 필터링합니다.

    • 세션

      불리언 선택사항

      세션과 영구 쿠키를 필터링합니다.

    • storeId

      문자열(선택사항)

      쿠키를 가져올 쿠키 저장소입니다. 생략하면 현재 실행 컨텍스트의 쿠키 저장소가 사용됩니다.

    • URL

      문자열(선택사항)

      검색된 쿠키를 지정된 URL과 일치하는 쿠키로 제한합니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (cookies: Cookie[]) => void

    • 쿠키

      쿠키[]

      지정된 쿠키 정보와 일치하는 만료되지 않은 기존 쿠키입니다.

반환 값

  • Promise<Cookie[]>

    Chrome 88 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getAllCookieStores()

Promise 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

모든 기존 쿠키 저장소를 나열합니다.

매개변수

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      모든 기존 쿠키 저장소

반환 값

  • Promise<CookieStore[]>

    Chrome 88 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼은 콜백을 사용해야 합니다.

remove()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

이름별로 쿠키를 삭제합니다.

매개변수

  • 세부정보

    CookieDetails

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (details?: object) => void

    • 세부정보

      객체(선택사항)

      삭제된 쿠키에 관한 세부정보를 포함합니다. 어떠한 이유로든 삭제에 실패하면 'null'이 되고 runtime.lastError가 설정됩니다.

      • 이름

        문자열

        삭제된 쿠키의 이름입니다.

      • partitionKey

        CookiePartitionKey 선택사항

        Chrome 119 이상

        Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.

      • storeId

        문자열

        쿠키가 삭제된 쿠키 스토어의 ID입니다.

      • URL

        문자열

        삭제된 쿠키와 연결된 URL입니다.

반환 값

  • 프라미스<object | 정의되지 않음>

    Chrome 88 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼은 콜백을 사용해야 합니다.

set()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.cookies.set(
  details: object,
  callback?: function,
)

지정된 쿠키 데이터로 쿠키를 설정합니다. 상응하는 쿠키가 있는 경우 해당 쿠키를 덮어쓸 수 있습니다.

매개변수

  • 세부정보

    객체

    설정되는 쿠키에 관한 세부정보입니다.

    • 도메인

      문자열(선택사항)

      쿠키의 도메인입니다. 생략할 경우 쿠키는 호스트 전용 쿠키가 됩니다.

    • expirationDate

      숫자 선택사항

      UNIX 기점을 기준으로 초 단위로 쿠키의 만료일입니다. 생략할 경우 쿠키는 세션 쿠키가 됩니다.

    • httpOnly

      불리언 선택사항

      쿠키를 HttpOnly로 표시해야 하는지 여부입니다. 기본값은 false입니다.

    • 이름

      문자열(선택사항)

      쿠키의 이름입니다. 생략하면 기본적으로 비어 있습니다.

    • partitionKey

      CookiePartitionKey 선택사항

      Chrome 119 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

      Partitioned 속성이 있는 쿠키를 읽거나 수정하기 위한 파티션 키입니다.

    • 경로

      문자열(선택사항)

      쿠키의 경로입니다. 기본값은 url 매개변수의 경로 부분입니다.

    • sameSite

      SameSiteStatus 선택사항

      Chrome 51 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

      쿠키의 동일 사이트 상태입니다. 기본값은 '미지정'입니다. 즉, 생략된 경우 SameSite 속성을 지정하지 않고 쿠키가 설정됩니다.

    • 보안

      불리언 선택사항

      쿠키를 Secure로 표시해야 하는지 여부입니다. 기본값은 false입니다.

    • storeId

      문자열(선택사항)

      쿠키를 설정할 쿠키 저장소의 ID입니다. 기본적으로 쿠키는 현재 실행 컨텍스트의 쿠키 저장소에 설정됩니다.

    • URL

      문자열

      쿠키 설정과 연결할 request-URI입니다. 이 값은 생성된 쿠키의 기본 도메인 및 경로 값에 영향을 줄 수 있습니다. 이 URL의 호스트 권한이 매니페스트 파일에 지정되지 않으면 API 호출이 실패합니다.

    • 값

      문자열(선택사항)

      쿠키의 값입니다. 생략하면 기본적으로 비어 있습니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (cookie?: Cookie) => void

    • 쿠키

      쿠키 선택사항

      설정된 쿠키에 대한 세부정보가 포함됩니다. 어떠한 이유로든 설정이 실패하면 'null'이 되고 runtime.lastError가 설정됩니다.

반환 값

  • Promise<Cookie | undefined>

    Chrome 88 이상

    Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

이벤트

onChanged

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

쿠키가 설정되거나 삭제될 때 실행됩니다. 쿠키의 속성 업데이트는 2단계로 구현됩니다. 즉, 업데이트할 쿠키가 먼저 완전히 삭제되고 '원인'이 포함된 알림이 생성됩니다. (삭제 중) 에서 자세한 내용을 확인하실 수 있습니다. 그런 다음 업데이트된 값으로 새 쿠키가 작성되어 'cause' 'explicit'가 포함된 두 번째 알림이 생성됩니다.

매개변수

  • 콜백

    함수

    callback 매개변수는 다음과 같습니다. 

    (changeInfo: object) => void

    • changeInfo

      객체

      • 쿠키가 변경되는 근본적인 이유입니다.

      • 쿠키

        쿠키

        설정되거나 삭제된 쿠키에 관한 정보입니다.

      • 삭제됨

        부울

        쿠키가 삭제된 경우 true입니다.