Extensions and apps can exchange messages with native applications using an API that is similar tothe othermessage passing APIs. Native applications that support this feature must register anative messaging host that knows how to communicate with the extension. Chrome starts the host ina separate process and communicates with it using standard input and standard output streams.

Native messaging host

In order to register a native messaging host the application must install a manifest file thatdefines the native messaging host configuration. Below is an example of the manifest file:

{"name":"com.my_company.my_application","description":"My Application","path":"C:\\Program Files\\My Application\\chrome_native_messaging_host.exe","type":"stdio","allowed_origins":["chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"]}

The native messaging host manifest file must be valid JSON and contains the following fields:

Native messaging host location

The location of the manifest file depends on the platform.

OnWindows, the manifest file can be located anywhere in the file system. The applicationinstaller must create registry keyHKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ orHKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_, andset default value of that key to the full path to the manifest file. For example, using thefollowing command:

REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f

or using the following.reg file:

Windows Registry Editor Version 5.00[HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application]@="C:\\path\\to\\nmh-manifest.json"

When Chrome looks for native messaging hosts, first the 32-bit registry is queried, then the 64-bitregistry.

OnOS X andLinux, the location of the native messaging host's manifest file varies by thebrowser (Google Chrome or Chromium). The system-wide native messaging hosts are looked up at a fixedlocation, while the user-level native messaging hosts are looked up in a subdirectory within theuser profile directory calledNativeMessagingHosts.

• OS X (system-wide)
  • Google Chrome:/Library/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
  • Chromium:/Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
• OS X (user-specific,default path)
  • Google Chrome:~/Library/Application Support/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
  • Chromium:~/Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
• Linux (system-wide)
  • Google Chrome:/etc/opt/chrome/native-messaging-hosts/_com.my_company.my_application_.json
  • Chromium:/etc/chromium/native-messaging-hosts/_com.my_company.my_application_.json
• Linux (user-specific,default path)
  • Google Chrome:~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
  • Chromium:~/.config/chromium/NativeMessagingHosts/_com.my_company.my_application_.json

Native messaging protocol

Chrome starts each native messaging host in a separate process and communicates with it usingstandard input (stdin) and standard output (stdout). The same format is used to send messages inboth directions: each message is serialized using JSON, UTF-8 encoded and is preceded with 32-bitmessage length in native byte order. The maximum size of a single message from the native messaginghost is 1 MB, mainly to protect Chrome from misbehaving native applications. The maximum size of themessage sent to the native messaging host is 4 GB.

The first argument to the native messaging host is the origin of the caller, usuallychrome-extension://[ID of allowed extension]. This allows native messaging hosts to identify thesource of the message when multiple extensions are specified in theallowed_origins key in thenative messaging host manifest.Warning: In Windows, in Chrome 54 and earlier, the origin was passed as the second parameterinstead of the first parameter.

When a messaging port is created usingruntime.connectNative Chrome starts native messaginghost process and keeps it running until the port is destroyed. On the other hand, when a message issent usingruntime.sendNativeMessage, without creating a messaging port, Chrome starts a newnative messaging host process for each message. In that case the first message generated by the hostprocess is handled as a response to the original request, i.e. Chrome will pass it to the responsecallback specified whenruntime.sendNativeMessage is called. All other messages generated bythe native messaging host in that case are ignored.

On Windows, the native messaging host is also passed a command line argument with a handle to thecalling Chrome native window:--parent-window=<decimal handle value>. This lets the nativemessaging host create native UI windows that are correctly parented. Note that this value will be0 if the calling context is a background script page.

Connecting to a native application

Sending and receiving messages to and from a native application is very similar to cross-extensionmessaging. The main difference is thatruntime.connectNative is used instead ofruntime.connect, andruntime.sendNativeMessage is used instead ofruntime.sendMessage.These methods can only be used if the "nativeMessaging" permission isdeclared in your app'smanifest file.

The Following example creates aruntime.Port object that's connected to native messaging hostcom.my_company.my_application, starts listening for messages from that port and sends one outgoingmessage:

varport=chrome.runtime.connectNative('com.my_company.my_application');port.onMessage.addListener(function(msg){console.log("Received"+msg);});port.onDisconnect.addListener(function(){console.log("Disconnected");});port.postMessage({text:"Hello, my_application"});

runtime.sendNativeMessage can be used to send a message to native application without creatinga port, e.g.:

chrome.runtime.sendNativeMessage('com.my_company.my_application',{text:"Hello"},function(response){console.log("Received "+response);});

Debugging native messaging

When the native messaging host fails to start, writes tostderr or when it violates thecommunication protocol, output is written to the error log of Chrome. On Linux and OS X, this logcan easily be accessed by starting Chrome from the command line and watching its output in theterminal. On Windows, use--enable-logging as explained atHow to enable logging.

Here are some errors and tips for solving the issues:

• Failed to start native messaging host.
  • Check whether you have sufficient permissions to execute the file.
• Invalid native messaging host name specified.
  • Check whether the name contains any invalid characters. Only lowercase alphanumeric characters,underscores and dots are allowed. A name cannot start or end with a dot, and a dot cannot befollowed by another dot.
• Native host has exited.
  • The pipe to the native messaging host was broken before the message was read by Chrome. This is mostlikely initiated from your native messaging host.
• Specified native messaging host not found.
  • Is the name spelled correctly in the extension and in the manifest file?
  • Is the manifest put in the right directory and with the correct name? Seenative messaging hostlocation for the expected formats.
  • Is the manifest file in the correct format? In particular, is the JSON syntax correct and do thevalues match the definition of anative messaging host manifest?
  • Does the file specified inpath exist? On Windows, paths may be relative, but on OS X and Linux,the paths must be absolute.
• Native messaging hosthost name is not registered. (Windows-only)
  • The native messaging host was not found in the Windows registry. Double-check usingregeditwhether the key was really created and matches the required format as documented atnativemessaging host location.
• Access to the specified native messaging host is forbidden.
  • Is the extension's origin listed inallowed_origins?
• Error when communicating with the native messaging host.
  • This is a very common error and indicates an incorrect implementation of the communication protocolin the native messaging host.
  • Make sure that all output instdout adheres to thenative messaging protocol. If you wantto print some data for debugging purposes, write tostderr.
  • Make sure that the 32-bit message length is in the platform's native integer format (little-endian/ big-endian).
  • The message length must not exceed 1024*1024.
  • The message size must be equal to the number of bytes in the message. This may differ from the"length" of a string, because characters may be represented by multiple bytes.
  • Windows-only: Make sure that the program's I/O mode is set toO_BINARY. By default, the I/Omode isO_TEXT, which corrupts the message format as line breaks (\n =0A) are replaced withWindows-style line endings (\r\n =0D 0A). The I/O mode can be set using__setmode.