browser.runtime

説明

chrome.runtime API を使用して、サービス ワーカーを取得し、マニフェストの詳細を返します。また、拡張機能のライフサイクルでイベントをリッスンして応答します。この API を使用して、URL の相対パスを完全修飾 URL に変換することもできます。

この API のほとんどのメンバーは権限を必要としません。この権限は、connectNative()、sendNativeMessage()、onNativeConnect に必要です。

次の例は、マニフェストで "nativeMessaging" 権限を宣言する方法を示しています。

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

コンセプトと使用方法

Runtime API には、拡張機能で使用できるさまざまな領域をサポートするメソッドが用意されています。

メッセージ パッシング
拡張機能は、拡張機能内のさまざまなコンテキストと通信できます。また、connect()、onConnect、onConnectExternal、sendMessage()、onMessage、onMessageExternal のメソッドとイベントを使用して、他の拡張機能と通信することもできます。また、拡張機能は、connectNative() と sendNativeMessage() を使用して、ユーザーのデバイス上のネイティブ アプリケーションにメッセージを渡すことができます。
拡張機能とプラットフォームのメタデータへのアクセス
これらのメソッドを使用すると、拡張機能とプラットフォームに関する特定のメタデータをいくつか取得できます。このカテゴリのメソッドには、getManifest()、getPlatformInfo() などがあります。
拡張機能のライフサイクルとオプションの管理
これらのプロパティを使用すると、拡張機能に対してメタ オペレーションを実行し、オプション ページを表示できます。 このカテゴリのメソッドとイベントには、onInstalled、onStartup、openOptionsPage()、reload()、requestUpdateCheck()、setUninstallURL() があります。
ヘルパー ユーティリティ
これらのメソッドは、内部リソース表現を外部形式に変換するなどのユーティリティを提供します。このカテゴリのメソッドには、getURL() があります。
キオスクモード ユーティリティ
これらのメソッドは ChromeOS でのみ使用でき、主にキオスクの実装をサポートするために存在します。このカテゴリのメソッドには、restart() と restartAfterDelay() があります。

パッケージ化されていない拡張機能の動作

解凍された拡張機能が再読み込みされると、これは更新として扱われます。つまり、browser.runtime.onInstalled イベントは "update" の理由で発生します。これには、拡張機能が browser.runtime.reload() で再読み込みされた場合も含まれます。

ユースケース

ウェブページに画像を追加する

ウェブページが別のドメインでホストされているアセットにアクセスするには、リソースの完全な URL（<img src="https://example.com/logo.png"> など）を指定する必要があります。ウェブページに拡張機能アセットを含める場合も同様です。2 つの違いは、拡張機能のアセットをウェブからアクセス可能なリソースとして公開する必要があることと、通常はコンテンツ スクリプトが拡張機能のアセットの挿入を担当することです。

この例では、拡張機能は runtime.getURL() を使用して完全修飾 URL を作成し、コンテンツ スクリプトが挿入されているページに logo.png を追加します。ただし、まず、マニフェストでアセットをウェブアクセス可能なリソースとして宣言する必要があります。

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = browser.runtime.getURL('logo.png');
  document.body.append(img);
}

コンテンツ スクリプトから Service Worker にデータを送信する

拡張機能のコンテンツ スクリプトが、サービス ワーカーなど、拡張機能の別の部分で管理されているデータを必要とすることはよくあります。同じウェブページを開いた 2 つのブラウザ ウィンドウと同様に、これら 2 つのコンテキストは互いの値に直接アクセスできません。代わりに、拡張機能はメッセージ パッシングを使用して、これらの異なるコンテキスト間で調整できます。

この例では、コンテンツ スクリプトが UI を初期化するために、拡張機能の Service Worker からデータを取得する必要があります。このデータを取得するために、デベロッパーが定義した get-user-data メッセージをサービス ワーカーに渡し、ユーザー情報のコピーを返します。

content.js:

// 1. Send a message to the service worker requesting the user's data
browser.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

アンインストールに関するフィードバックを収集する

多くの拡張機能では、アンインストール後のアンケートを使用して、拡張機能がユーザーにどのように役立つか、また、ユーザー維持率を向上させる方法を把握しています。次の例は、この機能を追加する方法を示しています。

background.js:

browser.runtime.onInstalled.addListener(details => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    browser.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

例

Runtime API のその他の例については、Manifest V3 - ウェブからアクセス可能なリソースのデモをご覧ください。

型

ContextFilter

Chrome 114 以降

特定の拡張機能コンテキストと照合するフィルタ。一致するコンテキストは、指定されたすべてのフィルタに一致する必要があります。指定されていないフィルタは、使用可能なすべてのコンテキストに一致します。したがって、`{}` のフィルタは、使用可能なすべてのコンテキストに一致します。

プロパティ

  • contextIds

    string[] 省略可

  • contextTypes

    ContextType[] 省略可

  • documentIds

    string[] 省略可

  • documentOrigins

    string[] 省略可

  • documentUrls

    string[] 省略可

  • frameIds

    number[] 省略可

  • シークレット

    boolean 省略可

  • tabIds

    number[] 省略可

  • windowIds

    number[] 省略可

ContextType

Chrome 114 以降

列挙型

"TAB"
コンテキスト タイプをタブとして指定します

"POPUP"
コンテキスト タイプを拡張機能のポップアップ ウィンドウとして指定します。

"BACKGROUND"
コンテキスト タイプを Service Worker として指定します。

"OFFSCREEN_DOCUMENT"
コンテキスト タイプをオフスクリーン ドキュメントとして指定します。

"SIDE_PANEL"
コンテキスト タイプをサイドパネルとして指定します。

"DEVELOPER_TOOLS"
コンテキスト タイプをデベロッパー ツールとして指定します。

ExtensionContext

Chrome 114 以降

拡張機能のコンテンツをホストするコンテキスト。

プロパティ

  • contextId

    文字列

    このコンテキストの固有識別子

  • contextType

    ContextType

    これに対応するコンテキストのタイプ。

  • documentId

    文字列 省略可

    このコンテキストに関連付けられたドキュメントの UUID。このコンテキストがドキュメントでホストされていない場合は未定義。

  • documentOrigin

    文字列 省略可

    このコンテキストに関連付けられたドキュメントのオリジン。コンテキストがドキュメントでホストされていない場合は未定義。

  • documentUrl

    文字列 省略可

    このコンテキストに関連付けられているドキュメントの URL。コンテキストがドキュメントでホストされていない場合は未定義。

  • frameId

    数値

    このコンテキストのフレームの ID。このコンテキストがフレームでホストされていない場合は -1。

  • シークレット

    ブール値

    コンテキストがシークレット プロファイルに関連付けられているかどうか。

  • tabId

    数値

    このコンテキストのタブの ID。このコンテキストがタブでホストされていない場合は -1。

  • windowId

    数値

    このコンテキストのウィンドウの ID。このコンテキストがウィンドウでホストされていない場合は -1。

ExtensionLoadDetails

Chrome 157 以降

拡張機能の読み込みイベントの詳細。

プロパティ

  • previousVersion

    文字列 省略可

    拡張機能の以前のバージョンを示します。これは、reason が update または enable の場合にのみ存在します。reason が update の場合、これは更新前の拡張機能のバージョンです。「reason」が「enable」の場合、これは拡張機能の現在のバージョンです。

  • このイベントがディスパッチされる理由。

MessageSender

メッセージまたはリクエストを送信したスクリプト コンテキストに関する情報を含むオブジェクト。

プロパティ

  • documentId

    文字列 省略可

    Chrome 106 以降

    接続を開いたドキュメントの UUID。

  • documentLifecycle

    文字列 省略可

    Chrome 106 以降

    ポートが作成された時点で、接続を開いたドキュメントが属しているライフサイクル。ドキュメントのライフサイクル ステータスは、ポートの作成後に変更されている可能性があります。

  • frameId

    number 省略可

    接続を開いたフレーム。最上位フレームの場合は 0、子フレームの場合は正の整数。これは、tab が設定されている場合にのみ設定されます。

  • id

    文字列 省略可

    接続を開いた拡張機能の ID（存在する場合）。

  • nativeApplication

    文字列 省略可

    Chrome 74 以降

    接続を開いたネイティブ アプリケーションの名前（存在する場合）。

  • origin

    文字列 省略可

    Chrome 80 以降

    接続を開いたページまたはフレームのオリジン。url プロパティ（about:blank など）とは異なる場合や、不透明な場合（サンドボックス化された iframe など）があります。これは、URL からすぐに判断できない場合に、オリジンが信頼できるかどうかを識別するのに役立ちます。

  • タブ

    タブ 省略可

    接続を開いた tabs.Tab（存在する場合）。このプロパティは、接続がタブ（コンテンツ スクリプトを含む）から開かれた場合にのみ存在し、受信側がアプリではなく拡張機能である場合にのみ存在します。

  • tlsChannelId

    文字列 省略可

    接続を開いたページまたはフレームの TLS チャンネル ID（拡張機能によってリクエストされ、利用可能な場合）。

  • URL

    文字列 省略可

    接続を開いたページまたはフレームの URL。送信者が iframe 内にある場合、iframe の URL になります。iframe をホストするページの URL ではありません。

OnInstalledReason

Chrome 44 以降

このイベントがディスパッチされる理由。

列挙型

"install"
イベントの理由をインストールとして指定します。

"update"
イベントの理由を拡張機能の更新として指定します。

"chrome_update"
イベントの理由を Chrome の更新として指定します。

"shared_module_update"
イベントの理由を共有モジュールの更新として指定します。

OnLoadedReason

Chrome 157 以降

このイベントがディスパッチされる理由。

列挙型

"install"
拡張機能が新たにインストールされました。

"update"
拡張機能が更新後に再読み込みされました。

"browser_update"
ブラウザが新しいバージョンに更新されました。

"enable"
拡張機能が無効な状態から再度有効になりました。

"startup"
拡張機能はブラウザの起動時に読み込まれます。

"reload"
拡張機能が再読み込みされた（例: chrome.runtime.reload() を使用、またはユーザーが手動で拡張機能を再読み込みした）。

OnRestartRequiredReason

Chrome 44 以降

イベントがディスパッチされる理由。「app_update」は、アプリケーションが新しいバージョンに更新されたために再起動が必要な場合に使用されます。「os_update」は、ブラウザまたは OS が新しいバージョンに更新されたために再起動が必要な場合に使用されます。「periodic」は、エンタープライズ ポリシーで設定された許可された稼働時間を超えてシステムが実行されている場合に使用されます。

列挙型

"app_update"
イベントの理由をアプリのアップデートとして指定します。

"os_update"
イベントの理由をオペレーティング システムのアップデートとして指定します。

"periodic"
イベントの理由として、アプリの定期的な再起動を指定します。

PlatformArch

Chrome 44 以降

マシンのプロセッサ アーキテクチャ。

列挙型

"arm"
プロセッサ アーキテクチャを arm として指定します。

"arm64"
プロセッサ アーキテクチャを arm64 として指定します。

"x86-32"
プロセッサ アーキテクチャを x86-32 として指定します。

"x86-64"
プロセッサ アーキテクチャを x86-64 として指定します。

"mips"
プロセッサ アーキテクチャを mips として指定します。

"mips64"
プロセッサ アーキテクチャを mips64 として指定します。

"riscv64"
プロセッサ アーキテクチャを riscv64 として指定します。

PlatformInfo

現在のプラットフォームに関する情報を含むオブジェクト。

プロパティ

  • マシンのプロセッサ アーキテクチャ。

  • nacl_arch

    PlatformNaclArch 省略可

    Chrome 149 以降、非推奨

    この属性は、Native Client の完全な削除に伴い非推奨となりました。

    ネイティブ クライアント アーキテクチャ。プラットフォームによっては、arch と異なる場合があります。

  • Chrome が実行されているオペレーティング システム。

PlatformNaclArch

Chrome 44 以降 Chrome 149 以降は非推奨

この列挙型は、Native Client の完全な削除に伴い非推奨となりました。

ネイティブ クライアント アーキテクチャ。プラットフォームによっては、arch と異なる場合があります。

列挙型

"arm"
ネイティブ クライアント アーキテクチャを arm として指定します。

"x86-32"
ネイティブ クライアント アーキテクチャを x86-32 として指定します。

"x86-64"
ネイティブ クライアント アーキテクチャを x86-64 として指定します。

"mips"
ネイティブ クライアント アーキテクチャを mips として指定します。

"mips64"
ネイティブ クライアント アーキテクチャを mips64 として指定します。

PlatformOs

Chrome 44 以降

Chrome が実行されているオペレーティング システム。

列挙型

"mac"
MacOS オペレーティング システムを指定します。

"win"
Windows オペレーティング システムを指定します。

"android"
Android オペレーティング システムを指定します。

"cros"
Chrome オペレーティング システムを指定します。

"linux"
Linux オペレーティング システムを指定します。

"openbsd"
OpenBSD オペレーティング システムを指定します。

Port

他のページとの双方向通信を可能にするオブジェクト。詳細については、長時間接続をご覧ください。

プロパティ

  • name

    文字列

    runtime.connect の呼び出しで指定されたポートの名前。

  • onDisconnect

    イベント<functionvoidvoid>

    ポートがもう一方の端から切断されたときに呼び出されます。エラーによりポートが切断された場合、runtime.lastError が設定されることがあります。ポートが disconnect で閉じられた場合、このイベントはもう一方の端でのみ発生します。このイベントは、最大で 1 回発生します（ポートの有効期間もご覧ください）。

    onDisconnect.addListener 関数は次のようになります。 

    (callback: function) => {...}

    • callback

      関数

      callback パラメータは次のようになります。 

      (port: Port) => void

  • onMessage

    イベント<functionvoidvoid>

    このイベントは、ポートのもう一方の端で postMessage が呼び出されたときに発生します。

    onMessage.addListener 関数は次のようになります。 

    (callback: function) => {...}

    • callback

      関数

      callback パラメータは次のようになります。 

      (message: any, port: Port) => void

  • sender

    MessageSender 省略可

    このプロパティは、onConnect / onConnectExternal / onConnectNative リスナーに渡されるポートにのみ存在します。

  • 接続を解除

    void

    すぐにポートを外します。すでに切断されているポートで disconnect() を呼び出しても効果はありません。ポートが切断されると、新しいイベントはこのポートにディスパッチされません。

    disconnect 関数は次のようになります。 

    () => {...}

  • postMessage

    void

    ポートのもう一方の端にメッセージを送信します。ポートが切断されている場合は、エラーがスローされます。

    postMessage 関数は次のようになります。 

    (message: any) => {...}

    • メッセージ

      任意

      Chrome 52 以降

      送信するメッセージ。このオブジェクトは JSON 形式に変換できる必要があります。

RequestUpdateCheckStatus

Chrome 44 以降

更新チェックの結果。

列挙型

"throttled"
ステータス チェックがスロットリングされたことを指定します。これは、短時間で繰り返しチェックを行った後に発生することがあります。

"no_update"
インストール可能なアップデートがないことを指定します。

"update_available"
インストール可能なアップデートがあることを示します。

プロパティ

id

拡張機能 / アプリの ID。

タイプ

文字列

lastError

API 関数の呼び出しが失敗した場合は、エラー メッセージが入力されます。それ以外の場合は未定義です。これは、その関数のコールバックのスコープ内でのみ定義されます。エラーが発生しても、コールバック内で runtime.lastError にアクセスされない場合は、エラーを生成した API 関数を一覧表示するメッセージがコンソールに記録されます。Promise を返す API 関数では、このプロパティは設定されません。

タイプ

オブジェクト

プロパティ

  • メッセージ

    文字列 省略可

    発生したエラーの詳細。

メソッド

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
): Port

拡張機能（バックグラウンド ページなど）または他の拡張機能やアプリ内のリスナーに接続を試みます。これは、拡張機能プロセスに接続するコンテンツ スクリプト、アプリ間 / 拡張機能間の通信、ウェブ メッセージングに役立ちます。これは、コンテンツ スクリプト内のリスナーには接続しません。拡張機能は、tabs.connect を介してタブに埋め込まれたコンテンツ スクリプトに接続できます。

パラメータ

  • extensionId

    文字列 省略可

    接続先の拡張機能の ID。省略すると、独自の拡張機能との接続が試行されます。ウェブ メッセージのためにウェブページからメッセージを送信する場合に必要です。

  • connectInfo

    オブジェクト（省略可）

    • includeTlsChannelId

      boolean 省略可

      接続イベントをリッスンしているプロセスに対して、TLS チャネル ID を onConnectExternal に渡すかどうか。

    • name

      文字列 省略可

      接続イベントをリッスンしているプロセスの onConnect に渡されます。

戻り値

  • メッセージを送受信できるポート。拡張機能が存在しない場合、ポートの onDisconnect イベントが発生します。

connectNative()

chrome.runtime.connectNative(
  application: string,
): Port

ホストマシンのネイティブ アプリケーションに接続します。このメソッドには "nativeMessaging" 権限が必要です。詳細については、ネイティブ メッセージングをご覧ください。

パラメータ

  • アプリケーション

    文字列

    接続先の登録済みアプリケーションの名前。

戻り値

  • アプリケーションでメッセージを送受信できるポート

getBackgroundPage()

フォアグラウンドのみ Chrome 133 以降、非推奨
chrome.runtime.getBackgroundPage(): Promise<Window | undefined>

MV3 拡張機能にはバックグラウンド ページは存在しません。

現在の拡張機能 / アプリ内で実行されているバックグラウンド ページの JavaScript の「window」オブジェクトを取得します。バックグラウンド ページがイベントページの場合、システムはコールバックを呼び出す前に、そのページが読み込まれていることを確認します。バックグラウンド ページがない場合は、エラーが設定されます。

戻り値

  • Promise<Window | undefined>

    Chrome 99 以降

getContexts()

Chrome 116 以降 MV3 以降 
chrome.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

この拡張機能に関連付けられているアクティブなコンテキストに関する情報を取得します。

パラメータ

  • filter

    ContextFilter

    一致するコンテキストを検索するフィルタ。コンテキストは、フィルタで指定されたすべてのフィールドに一致する場合に一致します。フィルタで指定されていないフィールドは、すべてのコンテキストに一致します。

戻り値

  • Promise<ExtensionContext[]>

    一致するコンテキスト（存在する場合）で解決される Promise。

getManifest()

chrome.runtime.getManifest(): object

マニフェストからアプリまたは拡張機能の詳細を返します。返されるオブジェクトは、完全なマニフェスト ファイルのシリアル化です。

戻り値

  • オブジェクト

    マニフェストの詳細。

getPackageDirectoryEntry()

フォアグラウンドのみ 
chrome.runtime.getPackageDirectoryEntry(): Promise<DirectoryEntry>

パッケージ ディレクトリの DirectoryEntry を返します。

戻り値

  • Promise<DirectoryEntry>

    Chrome 122 以降

getPlatformInfo()

chrome.runtime.getPlatformInfo(): Promise<PlatformInfo>

現在のプラットフォームに関する情報を返します。

戻り値

  • Promise<PlatformInfo>

    Chrome 99 以降

    現在のプラットフォームに関する情報で解決される Promise。

getURL()

chrome.runtime.getURL(
  path: string,
): string

アプリ / 拡張機能のインストール ディレクトリ内の相対パスを完全修飾 URL に変換します。

パラメータ

  • パス

    文字列

    インストール ディレクトリを基準とした、アプリ / 拡張機能内のリソースへのパス。

戻り値

  • 文字列

    リソースの完全修飾 URL。

getVersion()

Chrome 143 以降 
chrome.runtime.getVersion(): string

マニフェストで宣言されている拡張機能のバージョンを返します。

戻り値

  • 文字列

    拡張機能のバージョン。

openOptionsPage()

chrome.runtime.openOptionsPage(): Promise<void>

可能であれば、拡張機能のオプション ページを開きます。

正確な動作は、マニフェストの options_ui キーまたは options_page キー、またはその時点で Chrome がサポートしている内容によって異なる場合があります。たとえば、新しいタブ、chrome://extensions、アプリ内でページを開くことも、開いているオプション ページにフォーカスを合わせることもできます。呼び出し元のページが再読み込みされることはありません。

拡張機能でオプション ページが宣言されていない場合、または他の理由で Chrome がオプション ページを作成できなかった場合、コールバックは lastError を設定します。

戻り値

  • Promise<void>

    Chrome 99 以降

reload()

chrome.runtime.reload(): void

アプリまたは拡張機能を再読み込みします。このメソッドはキオスクモードではサポートされていません。キオスクモードの場合は、chrome.runtime.restart() メソッドを使用します。

requestUpdateCheck()

chrome.runtime.requestUpdateCheck(): Promise<object>

このアプリ / 拡張機能のアップデートをすぐに確認するようリクエストします。

重要: ほとんどの拡張機能やアプリでは、このメソッドを使用しないでください。Chrome はすでに数時間ごとに自動チェックを行っており、requestUpdateCheck を呼び出さなくても runtime.onUpdateAvailable イベントをリッスンできます。

このメソッドは、拡張機能がバックエンド サービスと通信し、バックエンド サービスがクライアント拡張機能のバージョンが非常に古いと判断した場合や、ユーザーに更新を促す場合など、非常に限られた状況でのみ呼び出すのに適しています。requestUpdateCheck のその他のほとんどの使用方法（繰り返しタイマーに基づいて無条件に呼び出すなど）は、クライアント、ネットワーク、サーバーのリソースを浪費するだけです。

注: コールバックを指定して呼び出した場合、この関数はオブジェクトを返すのではなく、2 つのプロパティを個別の引数としてコールバックに渡します。

戻り値

  • Promise<object>

    Chrome 109 以降

restart()

chrome.runtime.restart(): void

アプリがキオスクモードで実行されているときに ChromeOS デバイスを再起動します。それ以外の場合は no-op です。

restartAfterDelay()

Chrome 53 以降 
chrome.runtime.restartAfterDelay(
  seconds: number,
): Promise<void>

アプリがキオスクモードで実行されている場合に、指定した秒数が経過すると ChromeOS デバイスを再起動します。時間が経過する前に再度呼び出されると、再起動が遅れます。値 -1 で呼び出された場合、再起動はキャンセルされます。キオスクモード以外では、これは no-op です。この API を呼び出す最初の拡張機能のみが、繰り返し呼び出すことができます。

パラメータ

  • 秒

    数値

    デバイスを再起動するまでの待機時間（秒）。スケジュールされた再起動をキャンセルする場合は -1。

戻り値

  • Promise<void>

    Chrome 99 以降

    再起動リクエストが正常に再スケジュールされたときに解決される Promise。

sendMessage()

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
): Promise<any>

拡張機能内または別の拡張機能 / アプリ内のイベント リスナーに単一のメッセージを送信します。runtime.connect と同様ですが、単一のメッセージのみを送信し、オプションでレスポンスを送信します。拡張機能に送信する場合、runtime.onMessage イベントは拡張機能のすべてのフレーム（送信者のフレームを除く）で、または別の拡張機能の場合は runtime.onMessageExternal で、それぞれ発生します。拡張機能は、このメソッドを使用してコンテンツ スクリプトにメッセージを送信することはできません。コンテンツ スクリプトにメッセージを送信するには、tabs.sendMessage を使用します。

パラメータ

  • extensionId

    文字列 省略可

    メッセージの送信先となる拡張機能の ID。省略すると、メッセージは独自の拡張機能 / アプリに送信されます。ウェブ メッセージングのウェブページからメッセージを送信する場合は必須です。

  • メッセージ

    任意

    送信するメッセージ。このメッセージは JSON 形式のオブジェクトにする必要があります。

  • オプション

    オブジェクト（省略可）

    • includeTlsChannelId

      boolean 省略可

      接続イベントをリッスンしているプロセスに TLS チャネル ID を渡すかどうか。

戻り値

  • Promise<any>

    Chrome 99 以降

    Chrome 99 で、拡張機能コンテキストに Promise のサポートが追加されました。ウェブページから拡張機能に通信する場合、Chrome 118 以降で Promise を使用できます。

sendNativeMessage()

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
): Promise<any>

ネイティブ アプリケーションに 1 つのメッセージを送信します。このメソッドには "nativeMessaging" 権限が必要です。

パラメータ

  • アプリケーション

    文字列

    ネイティブ メッセージング ホストの名前、またはターゲットの詳細。

  • メッセージ

    オブジェクト

    ネイティブ メッセージング ホストに渡されるメッセージ。

戻り値

  • Promise<any>

    Chrome 99 以降

setUninstallURL()

chrome.runtime.setUninstallURL(
  url: string,
): Promise<void>

アンインストール時にアクセスする URL を設定します。これは、サーバーサイドのデータのクリーンアップ、分析、アンケートの実施に使用できます。最大 1,023 文字です。

パラメータ

  • URL

    文字列

    拡張機能のアンインストール後に開く URL。この URL には http: または https: スキームが必要です。アンインストール時に新しいタブを開かないようにするには、空の文字列を設定します。

戻り値

  • Promise<void>

    Chrome 99 以降

    アンインストール URL が設定されると解決される Promise。指定された URL が無効な場合、Promise は拒否されます。

イベント

onBrowserUpdateAvailable

非推奨
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

runtime.onRestartRequired を使用してください。

Chrome のアップデートが利用可能になったものの、ブラウザの再起動が必要なため、すぐにはインストールされない場合に呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

拡張機能プロセスまたはコンテンツ スクリプトから（runtime.connect によって）接続が確立されたときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (port: Port) => void

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

別の拡張機能（runtime.connect による）または外部接続可能なウェブサイトから接続が確立されたときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (port: Port) => void

onConnectNative

Chrome 76 以降 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

ネイティブ アプリケーションから接続が確立されたときに呼び出されます。このイベントには "nativeMessaging" 権限が必要です。Chrome OS でのみサポートされています。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (port: Port) => void

onEnabled

Chrome 155 以降 
chrome.runtime.onEnabled.addListener(
  callback: function,
)

拡張機能が無効な状態から有効な状態に移行したときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    () => void

onExtensionLoaded

Chrome 157 以降 
chrome.runtime.onExtensionLoaded.addListener(
  callback: function,
)

拡張機能が有効な拡張機能のセットに追加されたときに呼び出されます。これは、拡張機能が最初にインストールされたとき、新しいバージョンに更新されたとき、無効になった後に再度有効になったとき、再読み込みされたとき、ブラウザの起動時に読み込まれたとき、ブラウザが新しいバージョンに更新されたときに読み込まれたときなど、複数のシナリオで発生する可能性があります。

パラメータ

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

拡張機能が初めてインストールされたとき、拡張機能が新しいバージョンに更新されたとき、Chrome が新しいバージョンに更新されたときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • id

        文字列 省略可

        更新されたインポート済み共有モジュール拡張機能の ID を示します。これは、reason が shared_module_update の場合にのみ存在します。

      • previousVersion

        文字列 省略可

        更新された拡張機能の以前のバージョンを示します。これは、reason が update の場合にのみ存在します。

      • このイベントがディスパッチされる理由。

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

runtime.sendMessage または tabs.sendMessage からメッセージが送信されたときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

    • メッセージ

      任意

    • sender

      MessageSender

    • sendResponse

      関数

      sendResponse パラメータは次のようになります。 

      (response?: any) => void

      • レスポンス

        any 省略可

        メッセージ送信者に返すレスポンス。

    • 戻り値

      boolean | Promise<any> | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

別の拡張機能から（runtime.sendMessage によって）メッセージが送信されたときに呼び出されます。コンテンツ スクリプトでは使用できません。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | Promise<any> | undefined

    • メッセージ

      任意

    • sender

      MessageSender

    • sendResponse

      関数

      sendResponse パラメータは次のようになります。 

      (response?: any) => void

      • レスポンス

        any 省略可

        メッセージ送信者に返すレスポンス。

    • 戻り値

      boolean | Promise<any> | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

アプリまたはアプリが実行されているデバイスを再起動する必要がある場合に呼び出されます。アプリは、できるだけ早いタイミングですべてのウィンドウを閉じて、再起動が行われるようにする必要があります。アプリが何も行わない場合、24 時間の猶予期間が経過した後に再起動が強制されます。現在、このイベントは ChromeOS キオスクアプリでのみ発生します。

パラメータ

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

この拡張機能がインストールされているプロファイルが初めて起動したときに発生します。このイベントは、この拡張機能が「分割」シークレット モードで動作している場合でも、シークレット プロファイルの開始時には発生しません。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

イベントページがアンロードされる直前に送信されます。これにより、拡張機能はクリーンアップを行うことができます。ページがアンロードされるため、このイベントの処理中に開始された非同期オペレーションが完了する保証はありません。イベントページがアンロードされる前に、そのページでさらにアクティビティが発生すると、onSuspendCanceled イベントが送信され、ページはアンロードされません。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

onSuspend の後に送信され、アプリがアンロードされないことを示します。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

アップデートが利用可能になったものの、アプリが現在実行中のため、すぐにはインストールされない場合に呼び出されます。何もしない場合、アップデートは次にバックグラウンド ページがアンロードされたときにインストールされます。すぐにインストールしたい場合は、chrome.runtime.reload() を明示的に呼び出すことができます。拡張機能が永続的なバックグラウンド ページを使用している場合、バックグラウンド ページはアンロードされないため、このイベントに応じて chrome.runtime.reload() を手動で呼び出さない限り、アップデートは次に Chrome 自体が再起動されるまでインストールされません。このイベントをリッスンしているハンドラがなく、拡張機能に永続的なバックグラウンド ページがある場合、このイベントに応答して chrome.runtime.reload() が呼び出されたかのように動作します。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (details: object) => void

    • 詳細

      オブジェクト

      • version

        文字列

        利用可能なアップデートのバージョン番号。

onUserScriptConnect

Chrome 115 以降 MV3 以降 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

この拡張機能のユーザースクリプトから接続が確立されたときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (port: Port) => void

onUserScriptMessage

Chrome 115 以降 MV3 以降 
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

同じ拡張機能に関連付けられたユーザースクリプトからメッセージが送信されたときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • メッセージ

      任意

    • sender

      MessageSender

    • sendResponse

      関数

      sendResponse パラメータは次のようになります。 

      (response?: any) => void

      • レスポンス

        any 省略可

        メッセージ送信者に返すレスポンス。

    • 戻り値

      boolean | undefined