chrome.runtime

Deskripsi

Gunakan chrome.runtime API untuk mengambil pekerja layanan, menampilkan detail tentang manifes, serta memproses dan merespons peristiwa dalam siklus proses ekstensi. Anda juga dapat menggunakan API ini untuk mengonversi jalur relatif URL menjadi URL yang sepenuhnya memenuhi syarat.

Ringkasan

Runtime API menyediakan metode untuk mendukung sejumlah area fungsi yang dapat digunakan ekstensi Anda:

Penerusan pesan

Ekstensi Anda dapat berkomunikasi dengan konteks yang berbeda dalam ekstensi Anda dan juga dengan ekstensi lain menggunakan metode dan peristiwa ini: connect(), onConnect, onConnectExternal, sendMessage(), onMessage, dan onMessageExternal. Selain itu, ekstensi Anda dapat meneruskan pesan ke aplikasi native di perangkat pengguna menggunakan connectNative() dan sendNativeMessage().

Catatan: Lihat Penerusan Pesan untuk mengetahui ringkasan subjek.

Mengakses metadata ekstensi dan platform

Metode ini memungkinkan Anda mengambil beberapa bagian metadata tertentu tentang ekstensi dan platform. Metode dalam kategori ini mencakup getManifest(), dan getPlatformInfo().

Mengelola opsi dan siklus proses ekstensi

Properti ini memungkinkan Anda melakukan beberapa meta-operasi pada ekstensi, dan menampilkan halaman opsi. Metode dan peristiwa dalam kategori ini mencakup onInstalled, onStartup, openOptionsPage(), reload(), requestUpdateCheck(), dan setUninstallURL().

Utilitas bantuan

Metode ini menyediakan utilitas seperti konversi representasi resource internal ke format eksternal. Metode dalam kategori ini mencakup getURL().

Utilitas mode kios

Metode ini hanya tersedia di ChromeOS, dan terutama ada untuk mendukung penerapan kios. Metode dalam kategori ini mencakup restart dan restartAfterDelay.

Izin

Sebagian besar metode di Runtime API tidak memerlukan izin apa pun, kecuali untuk sendNativeMessage dan connectNative, yang memerlukan izin nativeMessaging.

Manifes

Contoh berikut menunjukkan cara mendeklarasikan izin nativeMessaging dalam manifes:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

Kasus penggunaan

Menambahkan gambar ke halaman web

Agar dapat mengakses aset yang dihosting di domain lain, halaman web harus menentukan URL lengkap resource (misalnya, <img src="https://example.com/logo.png">). Hal yang sama berlaku untuk menyertakan aset ekstensi di halaman web. Dua perbedaannya adalah aset ekstensi harus diekspos sebagai resource yang dapat diakses web dan biasanya skrip konten bertanggung jawab untuk memasukkan aset ekstensi.

Dalam contoh ini, ekstensi akan menambahkan logo.png ke halaman tempat skrip konten dimasukkan menggunakan runtime.getURL() untuk membuat URL yang sepenuhnya memenuhi syarat. Namun, pertama-tama, aset harus dideklarasikan sebagai resource yang dapat diakses web dalam manifes.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

Mengirim data dari pekerja layanan ke skrip konten

Skrip konten ekstensi biasanya memerlukan data yang dikelola oleh bagian lain ekstensi, seperti pekerja layanan. Sama seperti dua jendela browser yang dibuka ke halaman web yang sama, kedua konteks ini tidak dapat langsung mengakses nilai satu sama lain. Sebagai gantinya, ekstensi dapat menggunakan pengiriman pesan untuk berkoordinasi di berbagai konteks ini.

Dalam contoh ini, skrip konten memerlukan beberapa data dari pekerja layanan ekstensi untuk melakukan inisialisasi UI-nya. Untuk mendapatkan data ini, aplikasi meneruskan pesan get-user-data ke pekerja layanan, dan merespons dengan salinan informasi pengguna.

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

background.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

Mengumpulkan masukan tentang uninstal

Banyak ekstensi menggunakan survei pasca-penghapusan untuk memahami cara ekstensi dapat melayani penggunanya dengan lebih baik dan meningkatkan retensi. Contoh berikut menunjukkan cara menambahkan fungsi ini.

background.js:

chrome.runtime.onInstalled.addListener(details => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    chrome.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

Contoh ekstensi

Lihat demo Manifest V3 - Web Accessible Resources untuk mengetahui contoh Runtime API lainnya.

Jenis

ContextFilter

Chrome 114+

Filter untuk dicocokkan dengan konteks ekstensi tertentu. Konteks yang cocok harus cocok dengan semua filter yang ditentukan; filter apa pun yang tidak ditentukan akan cocok dengan semua konteks yang tersedia. Dengan demikian, filter `{}` akan cocok dengan semua konteks yang tersedia.

Properti

• contextIds

  string[] opsional

• contextTypes

  ContextType[] opsional

• documentIds

  string[] opsional

• documentOrigins

  string[] opsional

• documentUrls

  string[] opsional

• frameIds

  number[] opsional

• samaran

  boolean opsional

• tabIds

  number[] opsional

• windowIds

  number[] opsional

ContextType

Chrome 114+

Enum

"TAB"
Menentukan jenis konteks sebagai tab

"POPUP"
Menentukan jenis konteks sebagai jendela pop-up ekstensi

"BACKGROUND"
Menentukan jenis konteks sebagai pekerja layanan.

"OFFSCREEN_DOCUMENT"
Menentukan jenis konteks sebagai dokumen offscreen.

"SIDE_PANEL"
Menentukan jenis konteks sebagai panel samping.

"DEVELOPER_TOOLS"
Menentukan jenis konteks sebagai alat developer.

ExtensionContext

Chrome 114+

Konteks yang menghosting konten ekstensi.

Properti

• contextId

  string

  ID unik untuk konteks ini

• contextType

  ContextType

  Jenis konteks yang sesuai dengan ini.

• documentId

  string opsional

  UUID untuk dokumen yang terkait dengan konteks ini, atau tidak ditentukan jika konteks ini dihosting bukan dalam dokumen.

• documentOrigin

  string opsional

  Asal dokumen yang terkait dengan konteks ini, atau tidak ditentukan jika konteks tidak dihosting dalam dokumen.

• documentUrl

  string opsional

  URL dokumen yang terkait dengan konteks ini, atau tidak ditentukan jika konteks tidak dihosting dalam dokumen.

• frameId

  angka

  ID frame untuk konteks ini, atau -1 jika konteks ini tidak dihosting dalam frame.

• samaran

  boolean

  Apakah konteks dikaitkan dengan profil Samaran.

• tabId

  angka

  ID tab untuk konteks ini, atau -1 jika konteks ini tidak dihosting di tab.

• windowId

  angka

  ID jendela untuk konteks ini, atau -1 jika konteks ini tidak dihosting di jendela.

MessageSender

Objek yang berisi informasi tentang konteks skrip yang mengirim pesan atau permintaan.

Properti

• documentId

  string opsional

  Chrome 106+

  UUID dokumen yang membuka koneksi.

• documentLifecycle

  string opsional

  Chrome 106+

  Siklus proses dokumen yang membuka koneksi pada saat port dibuat. Perhatikan bahwa status siklus proses dokumen mungkin telah berubah sejak pembuatan port.

• frameId

  number opsional

  Frame yang membuka koneksi. 0 untuk frame tingkat atas, positif untuk frame turunan. Kolom ini hanya akan ditetapkan saat tab ditetapkan.

• id

  string opsional

  ID ekstensi yang membuka koneksi, jika ada.

• nativeApplication

  string opsional

  Chrome 74+

  Nama aplikasi native yang membuka koneksi, jika ada.

• asal

  string opsional

  Chrome 80+

  Asal halaman atau frame yang membuka koneksi. URL ini dapat bervariasi dari properti URL (misalnya, about:blank) atau dapat buram (misalnya, iframe dengan sandbox). Hal ini berguna untuk mengidentifikasi apakah asal dapat dipercaya jika kita tidak dapat langsung mengetahuinya dari URL.

• tab

  Tab opsional

  tabs.Tab yang membuka koneksi, jika ada. Properti ini hanya akan ada jika koneksi dibuka dari tab (termasuk skrip konten), dan hanya jika penerima adalah ekstensi, bukan aplikasi.

• tlsChannelId

  string opsional

  ID saluran TLS halaman atau frame yang membuka koneksi, jika diminta oleh ekstensi, dan jika tersedia.

• url

  string opsional

  URL halaman atau frame yang membuka koneksi. Jika pengirim berada dalam iframe, URL-nya akan berupa URL iframe, bukan URL halaman yang menghostingnya.

OnInstalledReason

Chrome 44+

Alasan peristiwa ini dikirim.

Enum

"install"
Menentukan alasan peristiwa sebagai penginstalan.

"update"
Menentukan alasan peristiwa sebagai update ekstensi.

"chrome_update"
Menentukan alasan peristiwa sebagai update Chrome.

"shared_module_update"
Menentukan alasan peristiwa sebagai update pada modul bersama.

OnRestartRequiredReason

Chrome 44+

Alasan peristiwa dikirim. 'app_update' digunakan saat mulai ulang diperlukan karena aplikasi diupdate ke versi yang lebih baru. 'os_update' digunakan saat mulai ulang diperlukan karena browser/OS diupdate ke versi yang lebih baru. 'periodik' digunakan saat sistem berjalan lebih dari waktu aktif yang diizinkan yang ditetapkan dalam kebijakan perusahaan.

Enum

"app_update"
Menentukan alasan peristiwa sebagai update pada aplikasi.

"os_update"
Menentukan alasan peristiwa sebagai update pada sistem operasi.

"periodic"
Menentukan alasan peristiwa sebagai mulai ulang aplikasi secara berkala.

PlatformArch

Chrome 44+

Arsitektur prosesor mesin.

Enum

"arm"
Menentukan arsitektur prosesor sebagai arm.

"arm64"
Menentukan arsitektur prosesor sebagai arm64.

"x86-32"
Menentukan arsitektur prosesor sebagai x86-32.

"x86-64"
Menentukan arsitektur prosesor sebagai x86-64.

"mips"
Menentukan arsitektur prosesor sebagai mips.

"mips64"
Menentukan arsitektur prosesor sebagai mips64.

PlatformInfo

Objek yang berisi informasi tentang platform saat ini.

Properti

• arch

  PlatformArch

  Arsitektur prosesor mesin.

• nacl_arch

  PlatformNaclArch

  Arsitektur klien native. Hal ini mungkin berbeda dengan arch di beberapa platform.

• os

  PlatformOs

  Sistem operasi yang menjalankan Chrome.

PlatformNaclArch

Chrome 44+

Arsitektur klien native. Hal ini mungkin berbeda dengan arch di beberapa platform.

Enum

"arm"
Menentukan arsitektur klien native sebagai arm.

"x86-32"
Menentukan arsitektur klien native sebagai x86-32.

"x86-64"
Menentukan arsitektur klien native sebagai x86-64.

"mips"
Menentukan arsitektur klien native sebagai mips.

"mips64"
Menentukan arsitektur klien native sebagai mips64.

PlatformOs

Chrome 44+

Sistem operasi yang menjalankan Chrome.

Enum

"mac"
Menentukan sistem operasi MacOS.

"win"
Menentukan sistem operasi Windows.

"android"
Menentukan sistem operasi Android.

"cros"
Menentukan sistem operasi Chrome.

"linux"
Menentukan sistem operasi Linux.

"openbsd"
Menentukan sistem operasi OpenBSD.

"fuchsia"
Menentukan sistem operasi Fuchsia.

Port

Objek yang memungkinkan komunikasi dua arah dengan halaman lain. Lihat Koneksi berumur panjang untuk mengetahui informasi selengkapnya.

Properti

• nama

  string

  Nama port, seperti yang ditentukan dalam panggilan ke runtime.connect.

• onDisconnect

  Peristiwa<functionvoidvoid>

  Diaktifkan saat port terputus dari ujung lainnya. runtime.lastError dapat ditetapkan jika port terputus karena error. Jika port ditutup melalui disconnect, peristiwa ini hanya diaktifkan di ujung lain. Peristiwa ini diaktifkan paling banyak sekali (lihat juga Masa aktif port).

  Fungsi onDisconnect.addListener terlihat seperti:

  (callback: function) => {...}

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (port: Port) => void

    • port

      Port

• onMessage

  Peristiwa<functionvoidvoid>

  Peristiwa ini diaktifkan saat postMessage dipanggil oleh ujung lain port.

  Fungsi onMessage.addListener terlihat seperti:

  (callback: function) => {...}

  • callback

    fungsi

    Parameter callback terlihat seperti:

    (message: any, port: Port) => void

    • pesan

      apa pun

    • port

      Port

• pengirim

  MessageSender opsional

  Properti ini hanya akan ada di port yang diteruskan ke pemroses onConnect / onConnectExternal / onConnectNative.

• berhenti hubungkan

  void

  Segera putuskan sambungan port. Memanggil disconnect() pada port yang sudah terputus tidak akan berpengaruh. Jika port terputus, tidak ada peristiwa baru yang akan dikirim ke port ini.

  Fungsi disconnect terlihat seperti:

  () => {...}

• postMessage

  void

  Kirim pesan ke ujung port lainnya. Jika port terputus, error akan ditampilkan.

  Fungsi postMessage terlihat seperti:

  (message: any) => {...}

  • pesan

    apa pun

    Chrome 52+

    Pesan yang akan dikirim. Objek ini harus dapat di-JSON.

RequestUpdateCheckStatus

Chrome 44+

Hasil pemeriksaan update.

Enum

"throttled"
Menunjukkan bahwa pemeriksaan status telah dibatasi. Hal ini dapat terjadi setelah pemeriksaan berulang dalam waktu singkat.

"no_update"
Menentukan bahwa tidak ada update yang tersedia untuk diinstal.

"update_available"
Menentukan bahwa ada update yang tersedia untuk diinstal.

Properti

id

ID ekstensi/aplikasi.

Jenis

string

lastError

Diisi dengan pesan error jika pemanggilan fungsi API gagal; jika tidak, tidak ditentukan. Ini hanya ditentukan dalam cakupan callback fungsi tersebut. Jika error dihasilkan, tetapi runtime.lastError tidak diakses dalam callback, pesan akan dicatat ke konsol yang mencantumkan fungsi API yang menghasilkan error. Fungsi API yang menampilkan promise tidak menetapkan properti ini.

Jenis

objek

Properti

• pesan

  string opsional

  Detail tentang error yang terjadi.

Metode

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
)

Mencoba menghubungkan pemroses dalam ekstensi (seperti halaman latar belakang), atau ekstensi/aplikasi lainnya. Hal ini berguna untuk skrip konten yang terhubung ke proses ekstensi, komunikasi antar-aplikasi/ekstensi, dan pesan web. Perhatikan bahwa tindakan ini tidak terhubung ke pemroses apa pun dalam skrip konten. Ekstensi dapat terhubung ke skrip konten yang disematkan di tab melalui tabs.connect.

Parameter

• extensionId

  string opsional

  ID ekstensi yang akan dihubungkan. Jika dihilangkan, koneksi akan dicoba dengan ekstensi Anda sendiri. Diperlukan jika mengirim pesan dari halaman web untuk pesan web.

• connectInfo

  objek opsional

  • includeTlsChannelId

    boolean opsional

    Apakah ID saluran TLS akan diteruskan ke onConnectExternal untuk proses yang memproses peristiwa koneksi.

  • nama

    string opsional

    Akan diteruskan ke onConnect untuk proses yang memproses peristiwa koneksi.

Hasil

• Port

  Port tempat pesan dapat dikirim dan diterima. Peristiwa onDisconnect port diaktifkan jika ekstensi tidak ada.

connectNative()

chrome.runtime.connectNative(
  application: string,
)

Menghubungkan ke aplikasi native di mesin host. Metode ini memerlukan izin "nativeMessaging". Lihat Pesan Native untuk mengetahui informasi selengkapnya.

Parameter

• aplikasi

  string

  Nama aplikasi terdaftar yang akan dihubungkan.

Hasil

• Port

  Port tempat pesan dapat dikirim dan diterima dengan aplikasi

getBackgroundPage()

Promise Khusus latar depan

chrome.runtime.getBackgroundPage(
  callback?: function,
)

Mengambil objek 'window' JavaScript untuk halaman latar belakang yang berjalan di dalam ekstensi/aplikasi saat ini. Jika halaman latar belakang adalah halaman peristiwa, sistem akan memastikan halaman tersebut dimuat sebelum memanggil callback. Jika tidak ada halaman latar belakang, error akan ditetapkan.

Parameter

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  (backgroundPage?: Window) => void

  • backgroundPage

    Periode opsional

    Objek 'window' JavaScript untuk halaman latar belakang.

Hasil

• Promise<Window | undefined>

  Chrome 99+

  Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

getContexts()

Promise Chrome 116+ MV3+

chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

Mengambil informasi tentang konteks aktif yang terkait dengan ekstensi ini

Parameter

• filter

  ContextFilter

  Filter untuk menemukan konteks yang cocok. Konteks cocok jika cocok dengan semua kolom yang ditentukan dalam filter. Semua kolom yang tidak ditentukan dalam filter cocok dengan semua konteks.

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  (contexts: ExtensionContext[]) => void

  • konteks

    ExtensionContext[]

    Konteks yang cocok, jika ada.

Hasil

• Promise<ExtensionContext[]>

  Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

getManifest()

chrome.runtime.getManifest()

Menampilkan detail tentang aplikasi atau ekstensi dari manifes. Objek yang ditampilkan adalah serialisasi file manifes lengkap.

Hasil

• objek

  Detail manifes.

getPackageDirectoryEntry()

Promise Khusus latar depan

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

Menampilkan DirectoryEntry untuk direktori paket.

Parameter

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  (directoryEntry: DirectoryEntry) => void

  • directoryEntry

    DirectoryEntry

Hasil

• Promise<DirectoryEntry>

  Chrome 122+

  Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

getPlatformInfo()

Promise

chrome.runtime.getPlatformInfo(
  callback?: function,
)

Menampilkan informasi tentang platform saat ini.

Parameter

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  (platformInfo: PlatformInfo) => void

  • platformInfo

    PlatformInfo

Hasil

• Promise<PlatformInfo>

  Chrome 99+

  Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

getURL()

chrome.runtime.getURL(
  path: string,
)

Mengonversi jalur relatif dalam direktori penginstalan aplikasi/ekstensi menjadi URL yang sepenuhnya memenuhi syarat.

Parameter

• jalur

  string

  Jalur ke resource dalam aplikasi/ekstensi yang dinyatakan relatif terhadap direktori penginstalannya.

Hasil

• string

  URL yang sepenuhnya memenuhi syarat ke resource.

openOptionsPage()

Promise

chrome.runtime.openOptionsPage(
  callback?: function,
)

Buka halaman opsi Ekstensi Anda, jika memungkinkan.

Perilaku yang tepat mungkin bergantung pada kunci options_ui atau options_page manifes Anda, atau apa yang didukung Chrome pada saat itu. Misalnya, halaman dapat dibuka di tab baru, dalam chrome://extensions, dalam Aplikasi, atau hanya memfokuskan halaman opsi yang terbuka. Hal ini tidak akan menyebabkan halaman pemanggil dimuat ulang.

Jika Ekstensi Anda tidak mendeklarasikan halaman opsi, atau Chrome gagal membuatnya karena alasan lain, callback akan menetapkan lastError.

Parameter

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  () => void

Hasil

• Promise<void>

  Chrome 99+

  Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

reload()

chrome.runtime.reload()

Memuat ulang aplikasi atau ekstensi. Metode ini tidak didukung dalam mode kios. Untuk mode kios, gunakan metode chrome.runtime.restart().

requestUpdateCheck()

Promise

chrome.runtime.requestUpdateCheck(
  callback?: function,
)

Meminta pemeriksaan update segera dilakukan untuk aplikasi/ekstensi ini.

Penting: Sebagian besar ekstensi/aplikasi tidak boleh menggunakan metode ini, karena Chrome sudah melakukan pemeriksaan otomatis setiap beberapa jam, dan Anda dapat memproses peristiwa runtime.onUpdateAvailable tanpa perlu memanggil requestUpdateCheck.

Metode ini hanya sesuai untuk dipanggil dalam situasi yang sangat terbatas, seperti jika ekstensi Anda berkomunikasi dengan layanan backend, dan layanan backend telah menentukan bahwa versi ekstensi klien sudah sangat lama dan Anda ingin meminta pengguna untuk mengupdatenya. Sebagian besar penggunaan requestUpdateCheck lainnya, seperti memanggilnya tanpa syarat berdasarkan timer berulang, mungkin hanya akan membuang-buang resource klien, jaringan, dan server.

Catatan: Saat dipanggil dengan callback, fungsi ini akan menampilkan dua properti sebagai argumen terpisah yang diteruskan ke callback, bukan menampilkan objek.

Parameter

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  (result: object) => void

  • hasil

    objek

    Chrome 109+

    Objek RequestUpdateCheckResult yang menyimpan status pemeriksaan update dan detail hasil jika ada update yang tersedia

    • status

      RequestUpdateCheckStatus

      Hasil pemeriksaan update.

    • versi

      string opsional

      Jika update tersedia, versi update yang tersedia akan ditampilkan.

Hasil

• Promise&lt;object&gt;

  Chrome 109+

  Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

restart()

chrome.runtime.restart()

Mulai ulang perangkat ChromeOS saat aplikasi berjalan dalam mode kios. Jika tidak, tidak ada operasi.

restartAfterDelay()

Promise Chrome 53+

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

Mulai ulang perangkat ChromeOS saat aplikasi berjalan dalam mode kios setelah detik yang ditentukan. Jika dipanggil lagi sebelum waktu berakhir, mulai ulang akan tertunda. Jika dipanggil dengan nilai -1, mulai ulang akan dibatalkan. Fungsi ini tidak berfungsi dalam mode non-kios. Fungsi ini hanya diizinkan untuk dipanggil berulang kali oleh ekstensi pertama yang memanggil API ini.

Parameter

• detik

  angka

  Waktu tunggu dalam detik sebelum memulai ulang perangkat, atau -1 untuk membatalkan mulai ulang terjadwal.

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  () => void

Hasil

• Promise<void>

  Chrome 99+

  Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

sendMessage()

Promise

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

Mengirim satu pesan ke pemroses peristiwa dalam ekstensi Anda atau ekstensi/aplikasi lain. Mirip dengan runtime.connect, tetapi hanya mengirim satu pesan, dengan respons opsional. Jika mengirim ke ekstensi Anda, peristiwa runtime.onMessage akan diaktifkan di setiap frame ekstensi Anda (kecuali untuk frame pengirim), atau runtime.onMessageExternal, jika ekstensi yang berbeda. Perhatikan bahwa ekstensi tidak dapat mengirim pesan ke skrip konten menggunakan metode ini. Untuk mengirim pesan ke skrip konten, gunakan tabs.sendMessage.

Parameter

• extensionId

  string opsional

  ID ekstensi tujuan pengiriman pesan. Jika dihilangkan, pesan akan dikirim ke ekstensi/aplikasi Anda sendiri. Wajib jika mengirim pesan dari halaman web untuk pesan web.

• pesan

  apa pun

  Pesan yang akan dikirim. Pesan ini harus berupa objek yang dapat di-JSON.

• opsi

  objek opsional

  • includeTlsChannelId

    boolean opsional

    Apakah ID saluran TLS akan diteruskan ke onMessageExternal untuk proses yang memproses peristiwa koneksi.

• callback

  fungsi opsional

  Chrome 99+

  Parameter callback terlihat seperti:

  (response: any) => void

  • respons

    apa pun

    Objek respons JSON yang dikirim oleh pengendali pesan. Jika terjadi error saat terhubung ke ekstensi, callback akan dipanggil tanpa argumen dan runtime.lastError akan ditetapkan ke pesan error.

Hasil

• Promise<any>

  Chrome 99+

  Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

sendNativeMessage()

Promise

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

Mengirim satu pesan ke aplikasi native. Metode ini memerlukan izin "nativeMessaging".

Parameter

• aplikasi

  string

  Nama host pesan native.

• pesan

  objek

  Pesan yang akan diteruskan ke host pesan native.

• callback

  fungsi opsional

  Chrome 99+

  Parameter callback terlihat seperti:

  (response: any) => void

  • respons

    apa pun

    Pesan respons yang dikirim oleh host pesan native. Jika terjadi error saat terhubung ke host pesan native, callback akan dipanggil tanpa argumen dan runtime.lastError akan ditetapkan ke pesan error.

Hasil

• Promise<any>

  Chrome 99+

  Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

setUninstallURL()

Promise

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

Menetapkan URL yang akan dikunjungi setelah penguninstalan. Ini dapat digunakan untuk membersihkan data sisi server, melakukan analisis, dan menerapkan survei. Maksimum 1.023 karakter.

Parameter

• url

  string

  URL yang akan dibuka setelah ekstensi di-uninstal. URL ini harus memiliki skema http: atau https:. Tetapkan string kosong agar tidak membuka tab baru setelah penguninstalan.

• callback

  fungsi opsional

  Chrome 45+

  Parameter callback terlihat seperti:

  () => void

Hasil

• Promise<void>

  Chrome 99+

  Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain harus menggunakan callback.

Acara

onBrowserUpdateAvailable

Tidak digunakan lagi

chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

Gunakan runtime.onRestartRequired.

Diaktifkan saat update Chrome tersedia, tetapi tidak langsung diinstal karena browser harus dimulai ulang.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

Diaktifkan saat koneksi dibuat dari proses ekstensi atau skrip konten (oleh runtime.connect).

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (port: Port) => void

  • port

    Port

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

Diaktifkan saat koneksi dibuat dari ekstensi lain (oleh runtime.connect), atau dari situs web yang dapat dihubungkan secara eksternal.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (port: Port) => void

  • port

    Port

onConnectNative

Chrome 76+

chrome.runtime.onConnectNative.addListener(
  callback: function,
)

Diaktifkan saat koneksi dibuat dari aplikasi native. Peristiwa ini memerlukan izin "nativeMessaging". Fitur ini hanya didukung di ChromeOS.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (port: Port) => void

  • port

    Port

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

Diaktifkan saat ekstensi pertama kali diinstal, saat ekstensi diupdate ke versi baru, dan saat Chrome diupdate ke versi baru.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (details: object) => void

  • detail

    objek

    • id

      string opsional

      Menunjukkan ID ekstensi modul bersama yang diimpor dan diperbarui. Ini hanya ada jika 'reason' adalah 'shared_module_update'.

    • previousVersion

      string opsional

      Menunjukkan versi ekstensi sebelumnya, yang baru saja diupdate. Ini hanya ada jika 'reason' adalah 'update'.

    • alasan

      OnInstalledReason

      Alasan peristiwa ini dikirim.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

Diaktifkan saat pesan dikirim dari proses ekstensi (oleh runtime.sendMessage) atau skrip konten (oleh tabs.sendMessage).

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • pesan

    apa pun

  • pengirim

    MessageSender

  • sendResponse

    fungsi

    Parameter sendResponse terlihat seperti:

    () => void

  • akan menampilkan

    boolean | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

Diaktifkan saat pesan dikirim dari ekstensi lain (oleh runtime.sendMessage). Tidak dapat digunakan dalam skrip konten.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • pesan

    apa pun

  • pengirim

    MessageSender

  • sendResponse

    fungsi

    Parameter sendResponse terlihat seperti:

    () => void

  • akan menampilkan

    boolean | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

Diaktifkan saat aplikasi atau perangkat tempat aplikasi berjalan perlu dimulai ulang. Aplikasi harus menutup semua jendelanya pada waktu yang paling awal agar dapat dimulai ulang. Jika aplikasi tidak melakukan apa pun, mulai ulang akan diterapkan setelah masa tenggang 24 jam berlalu. Saat ini, peristiwa ini hanya diaktifkan untuk aplikasi kios Chrome OS.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (reason: OnRestartRequiredReason) => void

  • alasan

    OnRestartRequiredReason

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

Diaktifkan saat profil yang menginstal ekstensi ini pertama kali dimulai. Peristiwa ini tidak diaktifkan saat profil Samaran dimulai, meskipun ekstensi ini beroperasi dalam mode Samaran 'terpisah'.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

Dikirim ke halaman peristiwa tepat sebelum dihapus muatannya. Hal ini memberi ekstensi kesempatan untuk melakukan pembersihan. Perhatikan bahwa karena halaman di-unload, operasi asinkron apa pun yang dimulai saat menangani peristiwa ini tidak dijamin akan selesai. Jika lebih banyak aktivitas untuk halaman peristiwa terjadi sebelum halaman dihapus muatannya, peristiwa onSuspendCanceled akan dikirim dan halaman tidak akan dihapus muatannya.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

Dikirim setelah onSuspend untuk menunjukkan bahwa aplikasi tidak akan di-unload.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

Diaktifkan saat update tersedia, tetapi tidak langsung diinstal karena aplikasi saat ini sedang berjalan. Jika Anda tidak melakukan apa pun, update akan diinstal saat halaman latar belakang dimuat ulang. Jika Anda ingin menginstalnya lebih cepat, Anda dapat memanggil chrome.runtime.reload() secara eksplisit sebagai respons terhadap peristiwa ini. Jika ekstensi Anda menggunakan halaman latar belakang persisten, halaman latar belakang tentu tidak akan pernah dimuat ulang. Jadi, kecuali jika Anda memanggil chrome.runtime.reload() secara manual sebagai respons terhadap peristiwa ini, update tidak akan diinstal hingga Chrome dimulai ulang. Jika tidak ada pengendali yang memproses peristiwa ini, dan ekstensi Anda memiliki halaman latar belakang yang persisten, ekstensi akan berperilaku seolah-olah chrome.runtime.reload() dipanggil sebagai respons terhadap peristiwa ini.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (details: object) => void

  • detail

    objek

    • versi

      string

      Nomor versi update yang tersedia.

onUserScriptConnect

Chrome 115+ MV3+

chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

Diaktifkan saat koneksi dibuat dari skrip pengguna dari ekstensi ini.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (port: Port) => void

  • port

    Port

onUserScriptMessage

Chrome 115+ MV3+

chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

Diaktifkan saat pesan dikirim dari skrip pengguna yang terkait dengan ekstensi yang sama.

Parameter

• callback

  fungsi

  Parameter callback terlihat seperti:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • pesan

    apa pun

  • pengirim

    MessageSender

  • sendResponse

    fungsi

    Parameter sendResponse terlihat seperti:

    () => void

  • akan menampilkan

    boolean | undefined