chrome.storage

설명

chrome.storage API를 사용하여 사용자 데이터의 변경사항을 저장, 검색, 추적합니다.

권한

storage

스토리지 API를 사용하려면 확장 프로그램 매니페스트에서 "storage" 권한을 선언합니다. 예를 들면 다음과 같습니다.

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

개념 및 사용

Storage API는 사용자 데이터와 상태를 유지하는 확장 프로그램별 방법을 제공합니다. 웹 플랫폼의 스토리지 API (IndexedDB 및 Storage)와 유사하지만 확장 프로그램의 스토리지 요구사항을 충족하도록 설계되었습니다. 다음은 몇 가지 주요 기능입니다.

  • 확장 프로그램 서비스 워커 및 콘텐츠 스크립트를 비롯한 모든 확장 프로그램 컨텍스트는 Storage API에 액세스할 수 있습니다.
  • JSON 직렬화 가능한 값은 객체 속성으로 저장됩니다.
  • Storage API는 일괄 읽기 및 쓰기 작업과 비동기식입니다.
  • 사용자가 캐시와 방문 기록을 삭제해도 데이터는 유지됩니다.
  • 저장된 설정은 분할 시크릿 모드를 사용하는 경우에도 유지됩니다.
  • 엔터프라이즈 정책을 위한 전용 읽기 전용 관리 스토리지 영역이 포함되어 있습니다.

확장 프로그램에서 웹 저장소 API를 사용할 수 있나요?

확장 프로그램은 일부 컨텍스트 (팝업 및 기타 HTML 페이지)에서 Storage 인터페이스 (window.localStorage에서 액세스 가능)를 사용할 수 있지만 다음과 같은 이유로 권장하지 않습니다.

  • 확장 프로그램 서비스 워커는 Web Storage API를 사용할 수 없습니다.
  • 콘텐츠 스크립트는 호스트 페이지와 스토리지를 공유합니다.
  • Web Storage API를 사용하여 저장된 데이터는 사용자가 방문 기록을 삭제하면 손실됩니다.

서비스 워커에서 웹 저장소 API의 데이터를 확장 프로그램 저장소 API로 이동하려면 다음 단계를 따르세요.

  1. 오프스크린 문서 HTML 페이지와 스크립트 파일을 준비합니다. 스크립트 파일에는 변환 루틴과 onMessage 핸들러가 포함되어야 합니다.
  2. 확장 프로그램 서비스 작업자에서 데이터의 chrome.storage를 확인합니다.
  3. 데이터를 찾을 수 없는 경우 createDocument()를 호출합니다.
  4. 반환된 Promise가 해결되면 sendMessage()를 호출하여 변환 루틴을 시작합니다.
  5. 오프스크린 문서의 onMessage 핸들러 내에서 변환 루틴을 호출합니다.

또한 웹 저장소 API가 확장 프로그램에서 작동하는 방식에는 약간의 차이점이 있습니다. 저장용량 및 쿠키 도움말에서 자세히 알아보세요.

저장소 영역

Storage API는 다음과 같은 스토리지 영역으로 나뉩니다.

storage.local
데이터는 로컬에 저장되며 확장 프로그램이 삭제되면 삭제됩니다. 저장용량 한도는 10MB (Chrome 113 이하에서는 5MB)이지만 "unlimitedStorage" 권한을 요청하여 늘릴 수 있습니다. 대용량 데이터를 저장하려면 storage.local를 사용하는 것이 좋습니다.
storage.managed
관리 저장소는 정책이 설치된 확장 프로그램의 읽기 전용 저장소이며 개발자가 정의한 스키마와 엔터프라이즈 정책을 사용하여 시스템 관리자가 관리합니다. 정책은 옵션과 유사하지만 사용자 대신 시스템 관리자가 구성하므로 조직의 모든 사용자를 위해 확장 프로그램을 사전 구성할 수 있습니다. 정책에 대한 자세한 내용은 관리자 문서를 참고하세요. managed 저장소 영역에 관한 자세한 내용은 저장소 영역 매니페스트를 참고하세요.
storage.session
브라우저 세션이 진행되는 동안 메모리에 데이터를 보관합니다. 기본적으로 콘텐츠 스크립트에 노출되지 않지만 chrome.storage.session.setAccessLevel()를 설정하여 이 동작을 변경할 수 있습니다. 저장용량 한도는 10MB (Chrome 111 이하에서는 1MB)입니다. storage.session 인터페이스는 서비스 워커에 권장되는 여러 인터페이스 중 하나입니다.
storage.sync
동기화가 사용 설정된 경우 데이터는 사용자가 로그인한 모든 Chrome 브라우저에 동기화됩니다. 사용 중지하면 storage.local처럼 작동합니다. Chrome은 브라우저가 오프라인 상태일 때 데이터를 로컬에 저장하고 다시 온라인 상태가 되면 동기화를 재개합니다. 할당량 제한은 약 100KB(항목당 8KB)입니다. 동기화된 브라우저에서 사용자 설정을 보존하려면 storage.sync를 사용하는 것이 좋습니다. 민감한 사용자 데이터를 사용하는 경우 대신 storage.session를 사용하세요.

저장용량 및 제한hrottling

Storage API에는 다음과 같은 사용량 제한사항이 있습니다.

  • 데이터를 저장하면 성능 비용이 발생하는 경우가 많으며 API에는 스토리지 할당량이 포함됩니다. 데이터 저장 기능을 사용하지 못하게 되지 않도록 저장하는 데이터에 주의하는 것이 좋습니다.
  • 저장소를 완료하는 데 시간이 걸릴 수 있습니다. 이 시간을 고려하도록 코드 구조를 정의해야 합니다.

저장소 영역 제한 및 제한을 초과할 경우 발생하는 상황에 관한 자세한 내용은 sync, local, session의 할당량 정보를 참고하세요.

사용 사례

다음 섹션에서는 Storage API의 일반적인 사용 사례를 보여줍니다.

스토리지 업데이트에 대한 동기식 응답

저장소에 적용된 변경사항을 추적하려면 onChanged 이벤트에 리스너를 추가합니다. 저장소에서 변경사항이 있으면 해당 이벤트가 실행됩니다. 샘플 코드는 다음 변경사항을 리슨합니다.

background.js:

chrome.storage.onChanged.addListener((changes, namespace) => {
  for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(
      `Storage key "${key}" in namespace "${namespace}" changed.`,
      `Old value was "${oldValue}", new value is "${newValue}".`
    );
  }
});

이 아이디어를 더 발전시킬 수 있습니다. 이 예에서는 사용자가 '디버그 모드'를 전환할 수 있는 옵션 페이지가 있습니다(여기에 구현은 표시되지 않음). 옵션 페이지는 새 설정을 즉시 storage.sync에 저장하고 서비스 워커는 storage.onChanged를 사용하여 설정을 최대한 빨리 적용합니다.

options.html:

<!-- type="module" allows you to use top level await -->
<script defer src="options.js" type="module"></script>
<form id="optionsForm">
  <label for="debug">
    <input type="checkbox" name="debug" id="debug">
    Enable debug mode
  </label>
</form>

options.js:

// In-page cache of the user's options
const options = {};
const optionsForm = document.getElementById("optionsForm");

// Immediately persist options changes
optionsForm.debug.addEventListener("change", (event) => {
  options.debug = event.target.checked;
  chrome.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await chrome.storage.sync.get("options");
Object.assign(options, data.options);
optionsForm.debug.checked = Boolean(options.debug);

background.js:

function setDebugMode() { /* ... */ }

// Watch for changes to the user's options & apply them
chrome.storage.onChanged.addListener((changes, area) => {
  if (area === 'sync' && changes.options?.newValue) {
    const debugMode = Boolean(changes.options.newValue.debug);
    console.log('enable debug mode?', debugMode);
    setDebugMode(debugMode);
  }
});

스토리지에서 비동기 미리 로드

서비스 워커는 항상 실행되지 않으므로 매니페스트 V3 확장 프로그램은 이벤트 핸들러를 실행하기 전에 스토리지에서 데이터를 비동기식으로 로드해야 하는 경우가 있습니다. 이를 위해 다음 스니펫은 로직을 실행하기 전에 storageCache 전역이 채워질 때까지 기다리는 비동기 action.onClicked 이벤트 핸들러를 사용합니다.

background.js:

// Where we will expose all the data we retrieve from storage.sync.
const storageCache = { count: 0 };
// Asynchronously retrieve data from storage.sync, then cache it.
const initStorageCache = chrome.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

chrome.action.onClicked.addListener(async (tab) => {
  try {
    await initStorageCache;
  } catch (e) {
    // Handle error that occurred during storage initialization.
  }

  // Normal action handler logic.
  storageCache.count++;
  storageCache.lastTabId = tab.id;
  chrome.storage.sync.set(storageCache);
});

예

다음 샘플은 local, sync, session 저장소 영역을 보여줍니다.

지역

chrome.storage.local.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.local.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

동기화

chrome.storage.sync.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.sync.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

세션

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value was set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Storage API의 다른 데모를 보려면 다음 샘플을 살펴보세요.

유형

AccessLevel

Chrome 102 이상

저장소 영역의 액세스 수준입니다.

열거형

"TRUSTED_CONTEXTS"
확장 프로그램 자체에서 발생한 컨텍스트를 지정합니다.

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
확장 프로그램 외부에서 발생한 컨텍스트를 지정합니다.

StorageArea

속성

  • onChanged

    Event<functionvoidvoid>

    Chrome 73 이상

    하나 이상의 항목이 변경될 때 실행됩니다.

    onChanged.addListener 함수는 다음과 같습니다. 

    (callback: function) => {...}

    • 콜백

      함수

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

      (changes: object) => void

      • 변경사항

        객체

  • 지우기

    void

    Promise

    저장소에서 모든 항목을 삭제합니다.

    clear 함수는 다음과 같습니다. 

    (callback?: function) => {...}

    • 콜백

      함수 선택사항

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

      () => void

    • returns

      Promise<void>

      Chrome 88 이상

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

  • get

    void

    Promise

    저장소에서 항목을 하나 이상 가져옵니다.

    get 함수는 다음과 같습니다. 

    (keys?: string | string[] | object, callback?: function) => {...}

    • 키

      string | string[] | object 선택사항

      가져올 단일 키, 가져올 키 목록 또는 기본값을 지정하는 사전입니다 (객체 설명 참고). 빈 목록이나 객체는 빈 결과 객체를 반환합니다. null를 전달하여 저장소의 전체 콘텐츠를 가져옵니다.

    • 콜백

      함수 선택사항

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

      (items: object) => void

      • 항목

        객체

        키-값 매핑에 항목이 있는 객체입니다.

    • returns

      Promise<object>

      Chrome 88 이상

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

  • getBytesInUse

    void

    Promise

    하나 이상의 항목에서 사용 중인 공간 (바이트)을 가져옵니다.

    getBytesInUse 함수는 다음과 같습니다. 

    (keys?: string | string[], callback?: function) => {...}

    • 키

      문자열 | string[] 선택사항

      총 사용량을 가져올 단일 키 또는 키 목록입니다. 빈 목록은 0을 반환합니다. null를 전달하여 모든 스토리지의 총 사용량을 가져옵니다.

    • 콜백

      함수 선택사항

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

      (bytesInUse: number) => void

      • bytesInUse

        숫자

        스토리지에서 사용 중인 공간(단위: 바이트)입니다.

    • returns

      Promise<number>

      Chrome 88 이상

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

  • getKeys

    void

    Promise Chrome 130 이상

    저장소에서 모든 키를 가져옵니다.

    getKeys 함수는 다음과 같습니다. 

    (callback?: function) => {...}

    • 콜백

      함수 선택사항

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

      (keys: string[]) => void

      • 키

        문자열[]

        저장소에서 읽은 키가 있는 배열입니다.

    • returns

      Promise<string[]>

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

  • 삭제

    void

    Promise

    저장소에서 하나 이상의 항목을 삭제합니다.

    remove 함수는 다음과 같습니다. 

    (keys: string | string[], callback?: function) => {...}

    • 키

      문자열 | 문자열[]

      삭제할 항목의 키 하나 또는 키 목록입니다.

    • 콜백

      함수 선택사항

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

      () => void

    • returns

      Promise<void>

      Chrome 88 이상

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

  • set

    void

    Promise

    여러 항목을 설정합니다.

    set 함수는 다음과 같습니다. 

    (items: object, callback?: function) => {...}

    • 항목

      객체

      저장소를 업데이트할 각 키-값 쌍을 제공하는 객체입니다. 저장소의 다른 키/값 쌍은 영향을 받지 않습니다.

      숫자와 같은 원시 값은 예상대로 직렬화됩니다. typeof "object" 및 "function"가 있는 값은 일반적으로 {}로 직렬화됩니다. 단, Array (예상대로 직렬화됨), Date, Regex (String 표현식을 사용하여 직렬화됨)는 예외입니다.

    • 콜백

      함수 선택사항

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

      () => void

    • returns

      Promise<void>

      Chrome 88 이상

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

  • setAccessLevel

    void

    Promise Chrome 102 이상

    저장소 영역의 원하는 액세스 수준을 설정합니다. 기본값은 신뢰할 수 있는 컨텍스트만 됩니다.

    setAccessLevel 함수는 다음과 같습니다. 

    (accessOptions: object, callback?: function) => {...}

    • accessOptions

      객체

      • accessLevel

        AccessLevel

        저장소 영역의 액세스 수준입니다.

    • 콜백

      함수 선택사항

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

      () => void

    • returns

      Promise<void>

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

StorageChange

속성

  • newValue

    any 선택사항

    새 값이 있는 경우 항목의 새 값입니다.

  • oldValue

    any 선택사항

    이전 값이 있는 경우 항목의 이전 값입니다.

속성

local

local 저장소 영역의 항목은 각 머신에 로컬로 있습니다.

유형

StorageArea 및 객체

속성

  • QUOTA_BYTES

    10485760

    모든 값의 JSON 문자열화와 모든 키의 길이를 합산하여 측정한 로컬 저장소에 저장할 수 있는 최대 데이터 양 (바이트)입니다. 확장 프로그램에 unlimitedStorage 권한이 있는 경우 이 값은 무시됩니다. 이 한도가 초과되는 업데이트는 즉시 실패하고 콜백을 사용하는 경우 runtime.lastError를 설정하거나 async/await를 사용하는 경우 거부된 Promise를 설정합니다.

managed

managed 저장소 영역의 항목은 도메인 관리자가 구성한 엔터프라이즈 정책에 의해 설정되며 확장 프로그램에 대해 읽기 전용입니다. 이 네임스페이스를 수정하려고 하면 오류가 발생합니다. 정책 구성에 관한 자세한 내용은 저장소 영역 매니페스트를 참고하세요.

유형

StorageArea

session

Chrome 102 이상 MV3 이상

session 저장소 영역의 항목은 메모리에 저장되며 디스크에 유지되지 않습니다.

유형

StorageArea 및 객체

속성

  • QUOTA_BYTES

    10485760

    모든 값과 키의 동적으로 할당된 메모리 사용량을 추정하여 측정한 값으로, 메모리에 저장할 수 있는 최대 데이터 양 (바이트)입니다. 이 한도가 초과되는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때 runtime.lastError를 설정합니다.

sync

sync 저장소 영역의 항목은 Chrome 동기화를 사용하여 동기화됩니다.

유형

StorageArea 및 객체

속성

  • MAX_ITEMS

    512

    동기화 저장소에 저장할 수 있는 최대 항목 수입니다. 이 한도를 초과하게 되는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때 runtime.lastError를 설정합니다.

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    지원 중단됨

    storage.sync API에 더 이상 지속적인 쓰기 작업 할당량이 없습니다.

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    시간당 실행할 수 있는 최대 set, remove, clear 작업 수입니다. 2초마다 1회로, 이는 단기적으로 더 높은 분당 쓰기 한도보다 낮은 한도입니다.

    이 한도가 초과되는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때 runtime.lastError를 설정합니다.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    분당 실행할 수 있는 최대 set, remove, clear 작업 수입니다. 초당 2회이므로 더 짧은 시간에 시간당 쓰기보다 높은 처리량을 제공합니다.

    이 한도가 초과되는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때 runtime.lastError를 설정합니다.

  • QUOTA_BYTES

    102400

    동기화 저장소에 저장할 수 있는 최대 총 데이터 양 (바이트)으로, 모든 값의 JSON 문자열화와 모든 키의 길이를 합산하여 측정합니다. 이 한도가 초과되는 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때 runtime.lastError를 설정합니다.

  • QUOTA_BYTES_PER_ITEM

    8192

    동기화 저장소에 있는 각 개별 항목의 최대 크기 (바이트)로, 값의 JSON 문자열화와 키 길이를 합산하여 측정합니다. 이 한도보다 큰 항목이 포함된 업데이트는 즉시 실패하고 콜백을 사용하거나 Promise가 거부될 때 runtime.lastError를 설정합니다.

이벤트

onChanged

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

하나 이상의 항목이 변경될 때 실행됩니다.

매개변수

  • 콜백

    함수

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

    (changes: object, areaName: string) => void

    • 변경사항

      객체

    • areaName

      문자열