Ekstensi dapat bertukar pesan dengan aplikasi native menggunakan API yang mirip dengan API penerusan pesan lainnya. Aplikasi native yang mendukung fitur ini harus mendaftarkan host pesan native yang dapat berkomunikasi dengan ekstensi. Chrome memulai host dalam proses terpisah dan berkomunikasi dengannya menggunakan input standar dan aliran output standar.
Host pesan native
Untuk mendaftarkan host pesan native, aplikasi harus menyimpan file yang menentukan konfigurasi host pesan native.
Contoh filenya adalah sebagai berikut:
{
"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/"]
}
File manifes host pesan native harus berupa JSON yang valid dan berisi kolom berikut:
name- Nama host pesan native. Klien meneruskan string ini ke
runtime.connectNative()atauruntime.sendNativeMessage(). Nama ini hanya boleh berisi karakter alfanumerik huruf kecil, garis bawah, dan titik. Nama tidak boleh diawali atau diakhiri dengan titik, dan titik tidak boleh diikuti dengan titik lain. description- Deskripsi aplikasi singkat.
path- Jalur ke biner host pesan native. Di Linux dan macOS, jalur harus bersifat absolut. Di Windows, jalur ini dapat bersifat relatif terhadap direktori yang berisi file manifes. Proses host dimulai dengan direktori saat ini ditetapkan ke direktori yang berisi biner host. Misalnya, jika parameter ini disetel ke
C:\Application\nm_host.exe, parameter akan dimulai dengan direktori saat ini `C:\Application`. type- Jenis antarmuka yang digunakan untuk berkomunikasi dengan host pesan native. Parameter ini memiliki satu kemungkinan nilai:
stdio. Hal ini menunjukkan bahwa Chrome harus menggunakanstdindanstdoutuntuk berkomunikasi dengan host. allowed_origins- Daftar ekstensi yang harus memiliki akses ke host pesan native. Nilai
allowed-originstidak boleh berisi karakter pengganti.
Lokasi host pesan native
Lokasi file manifes bergantung pada platform.
Di Windows, file manifes dapat ditempatkan di mana saja dalam sistem file. Penginstal
aplikasi harus membuat kunci registry, baik
HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application maupun
HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application, dan
menetapkan nilai default kunci tersebut ke jalur lengkap ke file manifes. Misalnya, menggunakan
perintah berikut:
REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f
atau menggunakan file .reg berikut:
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application]
@="C:\\path\\to\\nmh-manifest.json"
Saat Chrome mencari host pesan native, registry 32-bit akan dikueri terlebih dahulu, lalu registry 64-bit.
Di macOS dan Linux, lokasi file manifes host pesan native bervariasi menurut browser (Google Chrome atau Chromium). Host pesan native seluruh sistem dilihat pada lokasi
tetap, sedangkan host pesan native tingkat pengguna dicari di subdirektori NativeMessagingHosts/
pada direktori profil pengguna.
- macOS (seluruh sistem)
- 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 (jalur default khusus pengguna)
- 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 (seluruh sistem)
- 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 (jalur default khusus pengguna)
- Google Chrome:
~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json - Chromium:
~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json
Protokol pesan native
Chrome memulai setiap host pesan native dalam proses terpisah dan berkomunikasi dengannya menggunakan
input standar (stdin) dan output standar (stdout). Format yang sama digunakan untuk mengirim pesan
di kedua arah; setiap pesan diserialisasi menggunakan enkode JSON, UTF-8, dan didahului dengan panjang pesan
32-bit dalam urutan byte native. Ukuran maksimum satu pesan dari host pesan native
adalah 1 MB, terutama untuk melindungi Chrome dari aplikasi native yang berperilaku tidak semestinya. Ukuran maksimum pesan yang dikirim ke host pesan native adalah 4 GB.
Argumen pertama ke host pesan native adalah asal pemanggil, biasanya
chrome-extension://[ID of allowed extension]. Hal ini memungkinkan host fitur pesan native mengidentifikasi
sumber pesan saat beberapa ekstensi ditentukan dalam kunci allowed_origins di
manifes host fitur pesan native.
Di Windows, host pesan native juga meneruskan argumen command line dengan handle ke
jendela native Chrome yang memanggil: --parent-window=<decimal handle value>. Hal ini memungkinkan host
pesan native membuat jendela UI native yang induk dengan benar. Perhatikan bahwa nilai ini akan
menjadi 0 jika konteks panggilan adalah pekerja layanan.
Saat port pesan dibuat menggunakan runtime.connectNative(), Chrome memulai proses
host pesan native dan terus berjalan hingga port dihancurkan. Di sisi lain, saat pesan
dikirim menggunakan runtime.sendNativeMessage(), tanpa membuat port pesan, Chrome akan memulai
proses host pesan native baru untuk setiap pesan. Dalam hal ini, pesan pertama yang dihasilkan oleh proses
host ditangani sebagai respons terhadap permintaan asli, dan Chrome akan meneruskannya ke callback
respons yang ditentukan saat runtime.sendNativeMessage() dipanggil. Dalam kasus tersebut, semua pesan lain yang dibuat oleh
host pesan native akan diabaikan.
Menghubungkan ke aplikasi native
Mengirim dan menerima pesan ke dan dari aplikasi native sangat mirip dengan pesan lintas ekstensi. Perbedaan utamanya adalah runtime.connectNative() digunakan, bukan
runtime.connect(), dan runtime.sendNativeMessage() digunakan, bukan
runtime.sendMessage().
Untuk menggunakan metode ini, izin "nativeMessaging" harus dideklarasikan dalam file manifes ekstensi Anda.
Metode ini tidak tersedia di dalam skrip konten, hanya di dalam halaman ekstensi dan pekerja layanan Anda. Jika Anda ingin berkomunikasi dari skrip konten ke aplikasi native, kirim pesan ke pekerja layanan untuk meneruskannya ke aplikasi native.
Contoh berikut membuat objek runtime.Port yang terhubung ke host pesan native
com.my_company.my_application, mulai memproses pesan dari port tersebut, dan mengirim satu pesan
keluar:
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'});
Gunakan runtime.sendNativeMessage untuk mengirim pesan ke aplikasi native tanpa
membuat port, misalnya:
chrome.runtime.sendNativeMessage(
'com.my_company.my_application',
{text: 'Hello'},
function (response) {
console.log('Received ' + response);
}
);
Men-debug pesan native
Jika terjadi kegagalan pesan native tertentu, output akan ditulis ke log error Chrome. Hal ini termasuk
ketika host pesan native gagal memulai, menulis ke stderr, atau melanggar protokol komunikasi. Di
Linux dan macOS, log ini dapat diakses dengan memulai Chrome dari command line dan melihat
output-nya di terminal. Di Windows, gunakan --enable-logging seperti yang dijelaskan pada Cara mengaktifkan logging.
Berikut adalah beberapa kesalahan umum dan tips untuk mengatasinya:
Gagal memulai host pesan native.
Periksa apakah Anda memiliki izin yang memadai untuk menjalankan file host pesan native.
Nama host pesan native yang ditentukan tidak valid.
Periksa apakah nama berisi karakter yang tidak valid. Hanya boleh berisi karakter alfanumerik huruf kecil, garis bawah, dan titik. Nama tidak boleh diawali atau diakhiri dengan titik, dan titik tidak boleh diikuti dengan titik lain.
Host native telah keluar.
Pipa ke host pesan native rusak sebelum pesan dibaca oleh Chrome. Hal ini kemungkinan besar dimulai dari host pesan native Anda.
Host pesan native yang ditentukan tidak ditemukan.
Periksa hal-hal berikut:
- Apakah nama dieja dengan benar di ekstensi dan di file manifes?
- Apakah manifes berada di direktori yang tepat dan dengan nama yang benar? Lihat lokasi host pesan native untuk mengetahui format yang diharapkan.
- Apakah file manifes dalam format yang benar? Secara khusus, apakah JSON valid dan tersusun dengan baik, serta apakah nilainya sesuai dengan definisi manifes host pesan native?
- Apakah file yang ditentukan di
pathada? Di Windows, jalur dapat bersifat relatif, tetapi di macOS dan Linux, jalur harus bersifat absolut.
Nama host host pesan native tidak terdaftar. (Khusus Windows)
Host pesan native tidak ditemukan di registry Windows. Periksa kembali menggunakan regedit
apakah kunci sudah benar-benar dibuat dan cocok dengan format yang diperlukan seperti yang didokumentasikan di lokasi
host pesan native.
Akses ke host pesan native yang ditentukan dilarang.
Apakah asal ekstensi tercantum di allowed_origins?
Error saat berkomunikasi dengan host pesan native.
Hal ini menunjukkan implementasi protokol komunikasi yang salah di host fitur pesan native.
- Pastikan semua output di
stdoutmematuhi protokol pesan native. Jika Anda ingin mencetak beberapa data untuk tujuan proses debug, tulis kestderr. - Pastikan panjang pesan 32-bit dalam format bilangan bulat native platform (little-endian / big-endian).
- Panjang pesan tidak boleh melebihi 1024*1024.
- Ukuran pesan harus sama dengan jumlah byte dalam pesan. Hal ini mungkin berbeda dengan "panjang" string, karena karakter dapat direpresentasikan oleh beberapa byte.
- Khusus Windows: Pastikan mode I/O program disetel ke
O_BINARY. Secara default, mode I/O adalahO_TEXT, yang merusak format pesan karena akhir baris (\n=0A) diganti dengan akhir baris bergaya Windows (\r\n=0D 0A). Mode I/O dapat ditetapkan menggunakan__setmode.