Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

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. Hal ini menunjukkan bahwa Chrome harus menggunakan stdin dan stdout untuk berkomunikasi dengan host.
allowed_origins: Daftar ekstensi yang harus 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 berada di mana saja dalam sistem file. Penginstal aplikasi harus membuat kunci registry, 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, Chrome for Testing, atau Chromium). Host pesan native di seluruh sistem dicari 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; Google Chrome for Testing: /Library/Google/ChromeForTesting/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; Google Chrome for Testing: ~/Library/Application Support/Google/ChromeForTesting/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; Google Chrome for Testing: /etc/opt/chrome_for_testing/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; Google Chrome for Testing: ~/.config/google-chrome-for-testing/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 pesan native mengidentifikasi sumber pesan saat beberapa ekstensi ditentukan dalam kunci allowed_origins di manifes host 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 dengan benar. Perhatikan bahwa nilai ini akan 0 jika konteks pemanggil adalah service worker.

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 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 service worker ekstensi Anda. Untuk berkomunikasi dari skrip konten ke aplikasi native, kirim pesan ke service worker Anda 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:

const port = chrome.runtime.connectNative('com.my_company.my_application');
port.onMessage.addListener((msg) => {
  console.log('Received', msg);
});
port.onDisconnect.addListener(() => {
  if (chrome.runtime.lastError) {
    console.error(
      'Disconnected due to error:',
      chrome.runtime.lastError.message
    );
  } else {
    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'},
  (response) => {
    if (chrome.runtime.lastError) {
      console.error(
        'Error sending native message:',
        chrome.runtime.lastError.message
      );
      return;
    }
    console.log('Received', response);
  }
);

Men-debug pesan native

Jika terjadi kegagalan pesan native, output diagnostik akan ditulis ke log error Chrome.

Linux and macOS

# Linux
google-chrome --enable-logging=stderr --log-level=1 2>&1 | \
  grep -E "native_messag|launch_context"

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --enable-logging=stderr --log-level=1 2>&1 | \
  grep -E "native_messag|launch_context"

Windows

Luncurkan Chrome dengan logging diaktifkan:

chrome.exe --enable-logging --log-level=1

Teruskan --user-data-dir="%TEMP%\nm-debug" untuk meluncurkan instance terpisah tanpa melampirkan ke proses Chrome yang ada.

Untuk melihat output, streaming chrome_debug.log menggunakan PowerShell:

$log = "$env:LOCALAPPDATA\Google\Chrome\User Data\chrome_debug.log"
Get-Content -Wait $log | Select-String "native_messag|launch_context"

Anda juga dapat membuka chrome_debug.log di editor teks dan menelusuri launch_context.cc atau native_message_process_host.cc.

Detail logging kunci

Kegagalan penelusuran dan penguraian manifes di launch_context.cc dicatat sebagai peringatan. Gunakan --log-level=1, bukan 2 (ERROR), yang akan menekan diagnostik startup ini.
Telusuri launch_context untuk menemukan error peluncuran manifes dan biner, serta native_messag untuk menemukan error komunikasi saluran dan ukuran payload.

Error yang biasa terjadi

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 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?
Di Windows, apakah kunci registri ada di HKEY_CURRENT_USER atau HKEY_LOCAL_MACHINE, dan apakah nilai defaultnya mengarah ke jalur manifes lengkap? Chrome membuat kueri tampilan registri 32-bit terlebih dahulu, lalu tampilan 64-bit. Gunakan regedit untuk memverifikasi kunci. Lihat lokasi host pesan native.
Di macOS dan Linux, apakah file manifes berada di direktori yang diharapkan dan diberi nama sesuai dengan host (seperti com.my_company.my_application.json)? Lihat lokasi host pesan native.
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.

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