크롬 확장 프로그램의 핵심, manifest.json 가이드

 

크롬 확장 프로그램을 개발해 본 경험이 있는 분이라면 manifest.json 파일의 중요성을 잘 알고 계실 거예요. 이 파일은 확장 프로그램의 설정, 권한, 기능을 정의하는 핵심 구성 요소로, 크롬이 확장 프로그램을 인식하고 실행하는 데 필수적인 역할을 합니다. 이번 글에서는 manifest.json의 구조, 필드별 의미, 실제 예시를 통해 초보자도 쉽게 이해할 수 있도록 설명해 드리겠습니다.

---

1. manifest.json이란?

manifest.json은 JSON 형식으로 작성된 파일로, 크롬 확장 프로그램의 메타데이터와 동작 방식을 정의합니다. 이 파일이 없으면 크롬은 확장 프로그램을 인식할 수 없으며, 파일 내 필드 하나만 잘못 설정해도 확장 기능이 제대로 동작하지 않을 수 있습니다.

예를 들어, 확장 프로그램의 이름, 버전, 아이콘, 필요한 권한, 백그라운드 스크립트, 팝업 페이지 등을 모두 이 파일에 명시해야 합니다. 따라서 개발 초기 단계에서 manifest.json을 정확히 구성하는 것이 중요합니다.

---

2. manifest.json의 기본 구조

manifest.json은 크게 3가지 섹션으로 구성됩니다. 각 섹션의 역할을 자세히 알아보겠습니다.

2-1. 기본 정보 (Metadata)

확장 프로그램의 기본적인 정보를 정의합니다. 사용자가 크롬 웹 스토어에서 확장 프로그램을 설치할 때 보여지는 내용도 여기에 포함됩니다.

• manifest_version:
  크롬 확장 프로그램의 manifest 버전을 지정합니다. 현재는 3를 사용해야 합니다.
• "manifest_version": 3
• name:
  확장 프로그램의 이름입니다.
• "name": "내 첫 번째 크롬 확장"
• version:
  버전 관리를 위해 사용됩니다. 크롬은 이 값을 통해 업데이트를 확인합니다.
• "version": "1.0.0"
• description:
  확장 프로그램의 간단한 설명을 작성합니다.
• "description": "현재 페이지의 URL을 복사하는 간단한 확장 프로그램"
• icons:
  확장 프로그램의 아이콘을 등록합니다. 크롬은 다양한 크기의 아이콘을 요구하며, 일반적으로 16x16, 48x48, 128x128 픽셀을 권장합니다.
• "icons": { "16": "icons/icon16.png", "48": "icons/icon48.png", "128": "icons/icon128.png" }

---

2-2. 권한 설정 (Permissions)

확장 프로그램이 사용할 수 있는 권한을 정의합니다. 보안상의 이유로 필요한 최소한의 권한만 요청해야 합니다.

• permissions:
  확장 프로그램이 사용할 일반 권한을 배열로 나열합니다.
  • activeTab: 현재 활성화된 탭에 대한 임시 접근 권한을 부여합니다.
  • tabs: 모든 탭의 정보(예: URL)에 접근할 수 있습니다.
  • storage: 크롬의 로컬 저장소를 사용할 수 있습니다.
  • scripting: 동적으로 스크립트를 실행할 수 있습니다.

    "permissions": ["activeTab", "tabs", "storage", "scripting"]

• host_permissions:
  특정 웹 사이트의 콘텐츠에 접근할 수 있는 권한을 설정합니다.
  • <all_urls>: 모든 URL에 접근 가능 (주의 필요).
  • https://*.example.com/*: example.com 도메인만 접근 가능.

    "host_permissions": ["https://*.example.com/*"]

---

2-3. 기능 정의 (Functionalities)

확장 프로그램의 실제 동작을 제어하는 필드입니다. 백그라운드 스크립트, 팝업 페이지, 콘텐츠 스크립트 등을 설정합니다.

• action:
  툴바에 표시되는 아이콘과 클릭 시 나타날 팝업 페이지를 정의합니다.
• "action": { "default_icon": "icons/icon16.png", "default_popup": "popup.html", "default_title": "확장 프로그램 클릭!" }
• background:
  백그라운드에서 지속적으로 실행될 스크립트를 등록합니다.
• "background": { "service_worker": "background.js" }
• content_scripts:
  특정 웹 페이지에 자동으로 주입될 스크립트를 설정합니다.
• "content_scripts": [ { "matches": ["https://*.example.com/*"], "js": ["content.js"], "css": ["styles.css"] } ]

---

3. 실전 예시: URL 복사 확장 프로그램

실제 manifest.json 파일을 작성해 보겠습니다. 활성화된 탭의 URL을 복사하는 간단한 확장 프로그램을 만들어 볼게요.

{
  "manifest_version": 3,
  "name": "URL 복사 도우미",
  "version": "1.0.0",
  "description": "현재 페이지의 URL을 클립보드에 복사합니다.",
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "permissions": ["activeTab", "scripting"],
  "action": {
    "default_icon": "icons/icon16.png",
    "default_popup": "popup.html",
    "default_title": "URL 복사"
  },
  "background": {
    "service_worker": "background.js"
  }
}

• permissions: activeTab 권한으로 현재 탭에 접근하고, scripting으로 스크립트를 실행합니다.
• action: 팝업 페이지(popup.html)에서 복사 버튼을 클릭하면 백그라운드 스크립트(background.js)가 URL을 가져옵니다.

---

4. 주의 사항 & 팁

manifest.json을 작성할 때 반드시 확인해야 할 사항들을 정리했습니다.

4-1. 버전 관리

• version 필드는 세미버전(semver) 형식(예: 1.0.0)을 따라야 합니다.
• 크롬은 버전이 증가할 때마다 업데이트를 체크하므로, 개발 중에도 버전을 꼭 관리하세요.

4-2. 권한 최소화

• 불필요한 권한을 추가하면 보안 리스크가 커집니다.
• 예를 들어, host_permissions에 <all_urls>를 사용하면 모든 사이트에 접근할 수 있으니 주의하세요.

4-3. CSP(Content Security Policy)

• 외부 스크립트나 인라인 코드(예: onclick="...") 사용이 제한될 수 있습니다.
• CSP를 변경하려면 content_security_policy 필드를 추가해야 합니다.

  "content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'self'"
  }

---

5. 마치며

manifest.json은 크롬 확장 프로그램의 블루프린트와 같습니다. 이 파일을 정확히 작성하지 않으면 확장 프로그램은 제대로 동작하지 않습니다. 하지만 필드별 의미를 이해하고 체계적으로 구성하면 복잡해 보이는 작업도 쉽게 해결할 수 있습니다.

이번 글에서 설명한 내용을 바탕으로 직접 manifest.json을 작성해 보세요. 간단한 확장 프로그램부터 시작해 점차 복잡한 기능을 추가해 나가다 보면, 어느새 크롬 확장 개발의 달인이 되어 있을 거예요! 🚀

TIP: 크롬 공식 문서(Chrome Extensions Docs)에서 최신 manifest 사양을 확인하세요!