Messagerie native

Les extensions peuvent échanger des messages avec des applications natives à l'aide d'une API semblable aux autres API de transfert de messages. Les applications natives compatibles avec cette fonctionnalité doivent enregistrer un hôte de messagerie natif pouvant communiquer avec l'extension. Chrome démarre l'hôte dans un processus distinct et communique avec lui à l'aide des flux d'entrée et de sortie standards.

Hôte de messagerie native

Pour enregistrer un hôte de messagerie native, l'application doit enregistrer un fichier qui définit la configuration de l'hôte de messagerie native.

Voici un exemple de fichier :

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

Le fichier manifeste de l'hôte de messagerie natif doit être un fichier JSON valide et contenir les champs suivants :

name

Nom de l'hôte de messagerie native. Les clients transmettent cette chaîne à runtime.connectNative() ou runtime.sendNativeMessage(). Ce nom ne peut contenir que des caractères alphanumériques minuscules, des traits de soulignement et des points. Le nom ne peut pas commencer ni se terminer par un point, et un point ne peut pas être suivi d'un autre point.

description

Brève description de l'application.

path

Chemin d'accès au binaire de l'hôte de messagerie native. Sous Linux et macOS, le chemin d'accès doit être absolu. Sur Windows, il peut être relatif au répertoire contenant le fichier manifeste. Le processus hôte est démarré avec le répertoire actuel défini sur le répertoire contenant le binaire hôte. Par exemple, si ce paramètre est défini sur C:\Application\nm_host.exe, il démarrera avec le répertoire actuel "C:\Application".

type

Type d'interface utilisée pour communiquer avec l'hôte de messagerie native. Ce paramètre n'a qu'une seule valeur possible : stdio. Il indique que Chrome doit utiliser stdin et stdout pour communiquer avec l'hôte.

allowed_origins

Liste des extensions qui doivent avoir accès à l'hôte de messagerie natif. Les valeurs allowed_origins ne peuvent pas contenir de caractères génériques.

Emplacement de l'hôte de messagerie native

L'emplacement du fichier manifeste dépend de la plate-forme.

Sur Windows, le fichier manifeste peut se trouver n'importe où dans le système de fichiers. Le programme d'installation de l'application doit créer une clé de registre, HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application ou HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application, et définir la valeur par défaut de cette clé sur le chemin d'accès complet au fichier manifeste. Par exemple, à l'aide de la commande suivante :

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

ou en utilisant le fichier .reg suivant :

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

Lorsque Chrome recherche des hôtes de messagerie natifs, il interroge d'abord le registre 32 bits, puis le registre 64 bits.

Sur macOS et Linux, l'emplacement du fichier manifeste de l'hôte de messagerie natif varie selon le navigateur (Google Chrome, Google Chrome for Testing ou Chromium). Les hôtes de messagerie native à l'échelle du système sont recherchés à un emplacement fixe, tandis que les hôtes de messagerie native au niveau de l'utilisateur sont recherchés dans le sous-répertoire NativeMessagingHosts/ du répertoire du profil utilisateur.

Remarque : Dans les versions de Chrome antérieures à Chrome 146, Google Chrome for Testing utilisait les mêmes emplacements que Google Chrome.

macOS (à l'échelle du système)

Google Chrome : /Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json

Google Chrome for Testing : /Library/Google/ChromeForTesting/NativeMessagingHosts/com.my_company.my_application.json

Chromium : /Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json

macOS (chemin d'accès par défaut spécifique à l'utilisateur)

Google Chrome : ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json

Google Chrome for Testing : ~/Library/Application Support/Google/ChromeForTesting/NativeMessagingHosts/com.my_company.my_application.json

Chromium : ~/Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json

Linux (à l'échelle du système)

Google Chrome : /etc/opt/chrome/native-messaging-hosts/com.my_company.my_application.json

Google Chrome for Testing : /etc/opt/chrome_for_testing/native-messaging-hosts/com.my_company.my_application.json

Chromium : /etc/chromium/native-messaging-hosts/com.my_company.my_application.json

Linux (chemin d'accès par défaut spécifique à l'utilisateur)

Google Chrome : ~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json

Google Chrome for Testing : ~/.config/google-chrome-for-testing/NativeMessagingHosts/com.my_company.my_application.json

Chromium : ~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json

Protocole de messagerie native

Chrome démarre chaque hôte de messagerie native dans un processus distinct et communique avec lui à l'aide de l'entrée standard (stdin) et de la sortie standard (stdout). Le même format est utilisé pour envoyer des messages dans les deux sens. Chaque message est sérialisé à l'aide de JSON, encodé en UTF-8 et précédé d'une longueur de message de 32 bits dans l'ordre des octets natif. La taille maximale d'un message unique provenant de l'hôte de messagerie natif est de 1 Mo, principalement pour protéger Chrome contre les applications natives au comportement inapproprié. La taille maximale du message envoyé à l'hôte de messagerie natif est de 64 Mio.

Le premier argument de l'hôte de messagerie natif est l'origine de l'appelant, généralement chrome-extension://[ID of allowed extension]. Cela permet aux hôtes de messagerie native d'identifier la source du message lorsque plusieurs extensions sont spécifiées dans la clé allowed_origins du fichier manifeste de l'hôte de messagerie native.

Sous Windows, un argument de ligne de commande avec un handle vers la fenêtre native Chrome appelante est également transmis à l'hôte de messagerie native : --parent-window=<decimal handle value>. Cela permet à l'hôte de messagerie native de créer des fenêtres d'UI natives correctement parentées. Notez que cette valeur sera égale à 0 si le contexte d'appel est un service worker.

Lorsqu'un port de messagerie est créé à l'aide de runtime.connectNative(), Chrome démarre un processus hôte de messagerie native et le maintient en cours d'exécution jusqu'à ce que le port soit détruit. En revanche, lorsqu'un message est envoyé à l'aide de runtime.sendNativeMessage(), sans créer de port de messagerie, Chrome démarre un nouveau processus d'hôte de messagerie native pour chaque message. Dans ce cas, le premier message généré par le processus hôte est traité comme une réponse à la requête d'origine, et Chrome le transmet au rappel de réponse spécifié lors de l'appel de runtime.sendNativeMessage(). Tous les autres messages générés par l'hôte de messagerie native dans ce cas sont ignorés.

Se connecter à une application native

L'envoi et la réception de messages vers et depuis une application native sont très semblables à la messagerie multi-extensions. La principale différence est que runtime.connectNative() est utilisé à la place de runtime.connect(), et que runtime.sendNativeMessage() est utilisé à la place de runtime.sendMessage().

Pour utiliser ces méthodes, l'autorisation"nativeMessaging" doit être déclarée dans le fichier manifeste de votre extension.

Ces méthodes ne sont pas disponibles dans les scripts de contenu, mais uniquement dans les pages et le service worker de votre extension. Pour communiquer depuis un script de contenu vers l'application native, envoyez le message à votre service worker afin qu'il le transmette à l'application native.

Avertissement : Étant donné que les scripts de contenu partagent un processus de rendu avec des pages Web non fiables, votre service worker doit valider sender.origin (ou sender.url) et assainir la charge utile du message avant de transférer des données à l'hôte natif.

L'exemple suivant crée un objet runtime.Port connecté à l'hôte de messagerie native com.my_company.my_application, commence à écouter les messages de ce port et envoie un message sortant :

const port = chrome.runtime.connectNative('com.my_company.my_application');
port.onMessage.addListener((msg) => {
  console.log('Received', msg);
});
port.onDisconnect.addListener(() => {
  if (chrome.runtime.lastError) {
    console.error(
      'Disconnected due to error:',
      chrome.runtime.lastError.message
    );
  } else {
    console.log('Disconnected');
  }
});
port.postMessage({text: 'Hello, my_application'});

Utilisez runtime.sendNativeMessage pour envoyer un message à l'application native sans créer de port, par exemple :

chrome.runtime.sendNativeMessage(
  'com.my_company.my_application',
  {text: 'Hello'},
  (response) => {
    if (chrome.runtime.lastError) {
      console.error(
        'Error sending native message:',
        chrome.runtime.lastError.message
      );
      return;
    }
    console.log('Received', response);
  }
);

Déboguer la messagerie native

En cas d'échec de la messagerie native, les informations de diagnostic sont écrites dans le journal des erreurs de Chrome.

Linux et macOS

# Linux
google-chrome --enable-logging=stderr --log-level=1 2>&1 | \
  grep -E "native_messag|launch_context"

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --enable-logging=stderr --log-level=1 2>&1 | \
  grep -E "native_messag|launch_context"

Windows

Lancez Chrome avec la journalisation activée :

chrome.exe --enable-logging --log-level=1

Transmettez --user-data-dir="%TEMP%\nm-debug" pour lancer une instance distincte sans l'associer à un processus Chrome existant.

Pour afficher le résultat, diffusez chrome_debug.log à l'aide de PowerShell :

$log = "$env:LOCALAPPDATA\Google\Chrome\User Data\chrome_debug.log"
Get-Content -Wait $log | Select-String "native_messag|launch_context"

Vous pouvez également ouvrir chrome_debug.log dans un éditeur de texte et rechercher launch_context.cc ou native_message_process_host.cc.

Informations sur la journalisation des clés

• Les échecs de recherche et d'analyse du fichier manifeste dans launch_context.cc sont enregistrés en tant qu'avertissements. Utilisez --log-level=1 plutôt que 2 (ERROR), ce qui supprime ces diagnostics de démarrage.
• Recherchez launch_context pour trouver les erreurs de lancement de fichier manifeste et de binaire, et native_messag pour trouver les erreurs de taille de charge utile et de communication de canal.

Erreurs fréquentes

Voici quelques erreurs courantes et des conseils pour les résoudre :

Échec du démarrage de l'hôte de messagerie native.

Vérifiez que vous disposez des autorisations suffisantes pour exécuter le fichier hôte de messagerie native.

Nom d'hôte de messagerie native non valide spécifié.

Vérifiez si le nom contient des caractères non valides. Seuls les caractères alphanumériques en minuscules, les traits de soulignement et les points sont autorisés. Un nom ne peut pas commencer ni se terminer par un point, et un point ne peut pas être suivi d'un autre point.

L'hôte natif a quitté la session.

Le canal vers l'hôte de messagerie natif a été interrompu avant que le message ne soit lu par Chrome. Cela est très probablement initié par votre hôte de messagerie native.

L'hôte de messagerie native spécifié est introuvable.

Vérifiez les éléments suivants :

• Le nom est-il correctement orthographié dans l'extension et dans le fichier manifeste ?
• Sur Windows, la clé de registre existe-t-elle sous HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE, et sa valeur par défaut pointe-t-elle vers le chemin d'accès complet au fichier manifeste ? Chrome interroge d'abord la vue du registre 32 bits, puis celle du registre 64 bits. Utilisez regedit pour valider la clé. Consultez Emplacement de l'hôte de messagerie native.
• Sous macOS et Linux, le fichier manifeste se trouve-t-il dans le répertoire attendu et porte-t-il le nom de l'hôte (par exemple, com.my_company.my_application.json) ? Consultez Emplacement de l'hôte de messagerie native.
• Le fichier manifeste est-il au bon format ? En particulier, le fichier JSON est-il valide et bien formé, et les valeurs correspondent-elles à la définition d'un fichier manifeste d'hôte de messagerie native ?
• Le fichier spécifié dans path existe-t-il ? Sous Windows, les chemins d'accès peuvent être relatifs, mais sous macOS et Linux, ils doivent être absolus.

L'accès à l'hôte de messagerie native spécifié est interdit.

L'origine de l'extension est-elle listée dans allowed_origins ?

Erreur lors de la communication avec l'hôte de messagerie natif.

Cela indique une implémentation incorrecte du protocole de communication dans l'hôte de messagerie natif.

• Assurez-vous que tous les résultats dans stdout respectent le protocole de messagerie native. Si vous souhaitez imprimer des données à des fins de débogage, écrivez dans stderr.
• Assurez-vous que la longueur du message de 32 bits est au format entier natif de la plate-forme (little-endian/big-endian).
• La longueur du message ne doit pas dépasser 1 024 x 1 024.
• La taille du message doit être égale au nombre d'octets qu'il contient. Cela peut différer de la "longueur" d'une chaîne, car les caractères peuvent être représentés par plusieurs octets.
• Windows uniquement : assurez-vous que le mode d'E/S du programme est défini sur O_BINARY. Par défaut, le mode d'E/S est O_TEXT, ce qui corrompt le format du message, car les sauts de ligne (\n = 0A) sont remplacés par des fins de ligne de style Windows (\r\n = 0D 0A). Le mode d'E/S peut être défini à l'aide de __setmode.