ChromeExtension


## Intro

최근 3일 정도를 chrome extension version 2에서 version3로 migration하면서 보낸 거 같습니다. ㅠㅠ

현재 side project로 진행하고 있는 내용을 chrome extension store에 배포할려고 하는 순간에 경고창이 뜨며, 이제부터는 version 3만 업로드를 지원한다는 경고를 받았습니다.ㅠㅠㅠㅠㅠ

그래서 이전 셋업을 완전히 뜯어고쳐야 된다는 결론에 도달했고, 이전에 열심히 투닥투닥 만들었던 결과물을 다시 뜯어고쳐야했습니다.

이 내용은 제가 진행하면서 바꾼 내용을 정리한 내용입니다. 저와 같이 version migration을 진행하시는 분들에게 도움이 되었으면 좋겠습니다.

## 1. manifest에서 바뀌어야 하는 부분

위에가 기존 version 2라면 아래가 version 3로 바뀌었을 때의 내용입니다. 일단 용어적인 부분에서 엄청 변경된 것은 없습니다. (하지만, API call이라든지 기타 여러 부분에 관해서는 정책이 매우 강력해진 편입니다. 이는 바로 다음에 살펴봅니다.)

```json
// manifest.json
{
  "manifest_version": 2,
  "name": "chrome-ext-boiler-plate",
  "version": "0.0.1",
  "description": "This project is chrome extension boiler plate",
  "icons": {
    "16": "icon/16.png",
    "32": "icon/32.png",
    "48": "icon/48.png",
    "128": "icon/128.png"
  },
  "background": { "scripts": ["background.js"] },
  "content_scripts": [{ "matches": ["<all_urls>"], "js": ["content.js"] }],
  "options_page": "option.html",
  "browser_action": { "default_popup": "popup.html" },
  "permissions": ["storage", "tabs"],
  "content_security_policy": " script-src 'self' 'unsafe-eval'; object-src 'self'"
}
```

```json
// manifest.json
{
  "manifest_version": 3,
  "name": "chrome-ext-boiler-plate",
  "version": "0.0.1",
  "description": "This project is chrome extension boiler plate",
  "icons": {
    "16": "icon/16.png",
    "32": "icon/32.png",
    "48": "icon/48.png",
    "128": "icon/128.png"
  },
  "background": { "service_worker": "background.js" },
  "content_scripts": [{ "matches": ["<all_urls>"], "js": ["content.js"] }],
  "options_page": "option.html",
  "permissions": ["storage", "tabs"],
  "action": { "default_popup": "popup.html" }
}
```

> **요약**

- manifest\_version : 2 => 3
- background.scripts => background.service\_worker  
  배열에서 하나의 단일 service\_worker로 변경되었습니다. 기존에 permanent관련 설정을 하신 분들은 이를 사용할 수 없습니다.
- browser_action => action  
  기존에 있던 다른 action과 통합되어 하나의 action이라는 이름으로 명칭이 변경되었습니다. 사실 여기까지는 화가나지 않습니다.

## 2. 보안 설정

version 3로 올라오면서 보안정책이 정말 강화가 되었습니다.

특히 CORS 부분에서 1차 멘붕을 겪을 수 있습니다.

만약, server에서 기존의 CORS accept를 단순히 "\*"로 설정하였다면, 저처럼 개고생을 할 수 있습니다. 일단, popup에서 요청을 보내는 경우에 저는 "chrome-extension://\*" 로 설정을 직접적으로 해주어야 제대로 통신을 하는 것을 확인할 수 있었습니다. 이거 진짜 너무 힘들게 찾았습니다. ㅠㅠ (서버 단에서 라이브러리 문제인지 아니면, 다른 설정 문제인지는 체크는 안했습니다. ㅎ 여러분도 조심하시기 바랍니다.)

또한, websocket 설정도 굉장히 빡세졌습니다. 기존에는 wss 요청을 보낼 때, INVALID CERTIFICATE를 확인하지 않았기 때문에 인증서 대충 설정하고 진행했었는데, 이제는 background에서 connection 생성 시에 이를 반드시 확인합니다. 따라서, https 생성 하실 때 서명 확실하게 하시고, 설정하시는게 좋을 겁니다. (저는 traefik을 이용하는데 알아서 인증서 발급 해주는 게 너무 편리합니다.)

![chrome-ext-mig-01](/images/chrome-ext-mig-01.png)

## 3. Webpack 설정

요즘 같은 시대에 생 javascript, jQuery로 front를 개발하지 않기 때문에, webpack을 통해서 vue나 react를 사용하실 가능성이 높으실 겁니다. 놀라운 사실은 우리의 webpack이 아무 설정을 해주지 않으면 development mode에서는 build file로 eval이 잔뜩 덕칠되어 있는 코드를 return 합니다.

![chrome-ext-mig-02](/images/chrome-ext-mig-02.png)

그런데, 이번 v3에서는 eval을 사용하는 것을 보안상의 위협으로 체크하고, 개발상황에서도 허용하지 않습니다. (물론 sandbox로 설정해서 할 수 있지만, 이렇게 되면 manifest.json file을 development, production 구분해야하고, 일단 이에 대한 예제를 제가 찾지 못했기 때문에 이를 통한 설정은 저는 포기했습니다. ㅠ) 기존에는  manifest에서 content\_security\_policy에서 eval을 허용해주면 끝이였는데, version 3로 바뀌면서 sandbox라는 기능이 추가되면서, 저희를 곤혹스럽게 합니다. 일단 찾기 쉬운 예제로 sandbox에 적용하니 chrome API가 막히거나, http API call이 막히는 등 저를 너무나 힘들게 했습니다. 따라서, 저는 webpack 설정을 만져서 다시 고쳐쓰자는 결론을 내렸고, 검색과 검색과 더 검색을 거친 결과로 webpack.config.js에서 eval을 사용하지 않는 mode를 찾아냈습니다. 그래서 적용한 결과 진짜로 eval이 사라졌고, build 속도도 굉장히 빨랐기에 아주 기분 좋게 설정을 마쳤습니다. 껄껄..

아래는 devtools를 cheap-module-source-map으로 설정했을 때 나오는 결과물입니다. 정말 다행히도 eval이 없습니다.

![chrome-ext-mig-03](/images/chrome-ext-mig-03.png)

마무리하면서, 다 나쁜점만 있었던 것은 아니라는 점을 짚어보고 넘어갑니다. 기존에는 webpack plugin인 webpack-chrome-extension-reloader 를 이용해서 hot reloading을 구현했었는데, version3로 넘어가면서 code가 바뀌면 자동으로 해준다는 것을 확인했습니다. 따라서, webpack --watch 만 설정해줘도 쉽게 reloading이 됩니다. 아마 chrome에서 파일 변환이 생기면 자동으로 reloading 하는 거 같습니다. 따라서 해당 설정은 지워주었습니다.

이렇게 해서 거의 한 3일 정도 골머리를 앓으면서 migration한 내용을 정리해보았습니다. 다른 분들에게도 도움이 되었으면 좋겠네요.

마지막으로 github link입니다. 이거 보고 참고 하시는게 가장 빠를 거 같습니다.

[🔗 GitHub](https://github.com/euidong/chrome-extension-boilerplate)


Chrome Extension Migrantion V2에서 V3


## Intro

해당 글은 manifest version 3을 기반으로 작성된 글입니다. 혹여 version 2를 이용하셨다면, version 2에서 version 3로 migration 하면서 제가 적어놓은 글이 있으니 그것을 참고 하시기 바랍니다.

[Chrome Extension version migration from V2 to V3](/posts/chrome-extension-migration-v2-to-v3)

## 1. chrome 확장 앱의 구성

chrome extension에서 manifest version이 3이 되어 이를 한 번 정리할 겸,  
chrome 확장앱을 구성하는 component는 크게 5가지로 나눌 수 있습니다.

1. Background scripts => 대게 event를 등록하는데 사용합니다. (bookmark 등록, message 등과 같은 기능)
2. Content scripts => 현재 열려 있는 페이지를 기준으로 이들을 바꿀 수 있습니다.
3. an options page => options page에 의해 제공되는 세부 동작을 usesr가 사용할 수 있도록 합니다.
4. UI elements => 브라우저 우상단에 존재하는 아이콘 or 클릭 시 열리는 popup, 검색창, contextmenu 등과 관련된 요소를 관리합니다.
5. various logic files => 추가적으로 사용할 logic 등을 포함하는 것이 가능합니다.

기본적으로 모든 요소는 HTML, CSS, Javascript를 이용해서 구성됩니다. 모든 확장 component가 필요로 되는 것은 아닙니다.

## 2. Manifest 만들기

모든 extension은 반드시 하나의 manifest 파일을 포함합니다. 이는 JSON 형식으로 되어있고, manifest.json이라는 이름으로 저장됩니다.  
기본 형태는 다음 제시한 내용처럼 구성됩니다. required 부분에는 반드시 들어가야 하는 내용을 포함합니다.  
또한, app을 구성함에 있어 거의 필수적으로 들어가야 하는 action과 icon과 같은 내용과 설명 등이 포함됩니다.

```json
{
  // required
  "manifest_version": 3,
  "name": "app test",
  "version": "0.0.1",

  // recommended
  "action": {},
  "default_locale": "ko",
  "description": "chrome extension test",
  "icons": {}
}
```

자세한 사항은 하단 링크를 참고해주세요.

[Chrome extension Manifest](https://developer.chrome.com/docs/extensions/mv3/manifest/)

## 3. Background script 구성하기

확장앱은 event에 기반을 둔 크롬 브라우저 환경을 향상 또는 변경 시키기 위한 프로그램이다. event(새로운 page로의 이동, 북마크 삭제, 탭 닫기, 등)는 browser에 의해서 등록되어집니다. 확장앱은 background (service worker) scripts를 이용하여 이러한 event를 모니터링하며, 특정 지시사항을 명시합니다.  
background service worker는 필요에 의해 언제든지 load되고, 사용되지 않으면 unload됩니다.

- 확장앱이 최초로 설치되거나 업데이트 되었을 경우
- background page가 전송된 event를 들었을 경우
- 다른 script 또는 extension에서 message를 전송했을 경우
- 확장앱의 다른 view에서 runtime.getBackgroundPage를 호출한 경우

한번 load되면, service worker는 이것이 action을 수행하는 동안은 종료되지 않습니다. 따라서, service worker는 모든 view 그리고 message port가 닫힐 때까지 unload되지 않습니다.

`view를 여는 것은 service worker를 불러오지는 않지만, 종료되는 것을 막을 수는 있습니다.`

효율적인 background scripts는 event가 발동되기 까지는 정지상태로 존재하고, 이에 응한뒤에 종료된다.

### 등록

service worker를 등록하기 위해서는 manifest에 이를 명시해주어야 합니다.  
아래 예제에서는 명시된 background.js 파일이 service_worker들의 main이 됩니다.

```json
{
    "manifest_version": 3,
    ...,
    "background": {
          "service_worker": "background.js"
    }
}
```

### 구성하기

runtime.onInstalled event를 listen한다면, 확장앱 설치 시에 초기화가 가능합니다. 초기 상태를 정의할 때 이를 사용합니다.  
아래 예시에서는 event를 등록하는 과정입니다. 여기서 유의해야 할 것은 event의 등록은 page의 시작 시에 동기적으로 모두 설치해주어야 한다는 것입니다. 만약, event가 발생했을 때, event를 등록하는 것과 같은 동작을 하기 위해서는 다른 방식을 이용해야 합니다.

```javascript
chrome.runtime.onInstalled.addListener(function() {
  chrome.contextMenus.create({
    "id": "sampleContextMenu",
    "title": "Sample Context Menu",
    "contexts": ["selection"]
  });
});

// This will run when a bookmark is created.
chrome.bookmarks.onCreated.addListener(function() {
  // do something
});
```

추가적으로 요청을 filtering 하거나, trigger를 재등록하는 과정과 같은 내용은 하단 링크를 추가로 참고하기 바랍니다.

[Background pages](https://developer.chrome.com/docs/extensions/mv3/background_pages/)

## 4. Content scripts 만들기

contents scripts는 web page에서 동작할 내용에 대한 내용을 담습니다. DOM을 사용하여, scripts는 현재 웹 페이지의 세부사항을 조회, 변경 또는 정보를 전달하는 것이 가능합니다.  
contens scripts는 확장앱의 message 교환을 통해서 부모 확장앱에 의해 사용되는 chrome API에 접근하는 것이 가능합니다. 또한, URL을 통해서 확장앱의 파일에 접근하여, 이를 사용하는 것이 가능합니다. 기본적으로 i18n, storage, runtime(connect, getURL, id, onMessage, sendMessage, etc...) 과 같은 API에 바로 접근해서 사용하는 것이 가능합니다.

```javascript
// Code for displaying <extensionDir>/images/myimage.png:
var imgURL = chrome.runtime.getURL("images/myimage.png");
document.getElementById("someImage").src = imgURL;
```

### 고립

다른 확장앱, 또는 page와 충돌을 막기 위해서 기본적으로 content script는 고립됩니다. (browser의 tab간에 서로 독립적인 것처럼)  
예를 들어, 다음과 같은 코드가 있다고 가정합니다.

```html
<html>
  <button id="mybutton">click me</button>
  <script>
    var greeting = "hello, ";
    var button = document.getElementById("mybutton");
    button.person_name = "Bob";
    button.addEventListener("click", () =>
      alert(greeting + button.person_name + ".")
    , false);
  </script>
</html>
```

여기에 content scripts를 이용해서 아래 코드를 inject한다면,

```javascript
var greeting = "hola, ";
var button = document.getElementById("mybutton");
button.person_name = "Roberto";
button.addEventListener("click", () =>
  alert(greeting + button.person_name + ".")
, false);
```

button을 클릭했을 때, 두 개의 alert 창을 만날 수 있습니다.

### Inject scripts

content scripts는 3가지의 방법으로 삽입되어질 수 있습니다.

> **1. statically**

manifest.json 파일에 정적으로 선언하면, 자동적으로 page가 setting될 때 실행됩니다. 이는 "content\_scripts"라는 부분에 정의됩니다. 여기에는 javascript, css 등을 포함할 수 있습니다.

```json
{
"manifest_version": 3,
...
"content_scripts": [
  {
    "matches": ["http://*.nytimes.com/*"], // 해당 injection을 수행할 URL을 명시합니다. 필수입력입니다.
    "css": ["myStyles.css"], // 추가할 css파일 입니다.
    "js": ["contentScript.js"] // 추가할 js파일 입니다.
  }
]
}
```

> **2. dynamically**

2021.04.01 시점에서는 아직 완전 제공하지는 않는 기능입니다.  
host를 알지 못하거나 아는 host로 부터 script가 추가 또는 삭제될 필요가 있는 경우에 사용합니다.

`chrome.scripting.registerContentScript(optionsObject, callback);`

or

`chrome.scripting.unregisterContentScript(idArray, callback);`

> **3. programmatically**

구체적인 상황 또는 event에 대한 반응으로 실행하기 원할 때 사용합니다.  
이를 수행하기 위해서는, 해당 페이지에 대한 host의 permission이 필요합니다. 이는 확장앱의 host\_permissions 부분 or 일시적으로 activeTab을 이용해서 승인을 받을 수 있습니다.

```json
{
  "manifest_version": 3,
  ...
  "permissions": [
    "activeTab"
  ]
}
```

```javascript
// 1. 파일 전체를 실행 주입 시키는 방법
chrome.runtime.onMessage.addListener((message, callback) => {
  if (message == "runContentScript"){
    chrome.scripting.executeScript({
      file: 'contentScript.js'
    });
  }
});

// 2. 특정 함수를 주입하는 방법
function injectedFunction(color) {
  document.body.style.backgroundColor = color;
}

chrome.runtime.onMessage.addListener((message, callback) => {
  if (message == "changeColor"){
    chrome.scripting.executeScript({
      function: injectedFunction,
      arguments: ['orange']
    });
  }
});
```

추가적으로 matck 범위를 세부 정의하는 부분과 frame 및 rum time 시점 관련 사항은 아래 링크를 참조해주세요.

[Content scripts](https://developer.chrome.com/docs/extensions/mv3/content_scripts/)

## 5. option Page 만들기

사용자에게 option을 선택할 수 있는 page를 customise하여 제공할 수 있습니다. 이는 chrome 확장앱을 관리할 수 있는 chrome://extensions에서 Detail을 눌렀을 때 보이는 option과 관련된 page입니다.  
이는 필요에 따라 구현하는 것이 알맞기 때문에 링크만 달아두겠습니다.

[Options](https://developer.chrome.com/docs/extensions/mv3/options/)

## 6. UI elements 만들기

확장앱은 UI 요소를 몇 가지 제공하는 것이 가능합니다. 여기서는 일부만 소개합니다.

### 1. Badge

확장앱의 icon을 결정하거나, 활성화 / 비활성화 등을 구분할 때 사용됩니다. => 상세 내용은 하단 링크 참고  
여기서는 icon을 설정하는 방법만 적습니다.

```json
{
  "manifest_version": 3,
  ...
  "icons": {
    "16": "extension_icon16.png", // favicon
    "32": "extension_icon32.png", // 관리창 Icon(window에서 가끔 요구함)
    "48": "extension_icon48.png", // 관리창 Icon
    "128": "extension_icon128.png" // chrome webstore Icon
  }
}
```

### 2. Popup

browser 창의 tooltip을 클릭 시에 보여주고 싶은 내용을 명시하는 것이 가능합니다.

```json
{
  "manifest_version": 3,
  ...
  "browser_action": {
    "default_popup": "popup.html"
  }
  ...
}
```

popup.html

```html
<html>
  <head>
    <title>Water Popup</title>
  </head>
  <body>
      <img src='./stay_hydrated.png' id='hydrateImage'>
      <button id='sampleSecond' value='0.1'>Sample Second</button>
      <button id='15min' value='15'>15 Minutes</button>
      <button id='30min' value='30'>30 Minutes</button>
      <button id='cancelAlarm'>Cancel Alarm</button>
    <script src="popup.js"></script>
  </body>
</html>
```

### 3. Contextmenu

우클릭 시에 나오는 상자에 추가 내용을 추가하는 것이 가능합니다.

```json
{
  "manifest_version": 3,
  ...
  "permissions": [
    "contextMenus"
  ],
  "background": {
    "service_worker": "background.js"
  }
}
```

`background.js`

```javascript
const kLocales = {
  'com.au': 'Australia',
  'com.br': 'Brazil',
  'ca': 'Canada',
  'cn': 'China',
  'fr': 'France',
  'it': 'Italy',
  'co.in': 'India',
  'co.jp': 'Japan',
  'com.ms': 'Mexico',
  'ru': 'Russia',
  'co.za': 'South Africa',
  'co.uk': 'United Kingdom'
};

chrome.runtime.onInstalled.addListener(function() {
  for (let key of Object.keys(kLocales)) {
    chrome.contextMenus.create({
      id: key,
      title: kLocales[key],
      type: 'normal',
      contexts: ['selection'],
    });
  }
});
```

추가적으로, override page, command, 검색창 디자인 등 추가적인 요소를 보려면 아래 링크를 참조해주세요.

[Design the user interface](https://developer.chrome.com/docs/extensions/mv3/user_interface/)

## 7. Boilerplate

만약, react, typescript에 익숙하다면, 필자가 만들어놓은 boilerplate를 추천합니다.

[euidong/chrome-extension-boilerplate](https://github.com/euidong/chrome-extension-boilerplate)
