Native messaging

Native messaging enables a WebExtension to exchange messages with a native application installed on the user's computer. This enables native applications to provide a service to add-ons without needing to be reachable over the web. One common example here is password managers: the native application manages storage and encryption of passwords, and communicates with the add-on to populate web forms. Native messaging also enables add-ons to access resources that are not accessible through WebExtension APIs, such as some particular piece of hardware.

The native application is not installed or managed by the browser: it's installed using the underlying operating system's installation machinery. Along with the native application itself, you'll need to provide a JSON file called the "host manifest" or "app manifest", and install it in a defined location on the user's computer. The app manifest file describes how the browser can connect to the native application.

The WebExtension must request the "nativeMessaging" permission in its manifest.json file. Conversely, the native application must grant permission for the WebExtension by including its ID in the "allowed_extensions" field of the app manifest.

After that the WebExtension can exchange JSON messages with the native application using a set of functions in the runtime API. On the native app side, messages are received using standard input (stdin) and sent using standard output (stdout).

Support for native messaging in WebExtensions is mostly compatible with Chrome, with two main differences:

• The app manifest lists "allowed_extensions" as an array of app IDs, while Chrome lists "allowed_origins", as an array of "chrome-extension" URLs.
• The app manifest is stored in a different location, compared to Chrome.

There's a complete example in the "native-messaging" directory of the "webextensions-examples" repository on GitHub. Most of the sample code in this article is taken directly from that example.

Setup

Add-on manifest

If you want your WebExtension to communicate with a native application, then:

• You must set the "nativeMessaging" permission in its manifest.json file.
• You should probably specify your add-on ID explicitly, using the applications manifest key (This is because the app's manifest will identify the set of WebExtensions that are allowed to connect to it by listing their IDs).

Here's an example manifest.json file:

{

  "description": "Native messaging example add-on",
  "manifest_version": 2,
  "name": "Native messaging example",
  "version": "1.0",
  "icons": {
    "48": "icons/message.svg"
  },

  "applications": {
    "gecko": {
      "id": "[email protected]",
      "strict_min_version": "50.0"
    }
  },

  "background": {
    "scripts": ["background.js"]
  },

  "browser_action": {
    "default_icon": "icons/message.svg"
  },
 
  "permissions": ["nativeMessaging"]

}

App manifest

The app manifest describes to the browser how it can connect to the native application.

The app manifest file must be installed along with the native application. That is, the browser reads and validates app manifest files but it does not install or manage them. Thus the security model for when and how these files are installed and updated is much more like that for native applications than that for WebExtensions.

The app manifest contains a single JSON object with the following properties:

For example, here's a manifest for the "ping_pong" native application:

{
  "name": "ping_pong",
  "description": "Example host for native messaging",
  "path": "/path/to/native-messaging/app/ping_pong.py",
  "type": "stdio",
  "allowed_extensions": [ "[email protected]" ]
}

This allows the WebExtension whose ID is "[email protected]" to connect, by passing the name "ping_pong" into the relevant runtime API function. The application itself is at "/path/to/native-messaging/app/ping_pong.py".

{
  "name": "ping_pong",
  "description": "Example host for native messaging",
  "path": "c:\\path\\to\\native-messaging\\app\\ping_pong_win.bat",
  "type": "stdio",
  "allowed_extensions": [ "[email protected]" ]
}

@echo off

python "c:\path\to\native-messaging\app\ping_pong.py"

App manifest location

The app manifest needs to be stored in a known location on the user's computer, so the browser knows where to find it. This location is different for different operating systems, and different depending on whether the app should be made available globally or only to a single user.

In all the options below, "<name>" is the value of "name" in the manifest: so, "ping_pong" in the example above.

Windows

For global visibility, create a registry key with the following name:

HKEY_LOCAL_MACHINE\SOFTWARE\Mozilla\NativeMessagingHosts\<name>

The key should have a single default value, which is the path to the manifest.

Note that this key should not be created under Wow6432Node, even if the app is 32-bit. The browser will always look for the key under the "native" view of the registry, not the 32-bit emulation.

For per-user visibility, create a registry key with the following name:

HKEY_CURRENT_USER\SOFTWARE\Mozilla\NativeMessagingHosts\<name>

The key should have a single default value, which is the path to the manifest.

For example, if the native application's name is "ping_pong" and its app manifest is at "C:\path\to\ping_pong.json", then you could add the key using the following REG ADD command:

REG ADD "HKEY_CURRENT_USER\SOFTWARE\Mozilla\NativeMessagingHosts\ping_pong" /ve /d "C:\path\to\ping_pong.json" /f

Mac OS X

For global visibility, store the manifest in:

/Library/Application Support/Mozilla/NativeMessagingHosts/<name>.json

For per-user visibility, store the manifest in:

~/Library/Application Support/Mozilla/NativeMessagingHosts/<name>.json

Linux

For global visibility, store the manifest in any of:

/usr/lib/mozilla/native-messaging-hosts/<name>.json

/usr/lib64/mozilla/native-messaging-hosts/<name>.json

/usr/share/mozilla/native-messaging-hosts/<name>.json

For per-user visibility, store the manifest in:

~/.mozilla/native-messaging-hosts/<name>.json

Exchanging messages

Given the above setup, a WebExtension can exchange JSON messages with a native application.

Add-on side

If you've used the messaging APIs to communicate with content scripts, this should look very familiar. There are two patterns: connection-based messaging and connectionless messaging.

Connection-based messaging

With this pattern you call runtime.connectNative(), passing the name of the application (the value of the "name" property in the app's manifest). This launches the application if it is not already running and returns a runtime.Port object to the WebExtension. The application stays running until the WebExtension calls Port.disconnect() or the page that connected to it is closed.

To send messages using Port, call its postMessage() function, passing the JSON message to send. To listen for messages using Port, add the listener using its onMessage.addListener() function.

Here's an example background script that establishes a connection with the "ping_pong" app, listens for messages from it, then sends it a "ping" message whenever the user clicks the browser action:

/*
On startup, connect to the "ping_pong" app.
*/
var port = browser.runtime.connectNative("ping_pong");

/*
Listen for messages from the app.
*/
port.onMessage.addListener((response) => {
  console.log("Received: " + response);
});

/*
On a click on the browser action, send the app a message.
*/
browser.browserAction.onClicked.addListener(() => {
  console.log("Sending:  ping");
  port.postMessage("ping");
});

Connectionless messaging

With this pattern you call runtime.sendNativeMessage(), passing it:

• the name of the application
• the JSON message to send
• optionally, a callback.

A new instance of the app is created for each message. The first message sent by the app is treated as a response to the sendNativeMessage() call, and will be passed into the callback.

Here's the example above, rewritten to use runtime.sendNativeMessage():

function onResponse(response) {
  console.log("Received " + response);
}

/*
On a click on the browser action, send the app a message.
*/
browser.browserAction.onClicked.addListener(() => {
  console.log("Sending:  ping");
  chrome.runtime.sendNativeMessage(
    "ping_pong",
    "ping",
    onResponse);
});

App side

On the application side, you use standard input to receive messages and standard output to send them.

Each message is serialized using JSON, UTF-8 encoded and is preceded with a 32-bit value containing the message length in native byte order.

The maximum size of a single message from the application is 1 MB. The maximum size of a message sent to the application is 4 GB.

Here's an example written in Python. It listens for messages from the add-on. If the message is "ping", then it responds with a message "pong":

#!/usr/bin/env python

import sys, json, struct

# Read a message from stdin and decode it.
def getMessage():
  rawLength = sys.stdin.read(4)
  if len(rawLength) == 0:
      sys.exit(0)
  messageLength = struct.unpack('@I', rawLength)[0]
  message = sys.stdin.read(messageLength)
  return json.loads(message)

# Encode a message for transmission, given its content.
def encodeMessage(messageContent):
  encodedContent = json.dumps(messageContent)
  encodedLength = struct.pack('@I', len(encodedContent))
  return {'length': encodedLength, 'content': encodedContent}

# Send an encoded message to stdout.
def sendMessage(encodedMessage):
  sys.stdout.write(encodedMessage['length'])
  sys.stdout.write(encodedMessage['content'])
  sys.stdout.flush()

while True:
  receivedMessage = getMessage()
  if (receivedMessage == "ping"):
    sendMessage(encodeMessage("pong"))

Closing the native app

If you connected to the native application using runtime.connectNative(), then it stays running until the WebExtension calls Port.disconnect() or the page that connected to it is closed. If you started the native application by sending runtime.sendNativeMessage(), then it is closed after it has received the message and sent a response.

To close the native application:

• On *nix systems like OS X and Linux, the browser sends SIGTERM to the native application, then SIGKILL after the application has had a chance to exit gracefully. These signals propagate to any subprocesses unless they break away into a new process group.
• On Windows, the browser puts the native application's process into a Job object, and kills the job. If the native application launches any additional processes and wants them to remain open after the native application itself is killed, then the native application must launch the additional process with the CREATE_BREAKAWAY_FROM_JOB flag.

Troubleshooting

If something goes wrong, check the browser console. If the native application sends any output to stderr, the browser will redirect it to the browser console. So if you've got as far as launching the native application, you will see any error messages it emits.

If you haven't managed to run the application, you should see an error message giving you a clue about the problem.

"No such native application <name>"

•  Check that the name passed to runtime.connectNative() matches the name in the app manifest
• OS X/Linux: check that name of the app manifest is <name>.json.
• Windows: check that the registry key is in the correct place, and that its name matches the name in the app manifest.
• Windows: check that the path given in the registry key points to the app manifest.

"Error: Invalid application <name>"

• Check that the application's name contains no invalid characters.

"'python' is not recognized as an internal or external command, ..."

• Windows: if your application is a Python script, check that you have Python installed and have your path set up for it.

"File at path <path> does not exist, or is not executable"

• If you see this, then the app manifest has been found successfully.
• Check that the "path" in the app's manifest is correct.
• Windows: check that you've escaped the path separators ("c:\\path\\to\\file").
• Check that the app is at the location pointed to by the "path" property in the app's manifest.
• Check that the app is executable.

"This extension does not have permission to use native application <name>"

• Check that the "allowed_extensions" key in the app manifest contains the add-on's ID.

"TypeError: browser.runtime.connectNative is not a function"

• Check that the add-on has the "nativeMessaging" permission

"[object Object]       NativeMessaging.jsm:218"

• There was a problem starting the application.