chrome.storage

설명

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

권한

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에서 서비스 워커에서 확장 스토리지 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}".`
    );
  }
});

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

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

enum

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

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

StorageArea

속성

  • onChanged

    이벤트<functionvoid>

    Chrome 73 이상

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

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

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

    • 콜백

      기능

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

      (changes: object)=>void

      • 변경사항

        객체

  • 삭제

    void

    프로미스

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

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

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

    • 콜백

      함수 선택사항

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

      ()=>void

    • returns

      Promise<void>

      Chrome 88 이상

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

  • get

    void

    프로미스

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

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

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

    • 키

      string|string[]|object optional

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

    • 콜백

      함수 선택사항

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

      (items: object)=>void

      • items

        객체

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

    • returns

      Promise<object>

      Chrome 88 이상

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

  • getBytesInUse

    void

    프로미스

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

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

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

    • 키

      string|string[] optional

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

    • 콜백

      함수 선택사항

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

      (bytesInUse: number)=>void

      • bytesInUse

        숫자

        저장소에서 사용 중인 공간의 크기(바이트)입니다.

    • returns

      프로미스<number>

      Chrome 88 이상

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

  • remove

    void

    프로미스

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

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

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

    • 키

      문자열|string[]

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

    • 콜백

      함수 선택사항

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

      ()=>void

    • returns

      Promise<void>

      Chrome 88 이상

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

  • set

    void

    프로미스

    여러 항목을 설정합니다.

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

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

    • items

      객체

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

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

    • 콜백

      함수 선택사항

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

      ()=>void

    • returns

      Promise<void>

      Chrome 88 이상

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

  • setAccessLevel

    void

    Promise Chrome 102 이상

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

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

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

    • accessOptions

      객체

      • accessLevel

        AccessLevel

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

    • 콜백

      함수 선택사항

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

      ()=>void

    • returns

      Promise<void>

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

StorageChange

속성

  • newValue

    모든 선택사항

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

  • oldValue

    모든 선택사항

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

속성

local

local 스토리지 영역에 있는 항목은 각 머신의 로컬입니다.

유형

StorageArea객체(&O)

속성

  • QUOTA_BYTES

    10485760

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

managed

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

유형

StorageArea

session

Chrome 102 이상 MV3 이상

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

유형

StorageArea객체(&O)

속성

  • QUOTA_BYTES

    10485760

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

sync

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

유형

StorageArea객체(&O)

속성

  • MAX_ITEMS

    512

    동기화 저장소에 저장할 수 있는 최대 항목 수입니다. 이 한도를 초과하는 업데이트는 즉시 실패하며 콜백을 사용하거나 프로미스를 거부할 때 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

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

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

  • QUOTA_BYTES

    102400

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

  • QUOTA_BYTES_PER_ITEM

    8192

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

이벤트

onChanged

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

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

매개변수

  • 콜백

    기능

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

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

    • 변경사항

      객체

    • areaName

      문자열