Ekstensi dapat bertukar pesan dengan aplikasi native menggunakan API yang serupa 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 streaming input dan 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 dapat diikuti oleh titik lainnya. description- Deskripsi singkat aplikasi.
path- Jalur ke biner host pesan native. Di Linux dan macOS, jalurnya harus absolut. Di Windows, hal ini dapat relatif terhadap direktori yang berisi file manifes. Proses {i>host<i} dimulai dengan direktori saat ini yang diatur ke direktori yang berisi biner {i>host<i}. Misalnya, jika parameter ini disetel ke
C:\Application\nm_host.exe, parameter ini 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. Ini menunjukkan bahwa Chrome harus menggunakanstdindanstdoutuntuk berkomunikasi dengan host. allowed_origins- Daftar ekstensi yang akan 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, entah
HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application atau
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, dengan 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, pertama-tama registry 32-bit akan dikueri, kemudian 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 diperiksa di lokasi tetap, sedangkan host pesan native tingkat pengguna dicari di subdirektori NativeMessagingHosts/
dari 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 ke
kedua arah; setiap pesan diserialisasi menggunakan JSON, berenkode 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 agar tidak berperilaku buruk di aplikasi native. 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 pesan native mengidentifikasi sumber pesan saat beberapa ekstensi ditentukan dalam kunci allowed_origins di manifes host pesan native.
Di Windows, host pesan native juga diberi argumen command line dengan handle ke
jendela native Chrome yang melakukan panggilan: --parent-window=<decimal handle value>. Hal ini memungkinkan host
pesan native membuat jendela UI native yang diinduki dengan benar. Perhatikan bahwa nilai ini akan menjadi 0 jika konteks panggilan adalah pekerja layanan.
Saat port pesan dibuat menggunakan runtime.connectNative(), Chrome akan memulai proses host
pesan native dan terus menjalankannya hingga port dihancurkan. Di sisi lain, saat pesan dikirim menggunakan runtime.sendNativeMessage() tanpa membuat port pesan, Chrome akan memulai proses host pesan native yang 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. Semua pesan lain yang dibuat oleh
host pesan native dalam kasus tersebut 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 sebagai ganti
runtime.connect(), dan runtime.sendNativeMessage() digunakan sebagai ganti
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
Ketika kegagalan pesan native tertentu terjadi, output akan dituliskan ke log error Chrome. Hal ini termasuk
saat 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 mengamati
output-nya di terminal. Di Windows, gunakan --enable-logging seperti yang dijelaskan di Cara mengaktifkan logging.
Berikut adalah beberapa kesalahan umum dan tips untuk menyelesaikannya:
Gagal memulai host pesan native.
Periksa apakah Anda memiliki izin yang memadai untuk mengeksekusi file host pesan native.
Nama host pesan native yang ditentukan tidak valid.
Periksa apakah nama berisi karakter yang tidak valid. Hanya karakter alfanumerik huruf kecil, garis bawah, dan titik yang diperbolehkan. Nama tidak boleh diawali atau diakhiri dengan titik, dan titik tidak boleh diikuti dengan titik lainnya.
Host native telah keluar.
Pipe 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 format yang diharapkan.
- Apakah file manifes dalam format yang benar? Secara khusus, apakah JSON valid dan tersusun dengan baik, dan apakah nilainya cocok dengan definisi manifes host pesan native?
- Apakah file yang ditentukan dalam
pathada? Di Windows, jalur mungkin bersifat relatif, tetapi di macOS dan Linux, jalur tersebut harus absolut.
Nama host host pesan native tidak terdaftar. (Khusus Windows)
Host pesan native tidak ditemukan di registry Windows. Periksa kembali menggunakan regedit
apakah kunci 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 dalam allowed_origins?
Terjadi error saat berkomunikasi dengan host pesan native.
Hal ini menunjukkan penerapan protokol komunikasi yang salah di host 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 menggunakan format bilangan bulat native platform (little-endian/big-endian).
- Panjang pesan tidak boleh lebih dari 1024*1024.
- Ukuran pesan harus sama dengan jumlah byte dalam pesan. Nilai 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 sebagai jeda baris (\n=0A) diganti dengan akhiran baris gaya Windows (\r\n=0D 0A). Mode I/O dapat disetel menggunakan__setmode.