Fitur Pesan Native

Penting: Chrome akan menghapus dukungan untuk Aplikasi Chrome di semua platform. Browser Chrome dan Chrome Web Store akan terus mendukung ekstensi. Baca pengumumannya dan pelajari lebih lanjut cara memigrasikan aplikasi.

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
• 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 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.
• 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 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 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.