Rozszerzenia mogą wymieniać wiadomości z natywnymi aplikacjami przy użyciu interfejsu API podobnego do innych interfejsów API przekazujących wiadomości. Aplikacje natywne, które obsługują tę funkcję, muszą zarejestrować hosta natywnego przesyłania komunikatów, który może komunikować się z rozszerzeniem. Chrome uruchamia hosta w osobnym procesie i komunikuje się z nim za pomocą standardowych strumieni wejściowych i wyjściowych.
Host natywnego przesyłania komunikatów
Aby zarejestrować hosta wiadomości natywnych, aplikacja musi zapisać plik określający konfigurację hosta wiadomości natywnych.
Przykład takiego pliku:
{
"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/"]
}
Plik manifestu hosta natywnego przesyłania wiadomości musi być prawidłowym plikiem JSON i zawierać te pola:
name- Nazwa hosta natywnego przesyłania komunikatów. Klienci przekazują ten ciąg znaków do
runtime.connectNative()lubruntime.sendNativeMessage(). Ta nazwa może zawierać wyłącznie małe znaki alfanumeryczne, podkreślenia i kropki. Nazwa nie może zaczynać się ani kończyć kropką, a po niej nie może następować inna kropka. description- Krótki opis aplikacji.
path- Ścieżka do binarnego hosta natywnego przesyłania komunikatów. W systemach Linux i macOS ścieżka musi być bezwzględna. W systemie Windows może to być katalog zawierający plik manifestu. Proces hosta jest uruchamiany z bieżącym katalogiem ustawionym na katalog zawierający binarne pliki hosta. Jeśli na przykład parametr ma wartość
C:\Application\nm_host.exe, zostanie uruchomiony z bieżącego katalogu „C:\Application”. type- Typ interfejsu używanego do komunikacji z hostem wiadomości natywnej. Ten parametr ma jedną możliwą wartość:
stdio. Wskazuje, że Chrome powinien używaćstdinistdoutdo komunikacji z hostem. allowed_origins- Lista rozszerzeń, które powinny mieć dostęp do hosta natywnej aplikacji do obsługi wiadomości. Wartości
allowed-originsnie mogą zawierać symboli wieloznacznych.
Lokalizacja hosta natywnego przesyłania komunikatów
Lokalizacja pliku manifestu zależy od platformy.
W systemie Windows plik manifestu może się znajdować w dowolnym miejscu w systemie plików. Instalator aplikacji musi utworzyć klucz rejestru (HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application lub HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application) i ustawić jego domyślną wartość na pełną ścieżkę do pliku manifestu. Na przykład za pomocą tego polecenia:
REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f
lub za pomocą pliku .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"
Gdy Chrome szuka hostów natywnych komunikatów, najpierw sprawdza rejestr 32-bitowy, a potem 64-bitowy.
W systemach macOS i Linux lokalizacja pliku manifestu natywnego hosta wiadomości różni się w zależności od przeglądarki (Google Chrome lub Chromium). Hosty natywnych aplikacji do obsługi wiadomości w całym systemie są wyszukiwane w stałym miejscu, a hosty natywnych aplikacji do obsługi wiadomości na poziomie użytkownika w podkatalogu NativeMessagingHosts/ katalogu profilu użytkownika.
- macOS (cały system)
- 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 (ścieżka domyślna, zależna od użytkownika)
- 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 (cały system)
- 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 (ścieżka domyślna, zależna od użytkownika)
- Google Chrome:
~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json - Chromium:
~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json
Protokół natywnego przesyłania komunikatów
Chrome uruchamia każdy natywny host wiadomości w oddzielnym procesie i komunikuje się z nim za pomocą standardowego wejścia (stdin) i standardowego wyjścia (stdout). Ten sam format jest używany do wysyłania wiadomości w obu kierunkach. Każda wiadomość jest serializowana za pomocą JSON, kodowana w standardzie UTF-8 i poprzedzona 32-bitową długością wiadomości w natywnej kolejności bajtów. Maksymalny rozmiar pojedynczej wiadomości z rodziny aplikacji do obsługi wiadomości wynosi 1 MB. Ma to na celu ochronę Chrome przed nieprawidłowo działającymi natywnymi aplikacjami. Maksymalny rozmiar wiadomości wysyłanej do hosta natywnego przesyłania komunikatów wynosi 4 GB.
Pierwszym argumentem do hosta natywnej wiadomości jest pochodzenie dzwoniącego, zwykle chrome-extension://[ID of allowed extension]. Umożliwia to hostom natywnych aplikacji do obsługi wiadomości identyfikowanie źródła wiadomości, gdy w kluczu allowed_origins w pliku manifestu hosta natywnej aplikacji do obsługi wiadomości podano wiele rozszerzeń.
W systemie Windows host natywnego przesyłania komunikatów również jest przekazywany jako argument wiersza poleceń z uchwytem do wywołania natywnego okna Chrome: --parent-window=<decimal handle value>. Dzięki temu host natywnego przesyłania komunikatów może tworzyć natywne okna interfejsu użytkownika, które są prawidłowo powiązane z ich rodzicem. Pamiętaj, że ta wartość będzie miała wartość 0, jeśli kontekst wywołania to service worker.
Gdy port wiadomości zostanie utworzony przy użyciu runtime.connectNative(), Chrome uruchamia proces hosta natywnego przesyłania komunikatów i zachowuje go do momentu zniszczenia portu. Z drugiej strony, gdy wiadomość zostanie wysłana za pomocą runtime.sendNativeMessage(), bez tworzenia portu przesyłania, Chrome uruchamia dla każdej wiadomości nowy proces hosta natywnego przesyłania wiadomości. W takim przypadku pierwsza wiadomość wygenerowana przez proces hosta jest traktowana jako odpowiedź na pierwotne żądanie, a Chrome przekazuje ją do wywołania odpowiedzi określonego w funkcji runtime.sendNativeMessage(). W takim przypadku wszystkie inne wiadomości wygenerowane przez natywną aplikację do obsługi wiadomości są ignorowane.
Łączenie z natywną aplikacją
Wysyłanie i odbieranie wiadomości z i do aplikacji natywnej jest bardzo podobne do przesyłania wiadomości z różnych rozszerzeń. Główna różnica polega na tym, że zamiast runtime.connect() używany jest runtime.connectNative(), a zamiast runtime.sendMessage() jest używany runtime.sendNativeMessage().
Aby móc korzystać z tych metod, w pliku manifestu rozszerzeń musisz zadeklarować uprawnienie „nativeMessaging”.
Te metody nie są dostępne w skryptach treści, a tylko na stronach rozszerzenia i w skrypcie service worker. Jeśli chcesz przesłać wiadomość ze skryptu treści do natywnej aplikacji, wyślij ją do swojego pracownika usługi, aby przekazać ją do natywnej aplikacji.
Poniższy przykład tworzy obiekt runtime.Port połączony z hostem natywnego przesyłania komunikatów com.my_company.my_application, rozpoczyna nasłuchiwanie wiadomości z tego portu i wysyła 1 wiadomość wychodzącą:
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'});
Aby wysłać wiadomość do natywnej aplikacji bez tworzenia portu, użyj runtime.sendNativeMessage, np.:
chrome.runtime.sendNativeMessage(
'com.my_company.my_application',
{text: 'Hello'},
function (response) {
console.log('Received ' + response);
}
);
Debugowanie natywnych aplikacji do obsługi wiadomości
Gdy wystąpią pewne błędy w komunikacji natywnej, dane wyjściowe są zapisywane w dzienniku błędów Chrome. Dotyczy to sytuacji, gdy natywny host aplikacji do obsługi wiadomości nie uruchamia się, zapisuje do pliku stderr lub narusza protokół komunikacji. W systemach Linux i macOS możesz uzyskać dostęp do tego dziennika, uruchamiając Chrome z poziomu wiersza poleceń i obserwując jego dane wyjściowe w terminalu. W systemie Windows należy używać --enable-logging zgodnie z opisem w sekcji Jak włączyć logowanie.
Oto kilka częstych błędów i wskazówki, jak je rozwiązać:
Nie udało się uruchomić hosta natywnego przesyłania komunikatów.
Sprawdź, czy masz wystarczające uprawnienia do wykonania pliku hosta natywnej aplikacji do obsługi wiadomości.
Określono nieprawidłową nazwę hosta natywnego przesyłania komunikatów.
Sprawdź, czy nazwa zawiera nieprawidłowe znaki. Dozwolone są tylko małe znaki alfanumeryczne, podkreślenia i kropki. Nazwa nie może zaczynać się ani kończyć kropką, a po kropce nie może następować inna kropka.
Host natywny został zamknięty.
Przesył danych do hosta natywnej aplikacji do obsługi wiadomości został przerwany, zanim wiadomość została odczytana przez Chrome. Najczęściej jest to inicjowane przez hosta natywnego przesyłania komunikatów.
Nie znaleziono wskazanego hosta natywnej aplikacji do obsługi wiadomości.
Sprawdź poniższe kwestie:
- Czy nazwa jest zapisana prawidłowo w pliku rozszerzenia i pliku manifestu?
- Czy manifest znajduje się w odpowiednim katalogu i czy ma prawidłową nazwę? Aby dowiedzieć się, jakie formaty są obsługiwane, zobacz lokalizację hosta natywnej aplikacji do obsługi wiadomości.
- Czy plik manifestu ma prawidłowy format? Czy dane w formacie JSON są prawidłowe i sformatowane prawidłowo? Czy wartości odpowiadają definicji pliku manifestu hosta wiadomości natywnych?
- Czy plik określony w parametry
pathistnieje? W systemie Windows ścieżki mogą być względne, ale w systemach macOS i Linux muszą być bezwzględne.
Nazwa hosta natywnej aplikacji do obsługi wiadomości nie jest zarejestrowana. (tylko w Windows)
W rejestrze systemu Windows nie znaleziono hosta natywnej aplikacji do obsługi wiadomości. Upewnij się, że klucz został utworzony i jest zgodny z wymaganym formatem opisanym w miejscu hostowania natywnych wiadomości (regedit).
Dostęp do określonego hosta natywnej aplikacji do obsługi wiadomości jest zabroniony.
Czy źródło rozszerzenia jest podane w tym kraju: allowed_origins?
Błąd podczas komunikacji z hostem natywnych wiadomości.
Oznacza to, że protokół komunikacyjny został nieprawidłowo wdrożony na hoście natywnego przesyłania komunikatów.
- Upewnij się, że wszystkie dane wyjściowe w pliku
stdoutsą zgodne z protokołem natywnych aplikacji do obsługi wiadomości. Jeśli chcesz wydrukować dane na potrzeby debugowania, napisz dostderr. - Upewnij się, że 32-bitowa długość wiadomości jest w natywności platformy (little-endian lub big-endian).
- Długość wiadomości nie może przekraczać 1024*1024.
- Rozmiar wiadomości musi być równy liczbie bajtów w wiadomości. Może się to różnić od „długości” ciągu, ponieważ znaki mogą być reprezentowane przez kilka bajtów.
- Tylko Windows: sprawdź, czy tryb we/wy programu jest ustawiony na
O_BINARY. Domyślnie tryb we/wy toO_TEXT, który powoduje uszkodzenie formatu wiadomości, ponieważ znaki końca wiersza (\n=0A) są zastępowane przez znaki końca wiersza w stylu Windows (\r\n=0D 0A). Tryb we/wy można ustawić za pomocą parametru__setmode.