chrome.cookies

설명

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

권한

cookies

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

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

파티션 나누기

파티션을 나눈 쿠키를 사용하면 사이트에서 특정 쿠키가 최상위 프레임의 출처에 대해 키가 지정되어야 한다고 표시할 수 있습니다. 즉, 예를 들어 사이트 A가 iframe을 사용하여 사이트 B와 사이트 C에 삽입된 경우 A에서 파티션을 나눈 쿠키의 삽입 버전은 B와 C에서 서로 다른 값을 가질 수 있습니다.

기본적으로 모든 API 메서드는 파티션을 나누지 않은 쿠키에서 작동합니다. partitionKey 속성을 사용하여 이 동작을 재정의할 수 있습니다.

확장 프로그램의 파티션 나누기가 미치는 일반적인 영향에 관한 자세한 내용은 스토리지 및 쿠키를 참고하세요.

예

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

유형

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

속성

  • 도메인

    string

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

  • expirationDate

    number 선택사항

    UNIX 에포크 이후의 시간(초)으로 표시되는 쿠키 만료일입니다. 세션 쿠키에는 제공되지 않습니다.

  • hostOnly

    boolean

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

  • httpOnly

    boolean

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

  • 이름

    string

    쿠키의 이름입니다.

  • partitionKey

    CookiePartitionKey 선택사항

    Chrome 119 이상

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

  • 경로

    string

    쿠키의 경로입니다.

  • sameSite

    SameSiteStatus

    Chrome 51 이상

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

  • 보안

    boolean

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

  • session

    boolean

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

  • storeId

    string

    getAllCookieStores()에서 제공된 이 쿠키가 포함된 쿠키 저장소의 ID입니다.

  • 값

    string

    쿠키의 값입니다.

CookieDetails

Chrome 88 이상

쿠키 식별을 위한 세부정보입니다.

속성

  • 이름

    string

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

  • partitionKey

    CookiePartitionKey 선택사항

    Chrome 119 이상

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

  • storeId

    문자열 선택사항

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

  • url

    string

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

CookiePartitionKey

Chrome 119 이상

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

속성

  • topLevelSite

    문자열 선택사항

    파티션을 나눈 쿠키를 사용할 수 있는 최상위 사이트입니다.

CookieStore

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

속성

  • id

    string

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

  • tabIds

    숫자[]

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

OnChangedCause

Chrome 44 이상

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

열거형

"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()

프로미스 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

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

매개변수

  • 세부정보

    CookieDetails

  • 콜백

    함수 선택사항

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

    (cookie?: Cookie)=>void

    • 쿠키

      쿠키 선택사항

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

반환 값

  • 프로미스<쿠키|undefined>

    Chrome 88 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getAll()

프로미스 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

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

매개변수

  • 세부정보

    객체

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

    • 도메인

      문자열 선택사항

      가져온 쿠키를 이 도메인의 하위 도메인과 일치하거나 하위 도메인인 쿠키로 제한합니다.

    • 이름

      문자열 선택사항

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

    • partitionKey

      CookiePartitionKey 선택사항

      Chrome 119 이상

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

    • 경로

      문자열 선택사항

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

    • 보안

      부울 선택사항

      보안 속성을 기준으로 쿠키를 필터링합니다.

    • session

      부울 선택사항

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

    • storeId

      문자열 선택사항

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

    • url

      문자열 선택사항

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

  • 콜백

    함수 선택사항

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

    (cookies: Cookie[])=>void

    • 쿠키

      쿠키[]

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

반환 값

  • Promise<Cookie[]>

    Chrome 88 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getAllCookieStores()

프로미스 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

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

매개변수

  • 콜백

    함수 선택사항

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

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

      기존의 모든 쿠키 저장소

반환 값

  • Promise<CookieStore[]>

    Chrome 88 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

remove()

프로미스 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

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

매개변수

  • 세부정보

    CookieDetails

  • 콜백

    함수 선택사항

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

    (details?: object)=>void

    • 세부정보

      객체 선택사항

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

      • 이름

        string

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

      • partitionKey

        CookiePartitionKey 선택사항

        Chrome 119 이상

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

      • storeId

        string

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

      • url

        string

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

반환 값

  • Promise<object|undefined>

    Chrome 88 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

set()

프로미스 
chrome.cookies.set(
  details: object,
  callback?: function,
)

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

매개변수

  • 세부정보

    객체

    설정 중인 쿠키에 대한 세부정보입니다.

    • 도메인

      문자열 선택사항

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

    • expirationDate

      number 선택사항

      UNIX 에포크 이후의 시간(초)으로 표시되는 쿠키 만료일입니다. 생략하면 쿠키가 세션 쿠키가 됩니다.

    • httpOnly

      부울 선택사항

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

    • 이름

      문자열 선택사항

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

    • partitionKey

      CookiePartitionKey 선택사항

      Chrome 119 이상

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

    • 경로

      문자열 선택사항

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

    • sameSite

      SameSiteStatus 선택사항

      Chrome 51 이상

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

    • 보안

      부울 선택사항

      쿠키를 '보안'으로 표시할지 여부입니다. 기본값은 거짓입니다.

    • storeId

      문자열 선택사항

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

    • url

      string

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

    • 값

      문자열 선택사항

      쿠키의 값입니다. 생략된 경우 기본적으로 비어 있습니다.

  • 콜백

    함수 선택사항

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

    (cookie?: Cookie)=>void

    • 쿠키

      쿠키 선택사항

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

반환 값

  • 프로미스<쿠키|undefined>

    Chrome 88 이상

    프로미스는 Manifest V3 이상에서 지원되지만 콜백은 이전 버전과의 호환성을 위해 제공됩니다. 동일한 함수 호출에 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

이벤트

onChanged

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

쿠키가 설정되거나 삭제되면 시작됩니다. 쿠키의 속성 업데이트는 2단계 프로세스로 구현됩니다. 즉, 업데이트할 쿠키가 먼저 완전히 삭제되고 '덮어쓰기' '원인'이 포함된 알림이 생성됩니다. 그런 다음 업데이트된 값으로 새 쿠키가 작성되어 '원인'이 '명시적'인 두 번째 알림이 생성됩니다.

매개변수

  • 콜백

    기능

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

    (changeInfo: object)=>void

    • changeInfo

      객체

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

      • 쿠키

        쿠키

        설정 또는 삭제된 쿠키에 대한 정보입니다.

      • 삭제됨

        boolean

        쿠키가 삭제되면 true입니다.