このページは Cloud Translation API によって翻訳されました。

chrome.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() などがあります。

展開されていない拡張機能の動作

展開済みの拡張機能が再読み込みされると、更新として扱われます。つまり、"update" の理由で chrome.runtime.onInstalled イベントが発生します。これには、chrome.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 = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

コンテンツスクリプトからサービスワーカーにデータを送信する

拡張機能のコンテンツスクリプトでは、サービスワーカーなど、拡張機能の別の部分で管理されるデータが必要になることがよくあります。同じウェブページを開いた 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);
});

service-worker.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 - Web Accessible Resources デモをご覧ください。

型

ContextFilter

Chrome 114 以降

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

プロパティ

contextIds

string[] 省略可
contextTypes

ContextType[] 省略可
documentIds

string[] 省略可
documentOrigins

string[] 省略可
documentUrls

string[] 省略可
frameIds

number[] 省略可
シークレット

ブール値（省略可）
tabIds

number[] 省略可
windowIds

number[] 省略可

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

number（省略可）

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

文字列省略可

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

文字列省略可

Chrome 74 以降

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

文字列省略可

Chrome 80 以降

接続を開いたページまたはフレームのオリジン。これは、url プロパティとは異なる場合もあれば、不透明な場合もあります（サンドボックス化された 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"
共有モジュールの更新としてイベントの理由を指定します。

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 として指定します。

PlatformInfo

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

プロパティ

arch

PlatformArch

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

PlatformNaclArch

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

PlatformOs

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 が設定されることがあります。ポートが切断によって閉じられた場合、このイベントは相手側でのみ発生します。このイベントは最大 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 以降

更新チェックの結果。

列挙型

「スロットリング」
ステータスチェックがスロットリングされていることを指定します。これは、短時間に何度もチェックを行った場合に発生することがあります。

「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()

Promise フォアグラウンドのみ

chrome.runtime.getBackgroundPage(
  callback?: function,
)

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

パラメータ

callback

function 省略可

callback パラメータは次のようになります。
```
(backgroundPage?: Window) => void
```
- backgroundPage
  
  ウィンドウ（省略可）
  
  バックグラウンドページの JavaScript の「window」オブジェクト。

戻り値

Promise<Window | undefined>

Chrome 99 以降

Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

getContexts()

Promise Chrome 116 以降 MV3 以降

chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

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

パラメータ

フィルタ

ContextFilter

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

function 省略可

callback パラメータは次のようになります。
```
(contexts: ExtensionContext[]) => void
```
- コンテキスト
  
  ExtensionContext[]
  
  一致するコンテキスト（存在する場合）。

戻り値

Promise<ExtensionContext[]>

Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

getManifest()

chrome.runtime.getManifest()

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

戻り値

オブジェクト

マニフェストの詳細。

getPackageDirectoryEntry()

Promise フォアグラウンドのみ

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

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

パラメータ

callback

function 省略可

callback パラメータは次のようになります。
```
(directoryEntry: DirectoryEntry) => void
```
- directoryEntry
  
  DirectoryEntry

戻り値

Promise<DirectoryEntry>

Chrome 122 以降

Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

getPlatformInfo()

Promise

chrome.runtime.getPlatformInfo(
  callback?: function,
)

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

パラメータ

callback

function 省略可

callback パラメータは次のようになります。
```
(platformInfo: PlatformInfo) => void
```
- platformInfo
  
  PlatformInfo

戻り値

Promise<PlatformInfo>

Chrome 99 以降

Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

getURL()

chrome.runtime.getURL(
  path: string,
)

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

パラメータ

パス

文字列

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

戻り値

文字列

リソースの完全修飾 URL。

openOptionsPage()

Promise

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

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

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

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

パラメータ

callback

function 省略可

callback パラメータは次のようになります。
```
() => void
```

戻り値

Promise<void>

Chrome 99 以降

Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

Promise

chrome.runtime.requestUpdateCheck(
  callback?: function,
)

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

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

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

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

パラメータ

callback

function 省略可

callback パラメータは次のようになります。
```
(result: object) => void
```
- 件の結果
  
  オブジェクト
  
  Chrome 109 以降
  
  RequestUpdateCheckResult オブジェクト。更新チェックのステータスと、利用可能なアップデートがある場合は結果の詳細を保持します。
  - status
    
    RequestUpdateCheckStatus
    
    更新チェックの結果。
  - version
    
    文字列省略可
    
    アップデートが利用可能な場合は、利用可能なアップデートのバージョンが含まれます。

戻り値

Promise<object>

Chrome 109 以降

Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

restart()

chrome.runtime.restart()

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

restartAfterDelay()

Promise Chrome 53 以降

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

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

パラメータ

秒

数値

デバイスを再起動するまでの待機時間（秒単位）。-1 にすると、スケジュール設定された再起動がキャンセルされます。
callback

function 省略可

callback パラメータは次のようになります。
```
() => void
```

戻り値

Promise<void>

Chrome 99 以降

Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

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

function 省略可

Chrome 99 以降

callback パラメータは次のようになります。
```
(response: any) => void
```
- レスポンス
  
  任意
  
  メッセージのハンドラから送信された JSON レスポンスオブジェクト。拡張機能への接続中にエラーが発生した場合、コールバックは引数なしで呼び出され、runtime.lastError がエラーメッセージに設定されます。

戻り値

Promise<any>

Chrome 99 以降

Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

sendNativeMessage()

Promise

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

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

パラメータ

アプリケーション

文字列

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

オブジェクト

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

function 省略可

Chrome 99 以降

callback パラメータは次のようになります。
```
(response: any) => void
```
- レスポンス
  
  任意
  
  ネイティブメッセージングホストから送信されたレスポンスメッセージ。ネイティブメッセージホストへの接続中にエラーが発生した場合、コールバックは引数なしで呼び出され、runtime.lastError がエラーメッセージに設定されます。

戻り値

Promise<any>

Chrome 99 以降

Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

setUninstallURL()

Promise

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

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

パラメータ

URL

文字列

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

function 省略可

Chrome 45 以降

callback パラメータは次のようになります。
```
() => void
```

戻り値

Promise<void>

Chrome 99 以降

Promise は Manifest V3 以降でサポートされていますが、下位互換性を確保するためにコールバックが用意されています。同じ関数呼び出しで両方を使用することはできません。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" 権限が必要です。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」の場合にのみ存在します。
  - reason
    
    OnInstalledReason
    
    このイベントがディスパッチされる理由。

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 キオスクアプリでのみ発生します。

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(reason: OnRestartRequiredReason) => void
```
- reason
  
  OnRestartRequiredReason

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

chrome.runtime

説明

コンセプトと使用方法

展開されていない拡張機能の動作

ユースケース

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

コンテンツ スクリプトからサービス ワーカーにデータを送信する

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

例

型

ContextFilter

プロパティ

ContextType

列挙型

ExtensionContext

プロパティ

MessageSender

プロパティ

OnInstalledReason

列挙型

OnRestartRequiredReason

列挙型

PlatformArch

列挙型

PlatformInfo

プロパティ

PlatformNaclArch

列挙型

PlatformOs

列挙型

Port

プロパティ

RequestUpdateCheckStatus

列挙型

プロパティ

id

タイプ

lastError

タイプ

プロパティ

メソッド

connect()

パラメータ

戻り値

connectNative()

パラメータ

戻り値

getBackgroundPage()

パラメータ

戻り値

getContexts()

パラメータ

戻り値

getManifest()

戻り値

getPackageDirectoryEntry()

パラメータ

戻り値

getPlatformInfo()

パラメータ

戻り値

getURL()

パラメータ

戻り値

openOptionsPage()

パラメータ

戻り値

reload()

requestUpdateCheck()

パラメータ

戻り値

restart()

restartAfterDelay()

パラメータ

戻り値

sendMessage()

パラメータ

戻り値

sendNativeMessage()

パラメータ

コンテンツスクリプトからサービスワーカーにデータを送信する