Fitur Pesan Native

Ekstensi dan aplikasi dapat bertukar pesan dengan aplikasi native menggunakan API yang mirip dengan API penerusan pesan lainnya. Aplikasi bawaan yang mendukung fitur ini harus mendaftarkan host pesan native yang mengetahui cara berkomunikasi dengan ekstensi. Chrome memulai host di proses terpisah dan berkomunikasi dengannya menggunakan aliran input standar dan {i>output<i} 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:

Lokasi host pesan native

Lokasi file manifes bergantung pada platform.

Di Windows, file manifes dapat ditempatkan di mana saja dalam sistem file. Aplikasi penginstal 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 menyetel nilai {i>default<i} dari 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, pertama-tama registry 32-bit akan dikueri, lalu 64-bit {i>registry<i}.

Di OS X dan Linux, lokasi file manifes host pesan native berbeda-beda menurut browser Anda (Google Chrome atau Chromium). Host pesan native seluruh sistem diperiksa pada sementara host pesan native tingkat pengguna dicari di subdirektori dalam direktori profil pengguna bernama 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
• 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
• 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
• 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

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 JSON, berenkode UTF-8 dan didahului dengan 32-bit panjang pesan dalam urutan byte native. Ukuran maksimum satu pesan dari pesan native adalah 1 MB, terutama untuk melindungi Chrome agar tidak mengganggu aplikasi asli. Ukuran maksimum pesan yang dikirim ke host pesan native adalah 4 GB.

Argumen pertama untuk host pesan native adalah asal pemanggil, biasanya chrome-extension://[ID of allowed extension]. Hal ini memungkinkan host pesan native mengidentifikasi sumber pesan jika beberapa ekstensi ditentukan dalam kunci allowed_origins di manifes host pesan native. Peringatan: Di Windows, di Chrome 54 dan yang lebih lama, origin diteruskan sebagai parameter kedua bukannya parameter pertama.

Saat port pesan dibuat menggunakan runtime.connectNative, Chrome akan memulai pesan native {i>host<i} dan menjaganya tetap berjalan sampai porta dihancurkan. Di sisi lain, ketika sebuah pesan dikirim menggunakan runtime.sendNativeMessage, tanpa membuat port pesan, Chrome akan memulai proses {i>host<i} pesan asli untuk setiap pesan. Dalam hal ini, pesan pertama yang dibuat oleh host ditangani sebagai respons terhadap permintaan asli, yaitu Chrome akan meneruskannya ke respons callback yang ditentukan saat runtime.sendNativeMessage dipanggil. Semua pesan lainnya yang dibuat oleh host pesan native dalam kasus tersebut akan diabaikan.

Di Windows, host pesan native juga meneruskan argumen command line dengan handle ke memanggil jendela native Chrome: --parent-window=<decimal handle value>. Hal ini memungkinkan native {i>host<i} pesan membuat jendela UI native yang induk dengan benar. Perhatikan bahwa nilai ini akan 0 jika konteks panggilan adalah halaman skrip latar belakang.

Menghubungkan ke aplikasi native

Mengirim dan menerima pesan ke dan dari aplikasi asli sangat mirip dengan ekstensi silang untuk mengirim pesan. Perbedaan utamanya adalah runtime.connectNative digunakan, bukan runtime.connect, dan runtime.sendNativeMessage digunakan, bukan runtime.sendMessage. Metode ini hanya dapat digunakan jika "nativeMessaging" izin dideklarasikan dalam elemen manifes.

Contoh Berikut membuat objek runtime.Port yang terhubung ke host pesan native com.my_company.my_application, mulai memproses pesan dari port tersebut dan mengirimkan satu pesan keluar pesan:

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 membuatnya 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, tulis ke stderr atau jika melanggar protokol komunikasi, {i>output<i} ditulis ke log error Chrome. Pada Linux dan OS X, log ini dapat dengan mudah diakses dengan memulai Chrome dari baris perintah dan melihat {i>outputnya<i} di terminal. Di Windows, gunakan --enable-logging seperti yang dijelaskan pada 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 menjalankan 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 diperbolehkan. Nama tidak boleh diawali atau diakhiri dengan titik, dan titik tidak boleh diikuti oleh titik lain.
• Host native telah keluar.
  • Pipa ke host pesan native rusak sebelum pesan dibaca oleh Chrome. Ini adalah kemungkinan dimulai dari host pesan native.
• Host pesan native yang ditentukan tidak ditemukan.
  • Apakah nama dieja dengan benar dalam ekstensi dan file manifes?
  • Apakah manifes ditempatkan di direktori yang benar dan dengan nama yang benar? Lihat host pesan native lokasi untuk format yang diharapkan.
  • Apakah file manifes dalam format yang benar? Secara khusus, apakah sintaks JSON sudah benar dan apakah cocok dengan definisi manifes host pesan native?
  • Apakah file yang ditentukan di path ada? Pada Windows, jalur mungkin relatif, tetapi pada OS X dan Linux, jalurnya harus absolut.
• Nama host host pesan native tidak terdaftar. (Khusus Windows)
  • Host pesan native tidak ditemukan dalam registry Windows. Periksa kembali menggunakan regedit apakah kunci telah benar-benar dibuat dan sesuai dengan format yang diperlukan seperti yang didokumentasikan di lokasi host pesan.
• Akses ke host pesan native yang ditentukan dilarang.
  • Apakah asal ekstensi tercantum di allowed_origins?
• Terjadi error saat berkomunikasi dengan host pesan native.
  • Ini adalah kesalahan yang sangat umum dan menunjukkan implementasi protokol komunikasi yang salah di host pesan native.
  • Pastikan semua output di stdout mematuhi protokol pesan native. Jika Anda ingin untuk mencetak beberapa data untuk tujuan proses debug, tulis ke stderr.
  • Pastikan panjang pesan 32-bit menggunakan format integer native platform (little-endian) / big-endian).
  • Panjang pesan tidak boleh lebih dari 1024*1024.
  • Ukuran pesan harus sama dengan jumlah byte dalam pesan. Ini mungkin berbeda dari "panjang" sebuah {i>string<i}, karena karakter dapat diwakili oleh beberapa {i>byte<i}.
  • Khusus Windows: Pastikan mode I/O program disetel ke O_BINARY. Secara {i>default<i}, I/O adalah O_TEXT, yang merusak format pesan saat jeda baris (\n = 0A) diganti dengan Akhir baris bergaya Windows (\r\n = 0D 0A). Mode I/O dapat disetel menggunakan __setmode.