Rozszerzenia mogą wymieniać wiadomości z aplikacjami natywnymi przy użyciu interfejsu API podobnego do innych interfejsów API do przekazywania 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 standardowych.
Host natywnego przesyłania komunikatów
Aby zarejestrować hosta natywnego przesyłania wiadomości, aplikacja musi zapisać plik określający konfigurację hosta natywnego przesyłania komunikatów.
Przykładowy plik wygląda tak:
{
"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ć w formacie JSON i zawierać te pola:
name- Nazwa hosta komunikatora natywnego. Klienci przekazują ten ciąg znaków do usługi
runtime.connectNative()lubruntime.sendNativeMessage(). Ta nazwa może zawierać 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ć ani inna kropka. description- Krótki opis zgłoszenia.
path- Ścieżka do pliku binarnego hosta natywnego przesyłania wiadomości. W systemach Linux i macOS ścieżka musi być bezwzględna. W systemie Windows może on być względny względem katalogu zawierającego plik manifestu. Proces hosta jest uruchamiany z bieżącym katalogiem ustawionym na katalog zawierający plik binarny hosta. Jeśli na przykład ten parametr ma wartość
C:\Application\nm_host.exe, zostanie uruchomiony od bieżącego katalogu „C:\Aplikacja”. type- Typ interfejsu używanego do komunikacji z hostem natywnego przesyłania komunikatów. Ten parametr ma jedną z możliwych wartości:
stdio. Wskazuje ona, że do komunikacji z hostem Chrome powinien używaćstdinistdout. allowed_origins- Lista rozszerzeń, które powinny mieć dostęp do hosta natywnego przesyłania komunikatów. Wartości
allowed-originsnie mogą zawierać symboli wieloznacznych.
Lokalizacja hosta komunikatora natywnego
Lokalizacja pliku manifestu zależy od platformy.
W systemie Windows plik manifestu możesz umieścić 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ć domyślną wartość tego klucza 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ą tego 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 wiadomości natywnych, najpierw wysyłane jest zapytanie do rejestru 32-bitowego, a następnie do rejestru 64-bitowego.
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ą sprawdzane w stałej lokalizacji, natomiast hosty natywnych aplikacji do obsługi wiadomości na poziomie użytkownika są przeszukiwane 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 specyficzna dla użytkownika, domyślna)
- 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 (w całym systemie)
- 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 dla 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 host natywnego przesyłania wiadomości w osobnym procesie i komunikuje się z nim za pomocą standardowych danych wejściowych (stdin) i standardowych danych wyjściowych (stdout). Ten sam format jest używany do wysyłania wiadomości w obu kierunkach. Każda wiadomość jest serializowana w formacie JSON, zakodowana UTF-8 i jest poprzedzona 32-bitową długością wiadomości w natywnej kolejności bajtów. Maksymalny rozmiar pojedynczej wiadomości pochodzącej z hosta natywnego przesyłania wiadomości wynosi 1 MB. Głównie w celu ochrony Chrome przed nieodpowiednimi aplikacjami natywnymi. Maksymalny rozmiar wiadomości wysyłanej do hosta natywnego przesyłania wiadomości wynosi 4 GB.
Pierwszym argumentem hosta wiadomości natywnych to pochodzenie elementu wywołującego, zwykle chrome-extension://[ID of allowed extension]. Dzięki temu hosty natywnych aplikacji do obsługi wiadomości mogą zidentyfikować źródło wiadomości, gdy klucz allowed_origins w pliku manifestu hosta natywnego czatu zawiera wiele rozszerzeń.
W systemie Windows host natywnego przesyłania komunikatów otrzymuje też argument wiersza poleceń z nickem wywołującym okno natywne Chrome: --parent-window=<decimal handle value>. Dzięki temu host natywnego komunikatów głosowych może tworzyć okna interfejsu natywne, które mają prawidłowe elementy nadrzędne. Pamiętaj, że ta wartość wynosi 0, jeśli kontekst wywołania jest skryptem service worker.
Po utworzeniu portu do obsługi wiadomości przy użyciu runtime.connectNative() Chrome uruchamia natywny proces hosta do obsługi wiadomości i nie wyłącza go, dopóki port nie zostanie zniszczony. Z drugiej strony, gdy wiadomość jest wysyłana przez runtime.sendNativeMessage() bez utworzenia portu do obsługi wiadomości, Chrome rozpoczyna 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 zwrotnego określonego podczas wywołania runtime.sendNativeMessage(). Wszystkie pozostałe wiadomości wygenerowane przez hosta natywnego przesyłania komunikatów w takim przypadku będą ignorowane.
Nawiązywanie połączenia z aplikacją natywną
Wysyłanie i odbieranie wiadomości do i z aplikacji natywnej jest bardzo podobne do przesyłania wiadomości w różnych rozszerzeniach. Główna różnica polega na tym, że zamiast runtime.connect() używany jest runtime.connectNative(), a zamiast runtime.sendMessage() używany jest runtime.sendNativeMessage().
Aby korzystać z tych metod, uprawnienie „nativeMessaging” musi być zadeklarowane w pliku manifestu rozszerzeń.
Te metody nie są dostępne w skryptach treści, tylko na stronach rozszerzenia i w skrypcie service worker. Jeśli chcesz komunikować się za pomocą skryptu treści do aplikacji natywnej, wyślij wiadomość do skryptu service worker, który przekaże ją do aplikacji natywnej.
Poniższy przykład tworzy obiekt runtime.Port połączony z hostem natywnego przesyłania komunikatów com.my_company.my_application, zaczyna nasłuchiwać 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'});
Za pomocą runtime.sendNativeMessage możesz wysłać wiadomość do aplikacji natywnej bez tworzenia portu, na przykład:
chrome.runtime.sendNativeMessage(
'com.my_company.my_application',
{text: 'Hello'},
function (response) {
console.log('Received ' + response);
}
);
Debugowanie wiadomości natywnych
Gdy występują błędy związane z natywnymi wiadomościami, dane wyjściowe są zapisywane w dzienniku błędów Chrome. Dotyczy to sytuacji, gdy host natywnego przesyłania wiadomości nie uruchamia się, zapisuje w stderr lub narusza protokół komunikacji. W systemach Linux i macOS dostęp do tego dziennika można uzyskać, uruchamiając Chrome z poziomu wiersza poleceń i sprawdzając dane wyjściowe w terminalu. W systemie Windows użyj --enable-logging zgodnie z opisem w artykule Jak włączyć logowanie.
Oto kilka typowych błędów i wskazówki dotyczące ich rozwiązywania:
Nie udało się uruchomić hosta natywnego przesyłania wiadomości.
Sprawdź, czy masz wystarczające uprawnienia do wykonywania pliku hosta wiadomości natywnych.
Podano nieprawidłową nazwę hosta komunikatora natywnego.
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 być inna kropka.
Host natywny został zamknięty.
Pionowa kreska do hosta komunikatora natywnego uległa uszkodzeniu przed odczytaniem wiadomości przez Chrome. Najczęściej inicj ten pochodzi z hosta natywnego przesyłania komunikatów.
Nie znaleziono określonego hosta komunikatora natywnego.
Wykonaj te czynności:
- Czy nazwa jest poprawnie napisana w rozszerzeniu i w pliku manifestu?
- Czy plik manifestu znajduje się w odpowiednim katalogu i ma prawidłową nazwę? Odpowiednie formaty znajdziesz w sekcji Lokalizacja hosta komunikatora natywnego.
- Czy plik manifestu ma prawidłowy format? W szczególności czy kod JSON jest prawidłowy i prawidłowo oraz czy wartości pasują do definicji pliku manifestu hosta natywnego przesyłania komunikatów.
- Czy plik określony w polu
pathistnieje? W systemie Windows ścieżki mogą być względne, a w systemach macOS i Linux ścieżki bezwzględne.
Nazwa hosta hosta wiadomości natywnych nie jest zarejestrowana. (tylko Windows)
Nie znaleziono hosta natywnego przesyłania komunikatów w rejestrze systemu Windows. Korzystając z metody regedit, sprawdź dokładnie, czy klucz został rzeczywiście utworzony i czy pasuje do wymaganego formatu, co jest zgodne z lokalizacją hosta natywnego przekazu.
Dostęp do określonego hosta wiadomości natywnych jest zabroniony.
Czy źródło rozszerzenia jest podane w: allowed_origins?
Podczas komunikacji z hostem natywnego przesyłania wiadomości wystąpił błąd.
Wskazuje to na nieprawidłową implementację protokołu komunikacyjnego na hoście natywnego przesyłania wiadomości.
- Upewnij się, że wszystkie dane wyjściowe w usłudze
stdoutsą zgodne z protokołem natywnego przesyłania wiadomości. Jeśli chcesz wydrukować niektóre dane do celów debugowania, wpisz je na stroniestderr. - Upewnij się, że 32-bitowa długość komunikatu jest zapisana w natywnym formacie liczb całkowitych dostępnych na platformie (little-endian/big-endian).
- Długość wiadomości nie może przekraczać 1024*1024.
- Rozmiar wiadomości musi być równy liczbie bajtów tej wiadomości. Ta wartość może różnić się od „długości” ciągu znaków, ponieważ znaki mogą być reprezentowane przez wiele bajtów.
- Tylko w systemie Windows: upewnij się, że tryb wejścia-wyjścia programu jest ustawiony na
O_BINARY. Domyślnie tryb wejścia/wyjścia toO_TEXT, co powoduje uszkodzenie formatu wiadomości, ponieważ podziały wierszy (\n=0A) są zastępowane zakończeniami wierszy w stylu Windows (\r\n=0D 0A). Tryb wejścia-wyjścia można ustawić, używając elementu__setmode.