Chrome拡張機能 manifest.json Ver.3の書き方

はじめに

現在のChrome拡張機能のマニフェストのバージョンはV2とV3がありますが、こちら によると、
- 2022/1/17 でmanifest v2で新規公開はできなくなる
- 2022/6でmanifest v2で非公開でも新規登録はできなくなる
- 2023/1で例外を除き,既存のmanifestV2の機能は動かなくなる
- 2023/6でmanifestV2は例外なく動かなくなる
とのことなのでよっぽどの理由がない限りV3を今後は使うことになります。

V2で書かれた情報の記事はいっぱいあったのですが, V3の記事はあまりなかったので自分用メモも兼ねて整理しようと思います。

manifest.jsonの基本設定

manifest_version

拡張機能自体のバージョンではなく、マニフェストのバージョンです。
ここはとにかく 2 ではなく 3 にしておきましょう！

manifest.json

"manifest_version": 3 

name

拡張機能の名称です。45 文字まで設定が可能です。

manifest.json

"name": "your-extension-name"

version

拡張機能自体のバージョンです。
拡張機能の自動更新機能でバージョンが差がチェックされるので、更新の際には既存のバージョンより大きい値にする必要があります。

manifest.json

"version": "1.0.0"

description

拡張機能の説明文です。132 文字まで設定可能です。
こちらなくても動きますが審査に出すときは必要なので、なるべく設定しておきましょう。

"description": "拡張機能の説明文",

icons

拡張機能のアイコンです。16x16 , 48x48,128x128 のサイズの.png画像の設定推奨されています。
ウェブストアやfaviconなどに使われます。

manifest.json

"icons": {
    "16": "icon16.png",
    "48": "icon48.png",
    "128": "icon128.png"
},

manifest.jsonのオプション

action

拡張機能のアイコンをクリックしたときに動作するものを設定するときに記載します。
default_popup にhtmlファイルを設定することで、拡張機能のアイコンをクリック時にそのhtmlのポップアップを設定することができます。default_iconにはブラウザの右上に出すアイコンを設定します。

manifest.json

"action": {
     "default_icon": "popup16.png",
     "default_popup": "popup.html"
 },

V2までは、全てのページに対してアクションを起こす browser_actionと特定のページに対してアクションを起こすpage_action と分かれていましたが、V3から action に統合されました。それに伴い、chrome.browserActionとchrome.pageAction も chrome.action APIに統合されています。

content_script

表示しているWebページの詳細を読み取ったり、DOM操作したり、親の拡張機能に情報を渡したりする目的がある場合設定します。使用できるAPIが限られているため、あまり複雑な操作には向いていません。
matches にはコンテンツスクリプトが挿入されるページを指定します。
css・jsには一致するページに挿入されるCSS・JavaScriptファイル群を設定します。

manifest.json

 "content_scripts": [
   {
     "matches": ["https://xxxxxxx.com/*"],
     "css": ["style.css"],
     "js": ["content-script.js"]
   }
 ],

background

バックグラウンドでJSを動かす場合に設定します
V3からバックグラウンドページから service_worker に置き換えられました。
service_workerに設定するファイルは manifest.json と同じファイルに設定する必要があります。

"type:"module"とすることで、ServiceWorkerをESモジュールとして含めることができ、importを使った実装をなど行うことができます。

manifest.json

"background": {
    "service_worker": "background.js",
    //　オプション
    "type": "module"
},

使用できるAPIがcontent_scriptでは制限されているに対し、backgroundではほぼ全て使用することができますが、DOM操作などは行うことはできません。そのため、backgroundを通じてスクリプトを送り込み、DOM操作などのイベントを実行させる工夫なども場合によっては必要となります。

特定のURLサイトへのアクセス時に main.js を動かす、backgroud.js の例

backgroud.js

chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
    if (tab.url.indexOf('https://xxxxxxxxxxxxxxx') > -1) {
        chrome.scripting.executeScript({
            target: { tabId: tab.id },
            files: ['main.js'],
        });
    }
});

※V3からchrome.tabs.executeScript() はscripting.executeScript()へ置き換えられています

permission

permissionはchrome.scripting.executeScript... のなどのようなChromeAPIを使う時に設定する必要があります。
設定可能なパーミッション一覧: https://developer.chrome.com/extensions/declare_permissions

host_permissionには拡張機能がアクセスするサイトのURLを設定する必要があります。
全てのサイトで動かす場合は <all_urls>を設定します。

manifest.json

"permissions": ["tabs", "scripting"],
"host_permissions": [
  "https://xxxxxxxxxxxx",
　"<all_urls>"
]

content_security_policy

外部との接続を許可したりする場合に設定を変更する項目です。下記の設定がデフォルトの設定となります。

manifest.json

"content_security_policy": "script-src 'self'; object-src 'self'",

外部との接続を許可したりする項目であるため注意が必要です。eval 関数やインラインスクリプトを使わない拡張機能を作る分にはそもそも設定する必要はないため、むやみに設定を変更しないようにしましょう。

安全にevalを使用したい場合は sandbox を作成することによって、安全にしようすることができるらしいです。
https://developer.chrome.com/docs/extensions/mv3/sandboxingEval/

web Access Resources

Webから拡張機能の画像などのリソースにアクセスしたい場合に設定します。
デフォルトでは、Webにアクセスできる拡張機能のリソースはありません。

manifest.json

"web_accessible_resources": [{
  "resources": [公開されるリソース],
  "matches": [リソースにアクセスできるページを指定するURL一致パターン],
  "extension_ids": [リソースにアクセスできる拡張機能を指定する拡張機能ID]
}]

参考資料

・https://developer.chrome.com/docs/extensions/mv3/
・https://qiita.com/mdstoy/items/9866544e37987337dc79
・https://blog.pokutuna.com/entry/chrome-manifest-v3

最後に

これからも拡張機能を作る機会があると思うので、この機に整理できてよかったです。
他にもたくさんの設定項目などもあるので、実際の開発の際にはドキュメントを読み込む必要がありそうです。

この記事が誰かのお役に足れば幸いです。ありがとうございました。