Contents

Native Messaging

Extensions and apps can exchange messages with native applications using an API
that is similar to the other message passing APIs.
Native applications that support this feature must register a
native messaging host that knows how to communicate with the extension.
Chrome starts the host in a 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 that defines the native messaging host configuration. Below is an
example of the manifest file:

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

Name

Description

name

Name of the native messaging host. Clients pass this string to
runtime.connectNative or runtime.sendNativeMessage.
This name can only contain lowercase alphanumeric characters, underscores
and dots. The name cannot start or end with a dot, and a dot cannot be
followed by another dot.

description

Short application description.

path

Path to the native messaging host binary. On Linux and OSX the path must
be absolute. On Windows it can be relative to the directory in which the
manifest file is located. The host process is started with the current
directory set to the directory that contains the host binary. For example if
this parameter is set to C:\Application\nm_host.exe then it
will be started with current directory C:\Application\.

type

Type of the interface used to communicate with the native messaging
host. Currently there is only one possible value for this parameter:
stdio. It indicates that Chrome should use stdin
and stdout to communicate with the host.

allowed_origins

List of extensions that should have access to the native messaging host.
Wildcards such as chrome-extension://*/* are not
allowed.

Native messaging host location

The location of the manifest file depends on the platform.

On Windows, the manifest file can be located anywhere in the file system.
The application installer must create registry key
HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application
or
HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application,
and set default value of that key to the full path to the manifest file.
For example, using the following command:

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

On OS X and Linux, the location of the native messaging host's
manifest file varies by the browser (Google Chrome or Chromium).
The system-wide native messaging hosts are looked up at a fixed location,
while the user-level native messaging hosts are looked up in a subdirectory within the
user profile directory
called NativeMessagingHosts.

Native messaging protocol

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

The first argument to the native messaging host is the origin of the caller,
usually chrome-extension://[ID of whitelisted extension].
This allows native messaging hosts to identify the source of the message when
multiple extensions are specified in the allowed_origins key in the
native messaging host manifest.
Warning: In Windows, in Chrome 54 and earlier, the origin was
passed as the second parameter instead of the first parameter.

When a messaging port is created using runtime.connectNative Chrome
starts native messaging host process and keeps it running until the port is
destroyed. On the other hand, when a message is sent using
runtime.sendNativeMessage, without creating a messaging port, Chrome starts
a new native messaging host process for each message. In that case the first
message generated by the host process is handled as a response to the original
request, i.e. Chrome will pass it to the response callback specified when
runtime.sendNativeMessage is called. All other messages generated by the
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 the calling chrome native window: --parent-window=&ltdecimal
handle value&gt. This lets the native messaging host create native UI
windows that are correctly focused.

The Following example creates a runtime.Port object that's connected to native
messaging host com.my_company.my_application, starts listening for
messages from that port and sends one outgoing message:

Debugging native messaging

When the native messaging host fails to start, writes to stderr or
when it violates the communication protocol, output is written to the error log
of Chrome.
On Linux and OS X, this log can easily be accessed by starting Chrome from the
command line and watching its output in the terminal.
On Windows, use --enable-logging as explained at
How 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 be followed 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 most likely 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 file in the correct format? In particular, is the JSON
syntax correct and do the values match the definition of a
native messaging host manifest?

Does the file specified in path exist? On Windows, paths
may be relative, but on OS X and Linux, the paths must be absolute.

Native messaging host host name is not registered. (Windows-only)

The native messaging host was not found in the Windows registry. Double-check
using regedit whether the key was really created and matches the
required format as documented at
native messaging host location.

Access to the specified native messaging host is forbidden.

Is the extension's origin listed in allowed_origins?

Error when communicating with the native messaging host.

This is a very common error and indicates an incorrect implementation of
the communication protocol in the native messaging host.

Make sure that all output in stdout adheres to the
native messaging protocol.
If you want to print some data for debugging purposes,
write to stderr.

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 to
O_BINARY. By default, the I/O mode is O_TEXT,
which corrupts the message format as line breaks (\n =
0A) are replaced with Windows-style line endings
(\r\n = 0D 0A). The I/O mode can be set using
__setmode.

Examples

The examples/api/nativeMessaging
directory contains an example application that uses native messaging to
communicate with a Python script that serves as a native messaging host.
The sample host's directory also contains scripts to install/remove the native
messaging host.

To try out the example, first download and extract the
sample app
and
sample host.
Run install_host.bat (Windows) or
install_host.sh (Linux / OS X) to install the native messaging
host.
Then load the app and interact with the app.
Run uninstall_host.bat or uninstall_host.sh to
unregister the native messaging host when you are done.