chrome.runtime

説明

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

概要

Runtime API は、拡張機能のさまざまな機能領域をサポートするメソッドを提供します 以下を使用できます。

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

権限

Runtime API のほとんどのメソッドは、権限を必要としません sendNativeMessage と connectNative です nativeMessaging 権限が必要です。

マニフェスト

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

manifest.json:

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

ユースケース

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

ウェブページが別のドメインでホストされているアセットにアクセスするには、リソースの完全な 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 = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

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

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

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

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.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);
});

background.js:

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

chrome.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:

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

拡張機能の例

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

型

ContextFilter

Chrome 114 以降

特定の広告表示オプションのコンテキストと照合するフィルタ。一致するコンテキストは、指定されたすべてのフィルタに一致する必要があります。指定されていないフィルタは、使用可能なすべてのコンテキストに一致します。したがって、`{}` のフィルタは利用可能なすべてのコンテキストに一致します。

プロパティ

  • contextIds

    文字列 [] 省略可

  • contextTypes

    ContextType[] 省略可

  • documentIds

    文字列 [] 省略可

  • documentOrigins

    文字列 [] 省略可

  • documentUrls

    文字列 [] 省略可

  • frameIds

    数値 [] 省略可

  • シークレット

    ブール値（省略可）

  • tabIds

    number[] 省略可

  • windowIds

    数値 [] 省略可

ContextType

Chrome 114 以降

列挙型

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

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

「BACKGROUND」
コンテキスト タイプをサービス ワーカーとして指定します。

"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。

MessageSender

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

プロパティ

  • documentId

    文字列（省略可）

    Chrome 106 以降

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

  • documentLifecycle

    文字列（省略可）

    Chrome 106 以降

    ポートが作成された時点で、接続を開いたドキュメントが存在するライフサイクル。ポートの作成後に、ドキュメントのライフサイクルの状態が変更された可能性があります。

  • frameId

    数値（省略可）

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

  • id

    文字列（省略可）

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

  • nativeApplication

    文字列（省略可）

    Chrome 74 以降

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

  • オリジン

    文字列（省略可）

    Chrome 80 以降

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

  • タブ

    タブ （省略可）

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

  • tlsChannelId

    文字列（省略可）

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

  • URL

    文字列（省略可）

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

OnInstalledReason

Chrome 44 以降

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

列挙型

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

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

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

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

OnRestartRequiredReason

Chrome 44 以降

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

列挙型

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

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

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

PlatformArch

Chrome 44 以降

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

列挙型

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

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

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

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

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

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

PlatformInfo

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

プロパティ

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

  • nacl_arch

    PlatformNaclArch

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

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

PlatformNaclArch

Chrome 44 以降

ネイティブ クライアントのアーキテクチャ。プラットフォームによっては、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 オペレーティング システムを指定します。

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

Port

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

プロパティ

  • name

    文字列

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

  • onDisconnect

    Event<functionvoidvoid>

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

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

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

    • callback

      関数

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

      (port: Port) => void

  • onMessage

    Event<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,
)

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

パラメータ

  • extensionId

    文字列（省略可）

    接続する拡張機能の ID。省略すると、使用している拡張機能を使用して接続が試行されます。ウェブ メッセージ用にウェブページからメッセージを送信する場合は必須。

  • connectInfo

    オブジェクト（省略可）

    • includeTlsChannelId

      ブール値（省略可）

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

    • name

      文字列（省略可）

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

戻り値

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

パラメータ

  • アプリケーション

    文字列

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

戻り値

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

getBackgroundPage()

<ph type="x-smartling-placeholder"></ph> 約束 フォアグラウンドのみ 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

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

パラメータ

  • callback

    関数（省略可）

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

    (backgroundPage?: Window) => void

    • backgroundPage

      ウィンドウ（省略可）

      バックグラウンド ページの JavaScript の「window」オブジェクト。

戻り値

  • Promise<Window | undefined>

    Chrome 99 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getContexts()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 116 以降 MV3 以降 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

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

パラメータ

  • フィルタ

    ContextFilter

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

  • callback

    関数（省略可）

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

    (contexts: ExtensionContext[]) => void

    • コンテキスト

      ExtensionContext[]

      一致するコンテキスト（ある場合）。

戻り値

  • Promise&lt;ExtensionContext[]&gt;

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getManifest()

chrome.runtime.getManifest()

マニフェストからアプリや拡張機能の詳細を返します。マニフェスト ファイル全体がシリアル化されて返されます。

戻り値

  • オブジェクト

    マニフェストの詳細。

getPackageDirectoryEntry()

<ph type="x-smartling-placeholder"></ph> 約束 フォアグラウンドのみ 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

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

パラメータ

  • callback

    関数（省略可）

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

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

戻り値

  • Promise<DirectoryEntry>

    Chrome 122 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getPlatformInfo()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.runtime.getPlatformInfo(
  callback?: function,
)

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

パラメータ

  • callback

    関数（省略可）

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

    (platformInfo: PlatformInfo) => void

戻り値

  • Promise<PlatformInfo>

    Chrome 99 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getURL()

chrome.runtime.getURL(
  path: string,
)

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

パラメータ

  • パス

    文字列

    アプリまたは拡張機能内のリソースへのパス（インストール ディレクトリを基準とする相対パス）。

戻り値

  • 文字列

    リソースの完全修飾 URL。

openOptionsPage()

Promise 
chrome.runtime.openOptionsPage(
  callback?: function,
)

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

正確な動作は、マニフェストの [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) キーまたは [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) キー、またはその時点で Chrome がサポートする機能によって異なります。たとえば、ページは新しいタブ、chrome://extensions、アプリ内で開くことができます。また、開いているオプション ページにフォーカスを当てることもできます。呼び出し元のページが再読み込みされることはありません。

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

パラメータ

  • callback

    関数（省略可）

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

    () => void

戻り値

  • Promise<void>

    Chrome 99 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.runtime.requestUpdateCheck(
  callback?: function,
)

このアプリ/拡張機能のアップデートの即時チェックをリクエストします。

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

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

注: コールバックで呼び出されると、この関数はオブジェクトを返す代わりに、2 つのプロパティをコールバックに渡す個別の引数として返します。

パラメータ

  • callback

    関数（省略可）

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

    (result: object) => void

    • 件の結果

      オブジェクト

      Chrome 109 以降

      更新チェックのステータスと、利用可能な更新がある場合の結果の詳細を保持する RequestUpdateCheckResult オブジェクト。

      • 更新チェックの結果。

      • version

        文字列（省略可）

        適用できるアップデートがある場合、利用可能なアップデートのバージョンが表示されます。

戻り値

  • Promise <オブジェクト>

    Chrome 109 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

restart()

chrome.runtime.restart()

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

restartAfterDelay()

Promise Chrome 53 以降 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

指定した秒数経過後にアプリがキオスクモードで実行されたら、ChromeOS デバイスを再起動します。時間内に再度呼び出されると、再起動は遅延されます。-1 の値で呼び出されると、再起動はキャンセルされます。キオスク以外のモードでは何も行われません。この API を呼び出した最初の拡張機能によってのみ、繰り返し呼び出されます。

パラメータ

  • 秒

    数値

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • Promise<void>

    Chrome 99 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

sendMessage()

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

拡張機能内または別の拡張機能 / アプリのイベント リスナーに 1 つのメッセージを送信します。runtime.connect に似ていますが、送信されるメッセージは 1 つだけで、返信は任意です。拡張機能に送信する場合は、拡張機能のすべてのフレーム（送信者のフレームを除く）で runtime.onMessage イベントがトリガーされます。別の拡張機能の場合は runtime.onMessageExternal です。なお、拡張機能はこの方法でコンテンツ スクリプトにメッセージを送信することはできません。コンテンツ スクリプトにメッセージを送信するには、tabs.sendMessage を使用します。

パラメータ

  • extensionId

    文字列（省略可）

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

  • メッセージ

    任意

    送信するメッセージ。このメッセージは JSON 可能なオブジェクトである必要があります。

  • オプション

    オブジェクト（省略可）

    • includeTlsChannelId

      ブール値（省略可）

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

  • callback

    関数（省略可）

    Chrome 99 以降

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

    (response: any) => void

    • レスポンス

      任意

      メッセージのハンドラから送信された JSON レスポンス オブジェクト。拡張機能への接続中にエラーが発生した場合、コールバックは引数なしで呼び出され、runtime.lastError がエラー メッセージに設定されます。

戻り値

  • Promise<any>

    Chrome 99 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

sendNativeMessage()

Promise 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

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

パラメータ

  • アプリケーション

    文字列

    ネイティブ メッセージング ホストの名前。

  • メッセージ

    オブジェクト

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

  • callback

    関数（省略可）

    Chrome 99 以降

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

    (response: any) => void

    • レスポンス

      任意

      ネイティブ メッセージング ホストから送信されたレスポンス メッセージ。ネイティブ メッセージ ホストへの接続中にエラーが発生した場合、コールバックは引数なしで呼び出され、runtime.lastError がエラー メッセージに設定されます。

戻り値

  • Promise<any>

    Chrome 99 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

setUninstallURL()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

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

パラメータ

  • URL

    文字列

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

  • callback

    関数（省略可）

    Chrome 45 以降

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

    () => void

戻り値

  • Promise<void>

    Chrome 99 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

イベント

onBrowserUpdateAvailable

<ph type="x-smartling-placeholder"></ph> 非推奨
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" 権限が必要です。ChromeOS でのみサポートされています。

パラメータ

  • callback

    関数

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

    (port: Port) => void

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 | undefined

    • メッセージ

      任意

    • sender

      MessageSender

    • sendResponse

      関数

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

      () => void

    • 戻り値

      boolean | undefined

onMessageExternal

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

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

パラメータ

  • callback

    関数

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

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

    • メッセージ

      任意

    • sender

      MessageSender

    • sendResponse

      関数

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

      () => void

    • 戻り値

      boolean | 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 パラメータは次のようになります。 

      () => void

    • 戻り値

      boolean | undefined