Ekstensi dan aplikasi 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 mengetahui cara 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 menginstal file manifes yang menentukan konfigurasi host pesan native. Berikut adalah contoh file manifes:
{
"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:
Nama | Deskripsi |
---|---|
name | Nama host pesan native. Klien meneruskan string ini ke runtime.connectNative atau runtime.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 lainnya. |
description | Deskripsi singkat aplikasi. |
path | Jalur ke biner host pesan native. Di Linux dan OSX, jalur harus mutlak. Di Windows, hal ini dapat relatif terhadap direktori tempat file manifes berada. 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. Saat ini hanya ada satu nilai yang memungkinkan untuk parameter ini: stdio . Ini menunjukkan bahwa Chrome harus menggunakan stdin dan stdout untuk berkomunikasi dengan host. |
allowed_origins | Daftar ekstensi yang seharusnya memiliki akses ke host pesan native. Karakter pengganti seperti chrome-extension://*/* tidak diizinkan. |
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
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 OS X 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 dalam
direktori profil pengguna yang disebut NativeMessagingHosts
.
- OS X (seluruh sistem)
- Google Chrome:
/Library/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
- Kromium:
/Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
- Google Chrome:
- OS X (jalur default khusus pengguna)
- Google Chrome:
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
- Kromium:
~/Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
- Google Chrome:
- Linux (seluruh sistem)
- Google Chrome:
/etc/opt/chrome/native-messaging-hosts/_com.my_company.my_application_.json
- Kromium:
/etc/chromium/native-messaging-hosts/_com.my_company.my_application_.json
- Google Chrome:
- Linux (jalur default khusus pengguna)
- Google Chrome:
~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
- Kromium:
~/.config/chromium/NativeMessagingHosts/_com.my_company.my_application_.json
- Google Chrome:
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 dalam
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.
Peringatan: Di Windows, pada Chrome 54 dan yang lebih lama, origin diteruskan sebagai parameter kedua,
bukan parameter pertama.
Saat port pesan dibuat menggunakan runtime.connectNative, Chrome 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, yaitu 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.
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 halaman skrip latar belakang.
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. Metode ini hanya dapat digunakan jika izin "nativeMessaging" dideklarasikan dalam file manifes aplikasi Anda.
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" });
runtime.sendNativeMessage dapat digunakan 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 host pesan native gagal dimulai, menulis ke stderr
atau jika melanggar
protokol komunikasi, output akan dituliskan ke log error Chrome. Di Linux dan OS X, log ini
dapat diakses dengan mudah dengan memulai Chrome dari command line dan mengamati outputnya di
terminal. Di Windows, gunakan --enable-logging
seperti yang dijelaskan di Cara mengaktifkan logging.
Berikut adalah beberapa error dan tips untuk mengatasi masalah tersebut:
- Gagal memulai host pesan native.
- Periksa apakah Anda memiliki izin yang memadai untuk mengeksekusi file.
- 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 diizinkan. 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.
- Apakah nama dieja dengan benar di ekstensi dan di file manifes?
- Apakah manifes dimasukkan ke 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 sintaksis JSON sudah benar dan apakah nilainya cocok dengan definisi manifes host pesan native?
- Apakah file yang ditentukan dalam
path
ada? Di Windows, jalur mungkin bersifat relatif, tetapi di OS X 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.
- Host pesan native tidak ditemukan di registry Windows. Periksa kembali menggunakan
- Akses ke host pesan native yang ditentukan dilarang.
- Apakah asal ekstensi tercantum dalam
allowed_origins
?
- Apakah asal ekstensi tercantum dalam
- Terjadi error saat berkomunikasi dengan host pesan native.
- Hal ini merupakan error yang sangat umum dan menunjukkan penerapan protokol komunikasi yang tidak tepat dalam host pesan native.
- Pastikan semua output di
stdout
mematuhi 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
.