집
chrome-extensions
googlechrome/modern-web-guidance
Manifest V3의 모범 사례를 활용하여 Chrome 확장 프로그램을 제작하고 배포하세요. 사용자가 Chrome 브라우저 확장 프로그램, 애드온, 또는 Chrome Extensions API와 관련된 내용을 만들거나 수정하고, 디버깅하거나 이해하고자 할 때 이 기술을 활용할 수 있습니다. 다음 용어가 언급될 때 자동으로 적용됩니다: ‘Chrome extension’, ‘browser extension’, ‘manifest.json’, ‘content script’, ‘service worker’(브라우저 컨텍스트 내), ‘popup’(Chrome 확장 프로그램 컨텍스트 내), ‘side panel’, ‘chrome.* API’, ‘declarativeNetRequest’, ‘omnibox’, ‘context menu’(확장 프로그램 내).
...모든 것을 확장하십시오Chrome 확장 프로그램에 대하여
Manifest V3를 활용해 실제 사용에 적합한 품질의 Chrome 확장 프로그램을 제작하고 Chrome 웹 스토어에 게시하는 방법을 안내합니다. 이 가이드는 콘텐츠 스크립트, 서비스 워커, 팝업, 사이드 패널, declarativeNetRequest, 옴니박스, 컨텍스트 메뉴, 사용자 스크립트와 같은 Chrome 브라우저 확장 프로그램 및 chrome.* API를 만들거나 수정하고, 디버깅하거나 이해하는 작업이 있을 때마다 참고할 수 있습니다. 또한 권한 설명이나 개인정보 처리방침과 같은 웹 스토어 게시 관련 작업에도 적용됩니다.
제작 관련 내용은 확장 프로그램이 오류를 일으키는 가장 흔한 원인들을 해결하기 위한 필수 규칙들로 구성되어 있습니다. 예를 들어 실제로 존재하는 아이콘 파일만 참조하거나 아이콘을 전혀 사용하지 않는 경우, 사이드 패널을 열기 위한 명시적인 트리거를 제공해야 하며(단순히 default_path만으로는 열리지 않음), 확장 프로그램의 CSP가 eval 및 인라인 스크립트를 차단하기 때문에 코드는 반드시 샌드박스화된 iframe 내에서만 실행되어야 합니다. 또한 tab.url을 읽기 전에 먼저 탭 관련 권한을 선언하고, .then() 체인 대신 항상 async/await를 사용해야 하며, 메인 스레드가 막히는 것을 방지하기 위해 콘텐츠 스크립트 내의 DOM 작업은 일괄 처리해야 합니다. 서비스 워커는 일시적인 존재이므로 서비스 워커 변수에 상태를 저장해서는 안 되며, 대신 chrome.storage에 데이터를 저장하고 setTimeout 대신 chrome.alarms를 사용해야 합니다. 추가 규칙들로는 manifest 키를 통해 chrome.identity OAuth의 확장 프로그램 ID를 안정적으로 관리하고, 컨텍스트 메뉴 작업 후 사용자에게 피드백을 제공하며, 서비스 워커, 팝업, 사이드 패널 전반에서 Extension-Available LanguageModel(Prompt API)을 활용하는 방법, 그리고 chrome.action을 사용하기 전에 manifest에 액션 키를 반드시 포함시키는 방법 등이 있습니다.
이 가이드는 섬세한 Manifest V3 관련 문제를 디버깅하는 대신, 처음부터 제대로 작동하며 심사를 통과할 수 있는 확장 프로그램을 만들고자 할 때 유용합니다. 각 규칙은 오류가 있는 코드와 올바른 코드를 비교해 보여주며, 아이콘, 사이드 패널, CSP 샌드박스, 탭 관리, 콘텐츠 스크립트, 서비스 워커, 인증/정체성 관리, 컨텍스트 메뉴, Prompt API 등과 관련된 보다 상세한 참고 자료로 연결됩니다. 두 번째 파트에서는 확장 프로그램을 준비하는 방법부터 심사 거절에 대응하는 방법, 권한 설명 작성법, 개인정보 처리방침 작성법까지 포함하여 첫 번째 빌드부터 웹 스토어 등록에 이르는 전체 라이프사이클에 걸쳐 활용할 수 있습니다.
자주 묻는 질문
이 기술은 언제 사용해야 하나요?
Chrome 확장 프로그램 및 Chrome Extensions API를 만들거나 수정하고, 디버깅하거나 이해하는 작업을 할 때나, 권한 설명이나 개인정보 처리방침을 포함하여 Chrome 웹 스토어에 게시할 때 사용합니다.
manifest에 정의했는데 사이드 패널이 왜 열리지 않나요?
side_panel.default_path만으로는 사이드 패널이 자동으로 열리지 않습니다. 액션 클릭이나 팝업 버튼에 chrome.sidePanel.open()과 같은 트리거를 추가하거나, openPanelOnActionClick 설정을 해야 합니다.
확장 프로그램의 상태가 왜 사라지나요?
서비스 워커는 일시적인 존재로 약 30초간 활동이 없으면 종료되므로 변수에 저장된 상태도 함께 사라집니다. 이를 해결하려면 chrome.storage에 데이터를 저장하고 모든 이벤트에서 chrome.alarms를 사용하여 해당 데이터를 읽어야 하며, setTimeout/setInterval 대신 이 방식을 사용해야 합니다.
확장 프로그램의 CSP 제한 때문에 동적 코드를 어떻게 실행하나요?
확장 프로그램의 CSP는 eval, new Function, 인라인 스크립트를 차단하므로, manifest 샌드박스와 postMessage 기능을 활용한 샌드박스화된 iframe 내에서나, 별도의 오리진을 가지는 Blob URL 또는 srcdoc을 통해 코드를 실행해야 합니다.
Prompt API도 다루나요?
네. LanguageModel API는 추가적인 권한 없이도 서비스 워커, 팝업, 사이드 패널에서 작동하며, 웹 환경에서는 사용할 수 없는 LanguageModel.params() 기능도 확장 프로그램에서 사용할 수 있습니다.
