コンテンツスクリプト

コンテンツスクリプトは、ウェブページのコンテキストで実行される拡張機能の一部です（拡張機能の一部であるバックグラウンドスクリプトや、ウェブサイト自体の一部であるスクリプト、例えば <script> 要素みたいなものと対照的なものです）。

バックグラウンドスクリプトはすべての WebExtension JavaScript API にアクセスできますが、ウェブページのコンテンツに直接アクセスすることはできません。だからあなたの拡張機能がそれを行う必要がある場合は、コンテンツスクリプトが必要です。

通常のウェブページで読み込まれたスクリプトと同様に、コンテンツスクリプトは、標準の Web API を使用してページのコンテンツを読み取り、変更することができます。しかし、このようなことができるのは、ウェブページのオリジンに対するホスト権限が与えられている場合だけです。

メモ:一部の Web API は安全なコンテキストに制限されており、これらのコンテキストで実行するコンテンツスクリプトにも適用されます。ただし、PointerEvent.getCoalescedEvents() は、 Firefox の安全でないコンテキストでコンテンツスクリプトから呼び出すことができます。

コンテンツスクリプトは、WebExtension API の小さなサブセットにしかアクセスできませんが、メッセージングシステムを使用してバックグラウンドスクリプトと通信し、WebExtension API に間接的にアクセスすることができます。

コンテンツスクリプトの読み込み

次の 3 つの方法のいずれかを使用して、ウェブページにコンテンツスクリプトを読み込むことができます。

インストール時に、URL パターンに一致するページ内へ。: manifest.json の content_scripts キーを使用して、URL が指定されたパターンに一致するページをロードするたびにコンテンツスクリプトを読み込むようブラウザーに依頼できます。
実行時に、URL パターンに一致するページ内へ。: scripting.registerContentScripts() または（Firefox であればマニフェスト V2 の） contentScripts を使って、URL が指定されたパターンに一致するページを読み込むたびにコンテンツスクリプトを読み込むようブラウザーに依頼できます。これは方法 1 と似ていますが、実行時にコンテンツスクリプトを追加/削除できる点が異なります。）
実行時に、特定のタブへ。: scripting.executeScript() または（マニフェスト V2 のみ） tabs.executeScript() を使用すると、必要なときにコンテンツスクリプトを特定のタブに読み込むことができます。（ユーザーがブラウザーアクションをクリックした場合など。）

フレームごと、拡張機能ごとのグローバルスコープしかありません。これは 1 つのコンテンツスクリプトの変数は、読み込み方にかかわらず、他のコンテンツスクリプトからアクセスできることになります。

方法 (1) と (2) では一致パターンを使って表現された URL のスクリプトだけを読み込みできます。

方法 (3) では、拡張機能と一緒にパッケージされたページのスクリプトも読み込みできますが、"about:debugging" や "about:addons"のような権限つきページにはスクリプトを読み込めません。

メモ: ダイナミック JS モジュールインポートがコンテンツスクリプトで動作するようになりました。詳しくはFirefox バグ 1536094を参照してください。 moz-extension スキームを持つ URL のみが許可され、データ URL は除外されます (Firefox バグ 1587336)。

権限、制約、制限

権限

登録されたコンテンツスクリプトは、その拡張機能にドメインのホスト権限が付与されている場合にのみ実行されます。

プログラムでスクリプトを挿入するには、拡張機能には activeTab 権限またはホスト権限のどちらかが必要です。 scripting 権限は scripting API のメソッドを使用するために必要となります。

マニフェスト V3 以降、ホスト権限はインストール時点では自動的に付与されません。ユーザーは、拡張機能をインストールした後、ホスト権限のオプトインまたはオプトアウトを行うことができます。

ドメインの制限

ホスト権限と activeTab 権限はどちらも、いくつかのドメインが例外になっています。例えば、拡張機能が特別なページを通して権限をエスカレートさせることからユーザーを保護するために、コンテンツスクリプトはこの例ではドメイン上での実行がブロックされます。

Firefox では、これには次のドメインが含まれます。

accounts-static.cdn.mozilla.net
accounts.firefox.com
addons.cdn.mozilla.net
addons.mozilla.org
api.accounts.firefox.com
content.cdn.mozilla.net
discovery.addons.mozilla.org
install.mozilla.org
oauth.accounts.firefox.com
profile.accounts.firefox.com
support.mozilla.org
sync.services.mozilla.com

他のブラウザーでも、拡張機能をインストールできるウェブサイトには同様の制限があります。例えば、 Chrome では chrome.google.com へのアクセスが制限されています。

メモ: これらの制限は addons.mozilla.org を含んでいるので、ユーザーはインストール直後に拡張機能を使用しようとし、それが動作しないことに気付くかもしれません。適切な警告を追加したり、オンボーディングページを追加して、ユーザーを addons.mozilla.org から遠ざけたりするとよいでしょう。

一連のドメインは、エンタープライズポリシーでさらに制限することができます。 Firefox は ExtensionSettings in mozilla/policy-templates で文書化されている restricted_domains ポリシーを認識します。Chrome の runtime_blocked_hosts ポリシーは Configure ExtensionSettings policy で文書化されています。

制限

タブやフレーム全体を読み込むには、 data: URI や Blob オブジェクト、その他同様のテクニックを使用して、タブやフレーム全体を読み込むことができます。このような特殊文書へのコンテンツスクリプトの挿入に対応しているかどうかはブラウザーによって異なります。詳細は Firefox バグ #1411641 のコメント 41 を参照してください。

コンテンツスクリプト環境

DOM アクセス

コンテンツスクリプトは、普通のページスクリプトと同様に、ページの DOM にアクセスして修正できます。ページスクリプトにてなされた DOM の変更を見ることもできます。

しかし、コンテンツスクリプトは DOM の「きれいな」見た目を取得します。すなわち、

コンテンツスクリプトはページスクリプトにて定義された JavaScript 変数を見ることができない
ページスクリプトが組み込み DOM プロパティを再定義した場合、コンテンツスクリプトはそのプロパティの（再定義後でなく）オリジナル値を見ている

Chrome の非互換性における「コンテンツスクリプト環境」で触れている通り、動作はブラウザー間で異なります。

Firefox では、この挙動は Xray vision と呼ばれます。コンテンツスクリプトは、自分自身のグローバルスコープから、またはウェブページから Xray でラップされたバージョンの JavaScript オブジェクトに遭遇するかもしれません。
Chromeでは、この動作は隔離された世界 (isolated world) によって強制され、根本的に異なる手法を使用しています。

次のようなウェブページを考えてみてください。

html

<!doctype html>
<html lang="ja">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
  </head>

  <body>
    <script src="page-scripts/page-script.js"></script>
  </body>
</html>

page-script.js スクリプトは次を実行します。

// page-script.js

// add a new element to the DOM
let p = document.createElement("p");
p.textContent = "This paragraph was added by a page script.";
p.setAttribute("id", "page-script-para");
document.body.appendChild(p);

// define a new property on the window
window.foo = "This global variable was added by a page script";

// redefine the built-in window.confirm() function
window.confirm = () => {
  alert("The page script has also redefined 'confirm'");
};

今度は拡張機能がページにコンテンツスクリプトを挿入します。

// content-script.js

// can access and modify the DOM
let pageScriptPara = document.getElementById("page-script-para");
pageScriptPara.style.backgroundColor = "blue";

// can't see properties added by page-script.js
console.log(window.foo); // undefined

// sees the original form of redefined properties
window.confirm("Are you sure?"); // calls the original window.confirm()

逆も同様で、ページスクリプトはコンテンツスクリプトが追加した JavaScript のプロパティを見ることができません。

これは、コンテンツスクリプトが、ページスクリプトからの変数と衝突することを心配することなく、予測可能な動作をする DOM プロパティに頼っていることを意味しています。

この動作の実用的な結果の一つは、コンテンツスクリプトが、ページによって読み込まれたいかなる JavaScript ライブラリーにもアクセスできないことです。そのため、例えばページに jQuery が記載されていても、コンテンツスクリプトはそれを見ることができません。

コンテンツスクリプトが JavaScript ライブラリーを使用する必要がある場合、そのライブラリー自体は、それを使用したいコンテンツスクリプトと 並べて 挿入すべきです。

json

"content_scripts": [
  {
    "matches": ["*://*.mozilla.org/*"],
    "js": ["jquery.js", "content-script.js"]
  }
]

メモ: Firefox では cloneInto() および exportFunction() により、コンテンツスクリプトがページスクリプトによって作成された JavaScript オブジェクトにアクセスし、その JavaScript オブジェクトをページスクリプトに公開することができるようにしたりしています。

詳しくはページスクリプトとオブジェクトを共有するのページを見てください。

WebExtension API

標準 DOM API に加え、コンテンツスクリプトは次の WebExtension API を使用できます。

extension から:

runtime から:

i18n から:

menus から:

getTargetElement

すべてから:

storage

XHR と Fetch

コンテンツスクリプトは通常の window.XMLHttpRequest と window.fetch() API を使ってリクエストを作成できます。

メモ: Firefox では、コンテンツスクリプトの（例えば、fetch() を使った）リクエストは、拡張機能のコンテキストで起こるので、ページコンテンツを参照する URL を絶対 URL で提供せねばなりません。

Chrome では、リクエストはページのコンテキストで起こるので、相対 URL で行われます。例えば、/api は https://[現在のページの URL]/api に送られます。

コンテンツスクリプトは拡張機能の他の部分と同一のクロスドメイン権限を取得します。よって拡張機能が manifest.json の permissions キーを使ってあるドメインのクロスドメインアクセスを要求している場合、コンテンツスクリプトも同様にそのドメインのアクセスを取得します。

メモ: Manifest V3 を使用する場合、出力先サーバーが CORS を使用してオプトインするとき、コンテンツスクリプトはオリジン間リクエストを実行できます。ただし、コンテンツスクリプトではホスト権限は動作しませんが、通常の拡張ページではまだ動作しています。

これは、コンテンツスクリプトでより特権的な XHR とフェッチインスタンスを公開することによって達成されます。これは、ページ自身からのリクエストのように、Origin および Referer ヘッダーを設定しない副作用があります。これは、クロスオリジンの性質を明らかにしないリクエストを行うにはよく望ましいとされることです。

メモ: マニフェスト V2 の Firefox では、コンテンツ自身によって送信されたかのように振る舞うリクエストを実行する必要がある拡張機能は、代わりに content.XMLHttpRequest と content.fetch() を使用することができます。

クロスブラウザー拡張機能にとってこれらの存在は機能検出となります。

Manifest V3 では content.XMLHttpRequest と content.fetch() が利用できないため、このようなことは起こりえません。

メモ: Chrome ではバージョン 73 から、Firefox ではバージョン 101 からマニフェスト V3 を使用する場合、コンテンツスクリプトは、その中で実行されるページと同じ CORS ポリシーが適用されるようになりました。バックエンドスクリプトのみ、昇格したクロスドメイン特権があります。Chrome Extension コンテンツスクリプトにおける Cross-Origin Requests の変更点を参照してください。

バックグラウンドスクリプトとの通信

コンテンツスクリプトは WebExtension の API のほとんどを直接使用することはできませんが、メッセージング API を使用して拡張機能のバックグラウンドスクリプトと通信できるため、バックグラウンドスクリプトが使用できるのと同じ API にすべて間接的にアクセスすることができます。

バックグラウンドスクリプトとコンテンツスクリプトの間の通信には、基本的な 2 つのパターンがあります。

単発のメッセージ（オプションのレスポンス付き）を送信することができます。
両者の間に長寿命のコネクションを設定し、そのコネクションを使用してメッセージを交換することができます。

単発のメッセージ

レスポンスが必須でない単発のを送るには、次の API を使います。

	コンテンツスクリプト内	バックグラウンドスクリプト内
メッセージの送信	`browser.runtime.sendMessage()`	`browser.tabs.sendMessage()`
メッセージの受信	`browser.runtime.onMessage`	`browser.runtime.onMessage`

例えば、ウェブページでのクリックイベントを待ち受けするコンテンツスクリプトがここにあります。

クリックがリンク上である場合、ターゲット URL をバックグラウンドページにメッセージします。

// content-script.js

window.addEventListener("click", notifyExtension);

function notifyExtension(e) {
  if (e.target.tagName !== "A") {
    return;
  }
  browser.runtime.sendMessage({ url: e.target.href });
}

バックグラウンドスクリプトはこのメッセージを待ち受けして、notifications API を使って通知を表示します。

// background-script.js

browser.runtime.onMessage.addListener(notify);

function notify(message) {
  browser.notifications.create({
    type: "basic",
    iconUrl: browser.extension.getURL("link.png"),
    title: "You clicked a link!",
    message: message.url,
  });
}

この例のコードは GitHub の notify-link-clicks-i18n のサンプルから簡単に適用できます。

コネクションベースのメッセージ

バックグラウンドスクリプトとコンテンツスクリプトの間で多くのメッセージを交換する場合、単発のメッセージの送信は面倒になることがあります。そこで、 2 つのコンテキスト間でより詳しい接続を確立し、この接続を使用してメッセージを交換するという方法があります。

いずれの側にも runtime.Port オブジェクトがあり、メッセージ交換に使うことができます。

コネクションを作成するには次のようにします。

片方で runtime.onConnect にてコネクションを待ち受けする。
もう片方で次を呼び出す。
- tabs.connect() (コンテンツスクリプトに接続する場合)
- runtime.connect() (バックグラウンドスクリプトに接続する場合)

これは runtime.Port オブジェクトを返します。

runtime.onConnect リスナーには自身の runtime.Port オブジェクトが渡される。

それぞれがポートを持ったら、両方が、

runtime.Port.postMessage() でメッセージを送って
runtime.Port.onMessage でメッセージを受信できるようになる。

例えば、ロードしたらすぐに、このコンテンツスクリプトは、

バックグラウンドに接続し
myPort 変数に Port を格納する
myPort のメッセージを待ち受けする (ログに出す)
ユーザーがドキュメントをクリックしたとき、バックグラウンドスクリプトに myPort を使ってメッセージを送る

// content-script.js

let myPort = browser.runtime.connect({ name: "port-from-cs" });
myPort.postMessage({ greeting: "hello from content script" });

myPort.onMessage.addListener((m) => {
  console.log("In content script, received message from background script: ");
  console.log(m.greeting);
});

document.body.addEventListener("click", () => {
  myPort.postMessage({ greeting: "they clicked the page!" });
});

対応するバックグラウンドスクリプトは、

コンテンツスクリプトからの通信試行を待ち受けする
通信試行を受け取ったとき、
- portFromCS という名前の変数にポートを格納する
- そのポートを使ってコンテンツスクリプトにメッセージを送る
- ポートに届いたメッセージを待ち受けしてログに出す
ユーザーが拡張機能のブラウザーアクションをクリックしたとき、portFromCS を使ってコンテンツスクリプトにメッセージを送る

// background-script.js

let portFromCS;

function connected(p) {
  portFromCS = p;
  portFromCS.postMessage({ greeting: "hi there content script!" });
  portFromCS.onMessage.addListener((m) => {
    portFromCS.postMessage({
      greeting: `In background script, received message from content script: ${m.greeting}`,
    });
  });
}

browser.runtime.onConnect.addListener(connected);

browser.browserAction.onClicked.addListener(() => {
  portFromCS.postMessage({ greeting: "they clicked the button!" });
});

複数のコンテンツスクリプト

同時に複数のコンテンツスクリプトが通信する場合、各接続を配列に格納するのが良いかもしれません。

// background-script.js

let ports = [];

function connected(p) {
  ports[p.sender.tab.id] = p;
  // …
}

browser.runtime.onConnect.addListener(connected);

browser.browserAction.onClicked.addListener(() => {
  ports.forEach((p) => {
    p.postMessage({ greeting: "they clicked the button!" });
  });
});

単発メッセージとコネクションベースのメッセージとの選択

単発とコネクションベースのメッセージの選択は、拡張機能がどうメッセージを利用すると期待されるかに依存します。

推奨されるベストプラクティスは、次の通りです。

単発メッセージを使用する場合
- メッセージに 1 つだけの応答がある場合
- メッセージの受信を少しのスクリプトが待ち受けする場合(runtime.onMessage 呼び出し)
コネクションベースのメッセージを使用する場合
- スクリプトが、複数のメッセージを交換するセッションに関わる場合
- 拡張機能がタスクの進捗や、タスクが中断されたのを知る必要がある場合、または初期化されたタスクをメッセージング経由で中断したい場合

ウェブページとの通信

既定では、コンテンツスクリプトはページスクリプトが作成したオブジェクトにアクセスできませんが、DOM window.postMessage と window.addEventListener API を使ってページスクリプトと通信できます。

例えば:

// page-script.js

let messenger = document.getElementById("from-page-script");

messenger.addEventListener("click", messageContentScript);

function messageContentScript() {
  window.postMessage(
    {
      direction: "from-page-script",
      message: "Message from the page",
    },
    "*",
  );
}

// content-script.js

window.addEventListener("message", (event) => {
  if (
    event.source === window &&
    event?.data?.direction === "from-page-script"
  ) {
    alert(`Content script received message: "${event.data.message}"`);
  }
});

これの完全な動作サンプルは、GitHub のデモページに行って指示に従ってください。

警告: この方法で信頼できないウェブコンテンツと相互作用するには細心の注意が必要です！拡張機能は強力な力を持つコードの権限があり、敵意のあるウェブページは簡単にこの力にアクセスします。

細かい例を作るには、メッセージを受け取ったコンテンツスクリプトがこのようなことを行うと仮定してください:

// content-script.js

window.addEventListener("message", (event) => {
  if (
    event.source === window &&
    event?.data?.direction === "from-page-script"
  ) {
    eval(event.data.message);
  }
});

今やページスクリプトはコンテンツスクリプトのすべての権限でコードを実行できます。

コンテンツスクリプト内で eval() を使う

メモ: eval() はマニフェスト V3 では利用できません。

Chrome では

eval は常にページコンテキストではなくてコンテンツスクリプトのコンテキストで動作します。

Firefox では

eval() を呼ぶ場合、コンテンツスクリプトのコンテキストで動作します。

window.eval() を呼ぶ場合、ページのコンテキストで動作します。

例えば、こんなコンテンツスクリプトを考えてみます。

// content-script.js

window.eval("window.x = 1;");
eval("window.y = 2");

console.log(`In content script, window.x: ${window.x}`);
console.log(`In content script, window.y: ${window.y}`);

window.postMessage(
  {
    message: "check",
  },
  "*",
);

このコードは単に変数 x と y を、window.eval() と eval() を用いて作成し、値をログに出し、ページにメッセージします。

メッセージの受信に際し、ページスクリプトは同じ変数をログに出します。

window.addEventListener("message", (event) => {
  if (event.source === window && event.data && event.data.message === "check") {
    console.log(`In page script, window.x: ${window.x}`);
    console.log(`In page script, window.y: ${window.y}`);
  }
});

Chrome では、こんな出力が生成されます:

In content script, window.x: 1
In content script, window.y: 2
In page script, window.x: undefined
In page script, window.y: undefined

Firefox では、こんな出力が生成されます:

In content script, window.x: undefined
In content script, window.y: 2
In page script, window.x: 1
In page script, window.y: undefined

同じことは setTimeout()、setInterval()、Function() にも言えます。

警告: ページのコンテキストでコードを実行するときは特に注意してください！

ページの環境が悪意をはらんだウェブページにコントロールされ、期待しない方法であなたが操作するオブジェクトを再定義するかもしれません。

// page.js redefines console.log

let original = console.log;

console.log = () => {
  original(true);
};

// content-script.js calls the redefined version

window.eval("console.log(false)");