Native messaging

To communicate with a native Win32 app that's installed on a user's device, an extension uses the message-passing APIs. The native app host sends and receives messages with extensions using standard input and standard output.

Extensions that use native messaging are installed in Microsoft Edge similar to any other extension. However, native apps aren't installed or managed by Microsoft Edge.

To acquire the extension and native app host, there are two different distribution models:

  • Package your extension and the host together. When a user installs the package, both the extension and the host are installed.

  • Or, install your extension using the Microsoft Edge Add-ons website, and your extension prompts users to install the host.

To create your extension to send and receive messages with native app hosts, do the following steps.

Step 1 - Add permissions to the extension manifest

Add the nativeMessaging permission to the manifest.json file of the extension.

The following is an example manifest.json file:

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 2,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

Step 2 - Create your native messaging host manifest file

Native apps must provide a native messaging host manifest file. The manifest file contains the following information:

  • The path to the native messaging host runtime.

  • The method of communication with the extension.

  • A list of allowed extensions to which it communicates.

The browser reads and validates the native messaging host manifest. The browser doesn't install or manage the native messaging host manifest file.

Example of a native messaging host manifest file:

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

The host manifest file must be a valid JSON file that contains the following keys:

Key Details
name Specifies the name of the native messaging host. Clients pass the string to runtime.connectNative or runtime.sendNativeMessage.
The value must only contain lowercase alphanumeric characters, underscores, and dots.
The value must not start or end with a dot, and a dot must not be followed by another dot.
description Describes the app.
path Specifies the path to the native messaging host binary.
On Windows devices, you can use relative paths to the directory that contains the manifest file.
On macOS and Linux, the path must be absolute.
The host process starts with the current directory set to the directory that contains the host binary. For example (Windows), if the parameter is set to C:\App\nm_host.exe, the binary is started using the current directory (C:\App\).
type Specifies the type of the interface used to communicate with the native messaging host. The value instructs Microsoft Edge to use stdin and stdout to communicate with the host. The only acceptable value is stdio.
allowed_origins Specifies the list of extensions that have access to the native messaging host. To turn on your app to identify and communicate with an extension, in your native messaging host manifest file, set the following value:
"allowed_origins": ["chrome-extension://{microsoft_catalog_extension_id}"]

Sideload your extension to test native messaging with the host. To sideload your extension during development and retrieve microsoft_catalog_extension_id:

  1. Go to edge://extensions, and then turn on the Developer mode toggle button.

  2. Select Load unpacked, and then select your extension package to sideload.

  3. Click OK.

  4. Go to the edge://extensions page and verify that your extension is listed.

  5. Copy the key from microsoft_catalog_extension_id (ID) from the extension listing on the page.

When you're ready to distribute your extension to users, publish your extension to the Microsoft Edge Add-ons website. The extension ID of the published extension might differ from the ID that's used while sideloading your extension. If the ID changed, update allowed_origins in the host manifest file with the ID of your published extension.

Step 3 - Copy the native messaging host manifest file to your system

The final step involves copying the native messaging host manifest file to your computer, and ensuring the manifest file is correctly configured. To ensure your manifest file is placed in the expected location, do the following steps. The location varies by platform.

Note

Make sure that you provide read permissions on the manifest file, and run permissions on the host runtime.

The manifest file may be located anywhere in the file system. The app installer must create a registry key and set the default value of the key to the full path of the manifest file. The following locations are examples of registry keys:

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

To add a registry key to the directory with the manifest key, do either of the following:

  • Run a command in the command prompt:

    REG ADD "HKCU\Software\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f
    
  • Or, create a .reg file and run it, as follows:

    1. Copy the following command into a .reg file:

      Windows Registry Editor Version 5.00
      [HKEY_CURRENT_USER\Software\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app]
      @="C:\\path\\to\\nmh-manifest.json"
      
    2. Run the .reg file. If you run your created .reg file as part of a batch script, make sure you run it using an administrator command prompt.

Microsoft Edge queries the HKEY_CURRENT_USER root key, followed by HKEY_LOCAL_MACHINE. In both of the keys, the 32-bit registry is searched first, and then the 64-bit registry is searched to identify native messaging hosts. The registry key specifies the location of the native messaging host manifest.

If the registry entries for Microsoft Edge don't have the location of the host manifest, the Chromium and Chrome registry locations are used as fallback options.

If Microsoft Edge finds the registry key at any of the previously listed locations, it doesn't query the locations that are listed in the following code snippet.

The search order for the registry locations is:

HKEY_CURRENT_USER\SOFTWARE\WOW6432Node\Microsoft\Edge\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\WOW6432Node\Chromium\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\WOW6432Node\Google\Chrome\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Google\Chrome\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\

Note

If you have extensions on the Microsoft Edge Add-ons and the Chrome Webstore, you must add the extension IDs corresponding to both the stores in the allowed_origins of the host manifest file because only the host manifest corresponding to the first registry location found is read.

Note

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons Attribution 4.0 International License. The original page is found here.

Creative Commons License. This work is licensed under a Creative Commons Attribution 4.0 International License.