Pesan native

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() 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 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 menggunakan stdin dan stdout untuk berkomunikasi dengan host.
allowed_origins
Daftar ekstensi yang akan memiliki akses ke host pesan native. Nilai allowed-origins tidak 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 path ada? 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 stdout mematuhi protokol pesan native. Jika Anda ingin mencetak beberapa data untuk tujuan proses debug, tulis ke stderr.
  • 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 adalah O_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.