Mensajería nativa

Las extensiones y apps pueden intercambiar mensajes con aplicaciones nativas mediante una API similar a las otras APIs de paso de mensajes. Las aplicaciones nativas que admiten esta función deben registrar un host de mensajería nativa que sepa cómo comunicarse con la extensión. Chrome inicia el host en un proceso separado y se comunica con él mediante flujos de entrada y salida estándar.

Host de mensajería nativa

Para registrar un host de mensajería nativa, la aplicación debe instalar un archivo de manifiesto que defina la configuración del host de mensajería nativa. A continuación, se muestra un ejemplo del archivo de manifiesto:

{
  "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/"
  ]
}

El archivo de manifiesto del host de mensajería nativa debe tener un formato JSON válido y contener los siguientes campos:

NombreDescripción
nameNombre del host de mensajería nativa. Los clientes pasan esta string a runtime.connectNative o runtime.sendNativeMessage. Solo puede contener caracteres alfanuméricos en minúscula, guiones bajos y puntos. El nombre no puede empezar ni terminar con un punto, y otro punto no puede seguirlo.
descriptionDescripción breve de la aplicación.
pathRuta de acceso al objeto binario del host de mensajería nativa. En Linux y OSX, la ruta debe ser absoluta. En Windows, puede estar relacionada con el directorio en el que se encuentra el archivo de manifiesto. El proceso del host se inicia con el directorio actual configurado en el directorio que contiene el objeto binario del host. Por ejemplo, si este parámetro se establece en C:\Application\nm_host.exe, se iniciará con el directorio actual C:\Application\.
typeEl tipo de interfaz que se usa para comunicarse con el host de mensajería nativa. Actualmente, solo hay un valor posible para este parámetro: stdio. Indica que Chrome debe usar stdin y stdout para comunicarse con el host.
allowed_originsLista de extensiones que deberían tener acceso al host de mensajería nativa. No se permiten los comodines como chrome-extension://*/*.

Ubicación del host de mensajería nativa

La ubicación del archivo de manifiesto depende de la plataforma.

En Windows, el archivo de manifiesto se puede encontrar en cualquier parte del sistema de archivos. El instalador de aplicaciones debe crear una clave de registro HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ o HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\_com.my_company.my_application_ y establecer el valor predeterminado de esa clave en la ruta de acceso completa al archivo de manifiesto. Por ejemplo, usa el siguiente comando:

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

o con el siguiente archivo .reg:

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

Cuando Chrome busca hosts de mensajería nativa, primero se consulta el registro de 32 bits y, luego, el de 64 bits.

En OS X y Linux, la ubicación del archivo de manifiesto del host de mensajería nativa varía según el navegador (Google Chrome o Chromium). Los hosts de mensajería nativa de todo el sistema se buscan en una ubicación fija, mientras que los hosts de mensajería nativa de nivel de usuario se buscan en un subdirectorio dentro del directorio del perfil del usuario llamado NativeMessagingHosts.

  • OS X (en todo el sistema)
    • 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 (ruta de acceso predeterminada específica del usuario)
    • 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 (en todo el sistema)
    • 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 (específica del usuario, ruta de acceso predeterminada)
    • Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
    • Chromium: ~/.config/chromium/NativeMessagingHosts/_com.my_company.my_application_.json

Protocolo de mensajería nativa

Chrome inicia cada host de mensajería nativa en un proceso separado y se comunica con él mediante la entrada estándar (stdin) y la salida estándar (stdout). Se usa el mismo formato para enviar mensajes en ambas direcciones: cada mensaje se serializa con JSON, codificado en UTF-8 y se antecede con una longitud de mensaje de 32 bits en orden de bytes nativo. El tamaño máximo de un solo mensaje del host de mensajería nativa es de 1 MB, principalmente para proteger a Chrome de aplicaciones nativas que funcionan mal. El tamaño máximo del mensaje enviado al host de mensajería nativa es de 4 GB.

El primer argumento para el host de mensajería nativa es el origen del llamador, que suele ser chrome-extension://[ID of allowed extension]. Esto permite que los hosts de mensajería nativa identifiquen la fuente del mensaje cuando se especifican varias extensiones en la clave allowed_origins del manifiesto de host de mensajería nativa. Advertencia: En Windows, en Chrome 54 y versiones anteriores, se pasaba el origen como el segundo parámetro, en lugar del primer parámetro.

Cuando se crea un puerto de mensajería con runtime.connectNative, Chrome inicia el proceso de host de mensajería nativa y lo sigue ejecutando hasta que se destruye el puerto. Por otro lado, cuando se envía un mensaje con runtime.sendNativeMessage, sin crear un puerto de mensajería, Chrome inicia un nuevo proceso de host de mensajería nativa para cada mensaje. En ese caso, el primer mensaje generado por el proceso del host se maneja como una respuesta a la solicitud original, es decir, Chrome lo pasará a la devolución de llamada de respuesta que se especificó cuando se llama a runtime.sendNativeMessage. En ese caso, se ignoran todos los demás mensajes generados por el host de mensajería nativa.

En Windows, el host de mensajería nativa también recibe un argumento de línea de comandos con un controlador para la ventana nativa de Chrome que realiza la llamada: --parent-window=<decimal handle value>. Esto permite que el host de mensajería nativa cree ventanas nativas de IU que tengan el superior correcto. Ten en cuenta que este valor será 0 si el contexto de llamada es una página de secuencia de comandos en segundo plano.

Cómo conectarse a una aplicación nativa

El envío y la recepción de mensajes hacia y desde una aplicación nativa es muy similar a los mensajes entre extensiones. La diferencia principal es que se usa runtime.connectNative en lugar de runtime.connect y runtime.sendNativeMessage en lugar de runtime.sendMessage. Solo se pueden usar estos métodos si el permiso "nativeMessaging" se declara en el archivo de manifiesto de la app.

En el siguiente ejemplo, se crea un objeto runtime.Port que está conectado al host de mensajería nativa com.my_company.my_application, comienza a escuchar mensajes de ese puerto y envía un mensaje saliente:

var port = 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 se puede usar para enviar un mensaje a una aplicación nativa sin crear un puerto, p.ej.:

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

Cómo depurar mensajes nativos

Cuando no se inicia el host de la mensajería nativa, escribe en stderr o infringe el protocolo de comunicación, el resultado se escribe en el registro de errores de Chrome. En Linux y OS X, se puede acceder a este registro fácilmente si se inicia Chrome desde la línea de comandos y se observa su resultado en la terminal. En Windows, usa --enable-logging como se explica en Cómo habilitar el registro.

Estos son algunos errores y sugerencias para resolver los problemas:

  • No se pudo iniciar el host de mensajería nativa.
    • Verifica si tienes los permisos necesarios para ejecutar el archivo.
  • El nombre del host de mensajería nativa especificado no es válido.
    • Verifica si el nombre contiene caracteres no válidos. Solo se permiten caracteres alfanuméricos en minúscula, guiones bajos y puntos. Un nombre no puede comenzar ni terminar con un punto, y un punto no puede estar seguido de otro punto.
  • Se salió del host nativo.
    • La canalización hacia el host de mensajería nativa se rompía antes de que Chrome leyera el mensaje. Es probable que esto se inicie desde el host de mensajería nativa.
  • No se encontró el host de mensajería nativa especificado.
    • ¿El nombre está escrito correctamente en la extensión y en el archivo de manifiesto?
    • ¿El manifiesto está colocado en el directorio correcto y con el nombre correcto? Consulta la ubicación del host de mensajería nativa para conocer los formatos esperados.
    • ¿El archivo de manifiesto tiene el formato correcto? En particular, ¿es correcta la sintaxis JSON y los valores coinciden con la definición de un manifiesto de host de mensajería nativa?
    • ¿Existe el archivo especificado en path? En Windows, las rutas de acceso pueden ser relativas, pero en OS X y Linux, las rutas deben ser absolutas.
  • El nombre de host del host de mensajería nativa no está registrado. (Solo para Windows)
    • No se encontró el host de mensajería nativa en el registro de Windows. Vuelve a verificar con regedit si la clave realmente se creó y si coincide con el formato requerido, como se documenta en la ubicación del host de mensajería nativa.
  • No se permite el acceso al host de mensajería nativa especificado.
    • ¿El origen de la extensión aparece en allowed_origins?
  • Se produjo un error durante la comunicación con el host de mensajería nativa.
    • Este es un error muy común que indica una implementación incorrecta del protocolo de comunicación en el host de mensajería nativa.
    • Asegúrate de que todos los resultados de stdout cumplan con el protocolo de mensajería nativa. Si deseas imprimir algunos datos con fines de depuración, escribe en stderr.
    • Asegúrate de que la longitud del mensaje de 32 bits esté en el formato de número entero nativo de la plataforma (little-endian/big-endian).
    • La longitud del mensaje no debe superar los 1,024*1,024.
    • El tamaño del mensaje debe ser igual a la cantidad de bytes del mensaje. Esto puede diferir de la "longitud" de una string, ya que los caracteres pueden estar representados por varios bytes.
    • Solo para Windows: Asegúrate de que el modo de E/S del programa esté configurado en O_BINARY. De forma predeterminada, el modo de E/S es O_TEXT, que daña el formato del mensaje, ya que los saltos de línea (\n = 0A) se reemplazan por finales de línea de estilo Windows (\r\n = 0D 0A). El modo de E/S se puede establecer con __setmode.