chrome.storage

설명

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

권한

storage

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

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

개념 및 사용법

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

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

확장 프로그램에서 Web Storage API를 사용할 수 있나요?

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

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

서비스 워커에서 Web Storage API에서 Extension Storage API로 데이터를 이동하려면 다음 안내를 따르세요.

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

또한 확장 프로그램에서 Web Storage 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를 대신 사용하세요.

스토리지 및 제한 한도

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}".`
    );
  }
});

Google은 이 아이디어를 더욱 발전시킬 수 있습니다. 이 예에는 옵션 페이지가 있습니다. 사용자는 '디버그 모드'를 사용하여 (여기에 표시되지 않은 구현) 옵션 페이지는 새 설정을 즉시 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);
  }
});

저장소에서 비동기식 미리 로드

서비스 워커가 항상 실행되는 것은 아니므로 Manifest 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"
확장 프로그램 자체에서 발생한 컨텍스트를 지정합니다.

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

StorageArea

속성

  • onChanged

    이벤트<functionvoid>

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

    하나 이상의 항목이 변경되면 실행됩니다.

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

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

    • 콜백

      함수

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

      (changes: object) => void

      • 변경사항

        객체

  • 지우기

    void

    <ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

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

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

    • 콜백

      함수 선택사항

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

      () => void

    • returns

      프로미스<void>

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

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

  • get

    void

    <ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

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

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

    • 키

      string | string[] | 객체(선택사항)

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

    • 콜백

      함수 선택사항

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

      (items: object) => void

      • items

        객체

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

    • returns

      Promise&lt;object&gt;

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

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

  • getBytesInUse

    void

    <ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

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

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

    • 키

      string | string[] 선택사항

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

    • 콜백

      함수 선택사항

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

      (bytesInUse: number) => void

      • bytesInUse

        숫자

        스토리지에서 사용 중인 공간의 크기(바이트)입니다.

    • returns

      Promise&lt;number&gt;

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

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

  • getKeys

    void

    <ph type="x-smartling-placeholder"></ph> 프로미스 대기 중

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

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

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

    • 콜백

      함수 선택사항

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

      (keys: string[]) => void

      • 키

        문자열[]

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

    • returns

      Promise&lt;string[]&gt;

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

  • 삭제

    void

    <ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

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

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

    • 키

      string | 문자열[]

      삭제할 항목의 단일 키 또는 키 목록입니다.

    • 콜백

      함수 선택사항

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

      () => void

    • returns

      프로미스<void>

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

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

  • set

    void

    <ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

    여러 항목을 설정합니다.

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

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

    • items

      객체

      스토리지를 업데이트하는 각 키-값 쌍을 제공하는 객체입니다. 스토리지의 다른 키-값 쌍은 영향을 받지 않습니다.

      숫자와 같은 기본 값은 예상대로 직렬화됩니다. typeof "object" 및 "function"인 값은 일반적으로 {}로 직렬화되지만 Array (예상대로 직렬화), Date, Regex (String 표현을 사용하여 직렬화)는 예외입니다.

    • 콜백

      함수 선택사항

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

      () => void

    • returns

      프로미스<void>

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

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

  • setAccessLevel

    void

    <ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 102 이상

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

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

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

    • accessOptions

      객체

      • accessLevel

        AccessLevel

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

    • 콜백

      함수 선택사항

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

      () => void

    • returns

      프로미스<void>

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

StorageChange

속성

  • newValue

    선택사항

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

  • oldValue

    선택사항

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

속성

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

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

sync

sync 저장용량 영역에 있는 항목은 Chrome 동기화를 통해 동기화됩니다.

유형

StorageArea 및 객체

속성

  • MAX_ITEMS

    512

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

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    <ph type="x-smartling-placeholder"></ph> 지원 중단됨

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

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    매시간 수행할 수 있는 set, remove 또는 clear 작업의 최대 개수입니다. 이는 2초에 1개로, 단기적으로 높은 분당 쓰기 한도보다 낮은 상한입니다.

    이 한도를 초과하도록 하는 업데이트는 즉시 실패하며 콜백을 사용하거나 프로미스가 거부될 때 runtime.lastError를 설정합니다.

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

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

    이 한도를 초과하도록 하는 업데이트는 즉시 실패하며 콜백을 사용하거나 프로미스가 거부될 때 runtime.lastError를 설정합니다.

  • QUOTA_BYTES

    102400

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

  • QUOTA_BYTES_PER_ITEM

    8192

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

이벤트

onChanged

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

하나 이상의 항목이 변경되면 실행됩니다.

매개변수

  • 콜백

    함수

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

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

    • 변경사항

      객체

    • areaName

      문자열