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

chrome.runtime

説明

chrome.runtime API を使用して Service Worker を取得し、マニフェストに関する詳細情報を返して、拡張機能のライフサイクルでイベントをリッスンして応答します。この 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() があります。

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

パッケージ化されていない拡張機能が再読み込みされると、アップデートとして扱われます。つまり、chrome.runtime.onInstalled イベントが "update" を理由に呼び出されます。これには、chrome.runtime.reload() で拡張機能を再読み込みする場合も含まれます。

使用例

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

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

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

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 にデータを送信する

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

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

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 - ウェブからアクセス可能なリソースのデモをご覧ください。

型

ContextFilter

Chrome 114 以降

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

Properties

contextIds

string[] 省略可
contextTypes

ContextType[] 省略可
documentIds

string[] 省略可
documentOrigins

string[] 省略可
documentUrls

string[] 省略可
frameIds

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

ブール値（省略可）
tabIds

number[] 省略可
windowIds

number[] 省略可

ContextType

Chrome 114 以降

列挙型

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

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

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

"OFFSCREEN_DOCUMENT"
コンテキストタイプを画面外ドキュメントとして指定します。

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

ExtensionContext

Chrome 114 以降

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

Properties

contextId

string

このコンテキストの一意の識別子
contextType

ContextType

対応するコンテキストのタイプ。
documentId

string（省略可）

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

string（省略可）

このコンテキストに関連付けられているドキュメントの提供元。コンテキストがドキュメント内でホストされていない場合は未定義になります。
documentUrl

string（省略可）

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

数値

このコンテキストのフレームの ID。このコンテキストがフレーム内にホストされていない場合は -1。
シークレットモード

boolean

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

数値

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

数値

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

MessageSender

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

Properties

documentId

string（省略可）

Chrome 106 以降

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

string（省略可）

Chrome 106 以降

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

number（省略可）

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

string（省略可）

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

string（省略可）

Chrome 74 以降

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

string（省略可）

Chrome 80 以降

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

タブ（省略可）

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

string（省略可）

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

string（省略可）

接続を開始したページまたはフレームの 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

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

Properties

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

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

Properties

name

string

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

イベント<functionvoidvoid>

ポートが相手側から切断されたときに呼び出されます。エラーによってポートが接続解除された場合、runtime.lastError が設定されることがあります。切断によってポートが閉じられた場合、このイベントは相手側でのみ発生します。このイベントは最大 1 回発生します（ポートの存続期間もご覧ください）。

onDisconnect.addListener 関数は次のようになります。
```
(callback: function)=> {...}
```
- callback
  
  機能
  
  callback パラメータは次のようになります。
```
(port: Port)=>void
```
  - ポート
    
    ポート
onMessage

イベント<functionvoidvoid>

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

onMessage.addListener 関数は次のようになります。
```
(callback: function)=> {...}
```
- callback
  
  機能
  
  callback パラメータは次のようになります。
```
(message: any,port: Port)=>void
```
  - message
    
    任意
  - ポート
    
    ポート
sender

MessageSender 省略可

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

void

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

disconnect 関数は次のようになります。
```
()=> {...}
```
postMessage

void

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

postMessage 関数は次のようになります。
```
(message: any)=> {...}
```
- message
  
  任意
  
  Chrome 52 以降
  
  送信するメッセージ。このオブジェクトは JSON に変換できる必要があります。

RequestUpdateCheckStatus

Chrome 44 以降

更新チェックの結果。

列挙型

"throttled"
ステータスチェックが抑制されていることを指定します。これは、短期間に繰り返し確認した後に発生することがあります。

"no_update"
インストールできるアップデートがないことを示します。

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

Properties

id

拡張機能またはアプリの ID。

タイプ

string

lastError

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

タイプ

オブジェクト

Properties

message

string（省略可）

発生したエラーの詳細。

Methods

connect()

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

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

パラメータ

extensionId

string（省略可）

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

オブジェクト省略可
- includeTlsChannelId
  
  ブール値（省略可）
  
  接続イベントをリッスンしているプロセスの onConnectExternal に TLS チャネル ID を渡すかどうか。
- name
  
  string（省略可）
  
  接続イベントをリッスンしているプロセスの onConnect に渡されます。

戻り値

ポート

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

パラメータ

アプリケーション

string

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

戻り値

ポート

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

getBackgroundPage()

Promise フォアグラウンドのみ

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

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

パラメータ

callback

関数（省略可）

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

戻り値

Promise<ウィンドウ|未定義>

Chrome 99 以降

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

getContexts()

Promise Chrome 116 以降 MV3 以降

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

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

パラメータ

フィルタ

ContextFilter

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

関数（省略可）

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

戻り値

Promise<ExtensionContext[]>

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

getManifest()

chrome.runtime.getManifest()

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

戻り値

オブジェクト

マニフェストの詳細。

getPackageDirectoryEntry()

Promise フォアグラウンドのみ

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

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

パラメータ

callback

関数（省略可）

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

戻り値

Promise<DirectoryEntry>

Chrome 122 以降

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

getPlatformInfo()

Promise

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

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

パラメータ

callback

関数（省略可）

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

戻り値

Promise<PlatformInfo>

Chrome 99 以降

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

getURL()

chrome.runtime.getURL(
  path: string,
)

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

パラメータ

パス

string

アプリや拡張機能のインストールディレクトリからの相対パスで表される、アプリ/拡張機能内のリソースへのパス。

戻り値

string

リソースの完全修飾 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 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

Promise

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

このアプリまたは拡張機能の即時アップデートの確認をリクエストします。

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

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

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

パラメータ

callback

関数（省略可）

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

戻り値

Promise<object>

Chrome 109 以降

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

restart()

chrome.runtime.restart()

アプリをキオスクモードで実行したら、ChromeOS デバイスを再起動します。そうでなければ、オペレーションは実行されません。

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 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

sendMessage()

Promise

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

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

パラメータ

extensionId

string（省略可）

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

任意

送信するメッセージ。このメッセージは、JSON に変換可能なオブジェクトである必要があります。
オプション

オブジェクト省略可
- includeTlsChannelId
  
  ブール値（省略可）
  
  接続イベントをリッスンしているプロセスの onMessageExternal に TLS チャネル ID を渡すかどうか。
callback

関数（省略可）

Chrome 99 以降

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

戻り値

Promise<任意>

Chrome 99 以降

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

sendNativeMessage()

Promise

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

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

パラメータ

アプリケーション

string

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

オブジェクト

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

関数（省略可）

Chrome 99 以降

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

戻り値

Promise<任意>

Chrome 99 以降

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

setUninstallURL()

Promise

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

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

パラメータ

URL

string

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

関数（省略可）

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" 権限が必要です。Chrome OS でのみサポートされています。

パラメータ

callback

機能

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

onInstalled

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

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

パラメータ

callback

機能

callback パラメータは次のようになります。
```
(details: object)=>void
```
- 詳細
  
  オブジェクト
  - id
    
    string（省略可）
    
    更新されたインポート済み共有モジュール拡張機能の ID を示します。'reason' が 'shared_module_update' の場合にのみ存在します。
  - previousVersion
    
    string（省略可）
    
    更新されたばかりの拡張機能の以前のバージョンを示します。これは、「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
```
- message
  
  任意
- 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
```
- message
  
  任意
- sender
  
  MessageSender
- sendResponse
  
  機能
  
  sendResponse パラメータは次のようになります。
```
()=>void
```
- 戻り値
  boolean|undefined

onRestartRequired

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

アプリ、またはアプリが実行されるデバイスの再起動が必要になったときに呼び出されます。アプリは、再起動が行われるのに都合の良いタイミングですべてのウィンドウを閉じる必要があります。アプリが何もしなかった場合は、24 時間の猶予期間が過ぎると再起動が行われます。現在、このイベントは Chrome OS キオスクアプリでのみ発生します。

パラメータ

callback

機能

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

onStartup

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

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

パラメータ

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
```
- 詳細
  
  オブジェクト
  - バージョン
    
    string
    
    利用可能なアップデートのバージョン番号。

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
```
- message
  
  任意
- sender
  
  MessageSender
- sendResponse
  
  機能
  
  sendResponse パラメータは次のようになります。
```
()=>void
```
- 戻り値
  boolean|undefined

chrome.runtime

説明

コンセプトと使用方法

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

使用例

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

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

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

例

型

ContextFilter

Properties

ContextType

列挙型

ExtensionContext

Properties

MessageSender

Properties

OnInstalledReason

列挙型

OnRestartRequiredReason

列挙型

PlatformArch

列挙型

PlatformInfo

Properties

PlatformNaclArch

列挙型

PlatformOs

列挙型

Port

Properties

RequestUpdateCheckStatus

列挙型

Properties

id

タイプ

lastError

タイプ

Properties

Methods

connect()

パラメータ

戻り値

connectNative()

パラメータ

戻り値

getBackgroundPage()

パラメータ

戻り値

getContexts()

パラメータ

戻り値

getManifest()

戻り値

getPackageDirectoryEntry()

パラメータ

戻り値

getPlatformInfo()

パラメータ

戻り値

getURL()

パラメータ

戻り値

openOptionsPage()

パラメータ

戻り値

reload()

requestUpdateCheck()

パラメータ

戻り値

restart()

restartAfterDelay()

パラメータ

戻り値

sendMessage()

パラメータ

戻り値

sendNativeMessage()

パラメータ

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