chrome.cookies

설명

chrome.cookies API를 사용하여 쿠키를 쿼리하고 수정하며 쿠키가 변경될 때 알림을 받습니다.

권한

cookies

매니페스트

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

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

파티션 나누기

분할된 쿠키를 사용하면 사이트에서 특정 쿠키가 최상위 프레임의 출처에 대해 키를 지정해야 한다고 표시할 수 있습니다. 즉, 사이트 A가 사이트 B 및 사이트 C에 iframe을 사용하여 삽입된 경우 파티션된 쿠키는 각각 다른 값을 가질 수 있습니다.

chrome.cookies는 파티셔닝을 지원하지 않으므로 모든 메서드는 모든 파티션에서 쿠키를 읽고 씁니다. cookies.set() 메서드는 기본 파티션에 쿠키를 저장합니다.

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

예

examples/api/cookies 디렉터리에서 쿠키 API를 사용하는 간단한 예시를 확인할 수 있습니다. 다른 예와 소스 코드 보기에 관한 도움말은 샘플을 참고하세요.

유형

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

속성

  • 도메인

    문자열

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

  • expirationDate

    번호 선택사항

    쿠키의 만료일로 UNIX epoch 이후의 초입니다. 세션 쿠키에는 제공되지 않습니다.

  • 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

    number[]

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

FrameDetails

대기 중

프레임을 식별하는 세부정보입니다.

속성

  • documentId

    문자열 선택사항

    문서의 고유 식별자입니다. frameId 또는 tabId가 제공되면 제공된 문서 ID로 찾은 문서와 일치하는지 확인됩니다.

  • frameId

    번호 선택사항

    탭 내 프레임의 고유 식별자입니다.

  • tabId

    번호 선택사항

    프레임이 포함된 탭의 고유 식별자입니다.

OnChangedCause

Chrome 44 이상

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

열거형

'evicted'

'expired'

'명시적'

"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'에 해당합니다. 'unspecified'는 SameSite 속성이 없는 쿠키 세트에 해당합니다.

열거형

"no_restriction"

'lax'

'strict'

'지정되지 않음'

메서드

get()

Promise 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

단일 쿠키에 관한 정보를 검색합니다. 지정된 URL에 동일한 이름의 쿠키가 두 개 이상 있는 경우 경로가 가장 긴 쿠키가 반환됩니다. 경로 길이가 동일한 쿠키의 경우 생성 시간이 가장 빠른 쿠키가 반환됩니다.

매개변수

  • 세부정보

    CookieDetails

  • 콜백

    함수 선택사항

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

    (cookie?: Cookie) => void

    • 쿠키

      쿠키 선택사항

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

반환 값

  • Promise<Cookie | undefined>

    Chrome 88 이상

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

getAll()

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

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

매개변수

  • 세부정보

    객체

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

    • 도메인

      문자열 선택사항

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

    • 이름

      문자열 선택사항

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

    • partitionKey

      CookiePartitionKey 선택사항

      Chrome 119 이상

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

    • 경로

      문자열 선택사항

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

    • 보안

      불리언 선택사항

      Secure 속성으로 쿠키를 필터링합니다.

    • 세션

      불리언 선택사항

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

    • 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 이상

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

getPartitionKey()

Promise 대기 중
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

표시된 프레임의 파티션 키입니다.

매개변수

  • 세부정보

    FrameDetails

  • 콜백

    함수 선택사항

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

    (details: object) => void

    • 세부정보

      객체

      검색된 파티션 키에 관한 세부정보를 포함합니다.

      • partitionKey

        CookiePartitionKey

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

반환 값

  • Promise<object>

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

remove()

Promise 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

이름을 기준으로 쿠키를 삭제합니다.

매개변수

  • 세부정보

    CookieDetails

  • 콜백

    함수 선택사항

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

    (details?: object) => void

    • 세부정보

      객체 선택사항

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

      • 이름

        문자열

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

      • partitionKey

        CookiePartitionKey 선택사항

        Chrome 119 이상

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

      • storeId

        문자열

        쿠키가 삭제된 쿠키 저장소의 ID입니다.

      • URL

        문자열

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

반환 값

  • Promise<object | undefined>

    Chrome 88 이상

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

set()

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

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

매개변수

  • 세부정보

    객체

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

    • 도메인

      문자열 선택사항

      쿠키의 도메인입니다. 생략하면 쿠키가 호스트 전용 쿠키가 됩니다.

    • 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 호출이 실패합니다.

    • 값

      문자열 선택사항

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

  • 콜백

    함수 선택사항

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

    (cookie?: Cookie) => void

    • 쿠키

      쿠키 선택사항

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

반환 값

  • Promise<Cookie | undefined>

    Chrome 88 이상

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

이벤트

onChanged

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

쿠키가 설정되거나 삭제될 때 실행됩니다. 특수한 경우로, 쿠키 속성 업데이트는 두 단계 프로세스로 구현됩니다. 먼저 업데이트할 쿠키가 완전히 삭제되고 'cause'가 'overwrite'인 알림이 생성됩니다. 그런 다음 업데이트된 값으로 새 쿠키가 작성되어 'cause' 'explicit'가 포함된 두 번째 알림이 생성됩니다.

매개변수

  • 콜백

    함수

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

    (changeInfo: object) => void

    • changeInfo

      객체

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

      • 쿠키

        쿠키

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

      • 삭제됨

        부울

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