Halaman ini diterjemahkan oleh Cloud Translation API.

Pesan native

Ekstensi dapat bertukar pesan dengan aplikasi native menggunakan API yang mirip 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 aliran input standar dan output standar.

Host pesan native

Untuk mendaftarkan host pesan native, aplikasi harus menyimpan file yang menentukan konfigurasi host pesan native.

Contoh file-nya 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 boleh diikuti dengan titik lain.
description: Deskripsi singkat aplikasi.
path: Jalur ke biner host pesan native. Di Linux dan macOS, jalur harus bersifat absolut. Di Windows, jalur dapat bersifat relatif terhadap direktori yang berisi file manifes. Proses host dimulai dengan direktori saat ini yang ditetapkan ke direktori yang berisi biner host. Misalnya, jika parameter ini disetel ke C:\Application\nm_host.exe, maka 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. Header ini menunjukkan bahwa Chrome harus menggunakan stdin dan stdout untuk berkomunikasi dengan host.
allowed_origins: Daftar ekstensi yang harus memiliki akses ke host fitur 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 berada di mana saja dalam sistem file. Penginstal aplikasi harus membuat kunci registri, baik HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application maupun HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application, dan menetapkan nilai default kunci tersebut ke jalur lengkap 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 registry 64-bit.

Di macOS dan Linux, lokasi file manifes host pesan native bervariasi menurut browser (Google Chrome atau Chromium). Host fitur pesan native di seluruh sistem dicari di lokasi tetap, sedangkan host fitur 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 (khusus pengguna, jalur default): 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 (di 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 (khusus pengguna, jalur default): 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 di kedua arah; setiap pesan diserialisasi menggunakan JSON, dienkode UTF-8, dan diawali dengan panjang pesan 32-bit dalam urutan byte native. Ukuran maksimum satu pesan dari host pesan native adalah 1 MB, terutama untuk melindungi Chrome dari aplikasi native yang berperilaku tidak semestinya. Ukuran maksimum pesan yang dikirim ke host pesan native adalah 64 MiB.

Argumen pertama ke host pesan native adalah asal pemanggil, biasanya chrome-extension://[ID of allowed extension]. Hal ini memungkinkan host fitur pesan native mengidentifikasi sumber pesan saat beberapa ekstensi ditentukan dalam kunci allowed_origins di manifes host fitur pesan native.

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

Saat port pesan dibuat menggunakan runtime.connectNative(), Chrome akan memulai proses host pesan native dan membuatnya tetap berjalan hingga port dihancurkan. Di sisi lain, saat pesan dikirim menggunakan runtime.sendNativeMessage(), tanpa membuat port pesan, Chrome akan memulai proses host pesan native 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 pengiriman pesan antar-ekstensi. Perbedaan utamanya adalah runtime.connectNative() digunakan, bukan runtime.connect(), dan runtime.sendNativeMessage() digunakan, bukan 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 dan pekerja layanan ekstensi 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

Saat kegagalan pesan native tertentu terjadi, output akan ditulis ke log error Chrome. Hal ini mencakup saat host fitur pesan native gagal dimulai, menulis ke stderr, atau melanggar protokol komunikasi. Di Linux dan macOS, log ini dapat diakses dengan memulai Chrome dari command line dan melihat outputnya di terminal. Di Windows, gunakan --enable-logging seperti yang dijelaskan di Cara mengaktifkan logging.

Berikut beberapa error umum dan tips untuk mengatasinya:

Gagal memulai host pesan native.

Periksa apakah Anda memiliki izin yang memadai untuk menjalankan 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 diizinkan. Nama tidak boleh diawali atau diakhiri dengan titik, dan titik tidak boleh diikuti dengan titik lain.

Host native telah keluar.

Saluran ke host pesan native rusak sebelum pesan dibaca oleh Chrome. Hal ini kemungkinan besar dimulai dari host fitur 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 mengetahui format yang diharapkan.
Apakah file manifes dalam format yang benar? Khususnya, apakah JSON valid dan tersusun dengan baik, serta apakah nilai cocok dengan definisi manifes host pesan native?
Apakah file yang ditentukan dalam path ada? Di Windows, jalur dapat bersifat relatif, tetapi di macOS dan Linux, jalur harus bersifat absolut.

Nama host host name host pesan native tidak terdaftar. (Khusus Windows)

Host fitur pesan native tidak ditemukan di registri 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 origin ekstensi tercantum di allowed_origins?

Terjadi error saat berkomunikasi dengan host pesan native.

Hal ini menunjukkan penerapan protokol komunikasi yang salah di host fitur 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 dalam format bilangan bulat native platform (little-endian / big-endian).
Panjang pesan tidak boleh melebihi 1024*1024.
Ukuran pesan harus sama dengan jumlah byte dalam pesan. Hal 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 karena jeda baris (\n = 0A) diganti dengan akhir baris gaya Windows (\r\n = 0D 0A). Mode I/O dapat ditetapkan menggunakan __setmode.

Pesan native Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.