Se usó la API de Cloud Translation para traducir esta página.

Mensajería nativa

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

Host de mensajería nativa

Para registrar un host de mensajería nativa, la aplicación debe guardar un archivo que defina la configuración del host de mensajería nativa.

El siguiente es un ejemplo del archivo:

{
  "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 ser JSON válido y contener los siguientes campos:

name: Es el nombre del host de mensajería nativa. Los clientes pasan esta cadena a runtime.connectNative() o runtime.sendNativeMessage(). Este nombre solo puede contener caracteres alfanuméricos en minúscula, guiones bajos y puntos. El nombre no puede comenzar ni terminar con un punto, y no puede haber otro punto después de un punto.
description: Descripción breve de la aplicación.
path: Ruta de acceso al objeto binario del host de la mensajería nativa. En Linux y macOS, la ruta de acceso debe ser absoluta. En Windows, puede ser relativa al directorio que contiene el archivo de manifiesto. El proceso de 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".
type: Es el tipo de interfaz que se usa para comunicarse con el host de mensajería nativa. Este parámetro tiene un valor posible: stdio. Indica que Chrome debe usar stdin y stdout para comunicarse con el host.
allowed_origins: Es una lista de extensiones que deben tener acceso al host de mensajería nativa. Los valores de allowed-origins no pueden contener comodines.

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 ubicar en cualquier parte del sistema de archivos. El instalador de la aplicación debe crear una clave de registro, ya sea 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 usa 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 macOS 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 del sistema se buscan en una ubicación fija, mientras que los hosts de mensajería nativa a nivel del usuario se buscan en el subdirectorio NativeMessagingHosts/ del directorio de perfil de usuario.

macOS (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
macOS (específica del usuario, ruta default): 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 (ruta predeterminada específica del usuario): 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 independiente 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 va precedido por 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 se comporten de forma incorrecta. El tamaño máximo del mensaje que se envía al host de mensajería nativo es de 4 GB.

El primer argumento del host de mensajería nativa es el origen del llamador, por lo general, 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 del host de mensajería nativa.

En Windows, al host de mensajería nativa también se le pasa un argumento de línea de comandos con un identificador a 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 de IU nativas que estén correctamente vinculadas a su elemento superior. Ten en cuenta que este valor será 0 si el contexto de llamada es un trabajador de servicio.

Cuando se crea un puerto de mensajería con runtime.connectNative(), Chrome inicia el proceso de host de mensajería nativa y lo mantiene en ejecución 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 que genera el proceso del host se controla como una respuesta a la solicitud original, y Chrome lo pasará a la devolución de llamada de respuesta especificada cuando se llame a runtime.sendNativeMessage(). En ese caso, se ignoran todos los demás mensajes que genera el host de mensajería nativa.

Cómo conectarse a una aplicación nativa

Enviar y recibir mensajes desde y hacia 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().

Para usar estos métodos, se debe declarar el permiso "nativeMessaging" en el archivo de manifiesto de tu extensión.

Estos métodos no están disponibles dentro de las secuencias de comandos de contenido, solo dentro de las páginas de tu extensión y el service worker. Si deseas comunicarte desde una secuencia de comandos de contenido a la aplicación nativa, envía el mensaje a tu trabajador de servicio para que lo pase a la aplicación nativa.

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'});

Usa runtime.sendNativeMessage para enviar un mensaje a la 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 la mensajería nativa

Cuando se producen ciertas fallas de mensajería nativa, el resultado se escribe en el registro de errores de Chrome. Esto incluye cuando el host de mensajería nativa no se inicia, escribe en stderr o incumple el protocolo de comunicación. En Linux y macOS, se puede acceder a este registro si se inicia Chrome desde la línea de comandos y se mira el resultado en la terminal. En Windows, usa --enable-logging como se explica en Cómo habilitar el registro.

Estos son algunos errores comunes y sugerencias para solucionarlos:

No se pudo iniciar el host de mensajería nativa.

Verifica si tienes permisos suficientes para ejecutar el archivo host de mensajería nativa.

El nombre de 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 no puede haber otro punto después de un punto.

Se cerró el host nativo.

El canal al host de mensajería nativa se cerró antes de que Chrome leyera el mensaje. Es probable que se inicie desde tu host de mensajería nativa.

No se encontró el host de mensajería nativa especificado.

Verifica lo siguiente:

¿El nombre está escrito correctamente en la extensión y en el archivo de manifiesto?
¿El manifiesto está 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, ¿el JSON es válido y está bien formado, 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 macOS y Linux, deben ser absolutas.

No se registró el nombre de host del host de mensajería nativa. (solo para Windows)

No se encontró el host de mensajería nativa en el registro de Windows. Verifica con regedit si la clave realmente se creó y coincide con el formato requerido, como se documenta en la ubicación del host de mensajería nativa.

El acceso al host de mensajería nativa especificado está prohibido.

¿El origen de la extensión aparece en allowed_origins?

Se produjo un error cuando se comunicaba con el host de mensajería nativo.

Esto 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 nativo. Si quieres imprimir algunos datos para depurar, 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 (endianidad baja o alta).
La longitud del mensaje no debe exceder 1,024*1,024.
El tamaño del mensaje debe ser igual a la cantidad de bytes que tiene. Esto puede diferir de la "longitud" de una cadena, 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 configurar con __setmode.