chrome.contentSettings

Deskripsi

Gunakan chrome.contentSettings API untuk mengubah setelan yang mengontrol apakah situs dapat menggunakan fitur seperti cookie, JavaScript, dan plugin. Secara umum, setelan konten memungkinkan Anda menyesuaikan perilaku Chrome berdasarkan per situs, bukan secara global.

Izin

contentSettings

Manifes

Anda harus mendeklarasikan izin "contentSettings" di manifes ekstensi untuk menggunakan API. Contoh:

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

Pola setelan konten

Anda dapat menggunakan pola untuk menentukan situs yang terpengaruh oleh setiap setelan konten. Misalnya, https://*.youtube.com/* menentukan youtube.com dan semua subdomainnya. Sintaksis untuk pola setelan konten sama dengan pola kecocokan , dengan beberapa perbedaan:

  • Untuk URL http, https, dan ftp, jalur harus berupa karakter pengganti (/*). Untuk URL file, jalur harus ditentukan sepenuhnya dan tidak boleh berisi karakter pengganti.
  • Berbeda dengan pola pencocokan, pola setelan konten dapat menentukan nomor port. Jika nomor port ditentukan, pola hanya cocok dengan situs yang memiliki port tersebut. Jika tidak ada nomor port yang ditentukan, pola akan cocok dengan semua port.

Prioritas pola

Jika lebih dari satu aturan setelan konten berlaku untuk situs tertentu, aturan dengan pola yang lebih spesifik akan diutamakan.

Misalnya, pola berikut diurutkan berdasarkan prioritas:

  1. https://www.example.com/*
  2. https://*.example.com/* (mencocokkan example.com dan semua subdomain)
  3. <all_urls> (mencocokkan setiap URL)

Tiga jenis karakter pengganti memengaruhi seberapa spesifik suatu pola:

  • Karakter pengganti di port (misalnya, https://www.example.com:*/*)
  • Karakter pengganti dalam skema (misalnya *://www.example.com:123/*)
  • Karakter pengganti di nama host (misalnya https://*.example.com:123/*)

Jika suatu pola lebih spesifik daripada pola lain di satu bagian, tetapi kurang spesifik di bagian lain, bagian yang berbeda diperiksa dalam urutan berikut: nama host, skema, port. Misalnya, pola berikut diurutkan berdasarkan prioritas:

  1. https://www.example.com:*/* Menentukan nama host dan skema.
  2. *:/www.example.com:123/* Tidak setinggi itu, karena meskipun menentukan nama host, tetapi tidak menentukan skema.
  3. https://*.example.com:123/* Lebih rendah karena meskipun menentukan port dan skema, ia memiliki karakter pengganti di nama host.

Pola primer dan sekunder

URL yang dipertimbangkan saat memutuskan setelan konten yang akan diterapkan bergantung pada jenis konten. Misalnya, setelan contentSettings.notifications didasarkan pada URL yang ditampilkan di omnibox. URL ini disebut URL "utama".

Beberapa jenis konten dapat mempertimbangkan URL tambahan. Misalnya, apakah situs diizinkan untuk menyetel contentSettings.cookies diputuskan berdasarkan URL permintaan HTTP (yang merupakan URL utama dalam hal ini) serta URL yang ditampilkan di kotak serbaguna (yang disebut URL "sekunder").

Jika beberapa aturan memiliki pola utama dan sekunder, aturan dengan pola utama yang lebih spesifik akan diutamakan. Jika ada beberapa aturan yang memiliki pola utama yang sama, aturan dengan pola sekunder yang lebih spesifik akan diutamakan. Misalnya, daftar pasangan pola primer/sekunder berikut diurutkan berdasarkan prioritas:

PrioritasPola utamaPola sekunder
1https://www.moose.com/*,https://www.wombat.com/*
2https://www.moose.com/*,<all_urls>
3<all_urls>,https://www.wombat.com/*
4<all_urls>,<all_urls>

ID resource

ID resource memungkinkan Anda menentukan setelan konten untuk subjenis tertentu dari jenis konten. Saat ini, satu-satunya jenis konten yang mendukung ID resource adalah contentSettings.plugins, dengan ID resource mengidentifikasi plugin tertentu. Saat menerapkan setelan konten, setelan untuk plugin tertentu akan diperiksa terlebih dahulu. Jika tidak ada setelan yang ditemukan untuk plugin tertentu, setelan konten umum untuk plugin akan diperiksa.

Misalnya, jika aturan setelan konten memiliki ID resource adobe-flash-player dan pola <all_urls>, aturan tersebut akan lebih diprioritaskan daripada aturan tanpa ID resource dan pola https://www.example.com/*, meskipun pola tersebut lebih spesifik.

Anda bisa mendapatkan daftar ID resource untuk jenis konten dengan memanggil metode contentSettings.ContentSetting.getResourceIdentifiers. Daftar yang ditampilkan dapat berubah dengan kumpulan plugin yang diinstal di komputer pengguna, tetapi Chrome mencoba menjaga ID tetap stabil di seluruh update plugin.

Contoh

Untuk mencoba API ini, instal contoh API contentSettings dari repositori chrome-extension-samples.

Jenis

AutoVerifyContentSetting

Chrome 113+

Enum

"allow"

"block"

CameraContentSetting

Chrome 46+

Enum

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121+

Enum

"allow"

"block"

"ask"

ContentSetting

Properti

  • hapus

    void

    Janji

    Menghapus semua aturan setelan konten yang ditetapkan oleh ekstensi ini.

    Fungsi clear akan terlihat seperti: 

    (details: object, callback?: function) => {...}

    • detail

      objek

      • cakupan

        Cakupan opsional

        Tempat untuk menghapus setelan (default: reguler).

    • callback

      fungsi opsional

      Parameter callback terlihat seperti: 

      () => void

    • return

      Promise<void>

      Chrome 96+

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

  • get

    void

    Janji

    Mendapatkan setelan konten saat ini untuk pasangan URL tertentu.

    Fungsi get akan terlihat seperti: 

    (details: object, callback?: function) => {...}

    • detail

      objek

      • samaran

        boolean opsional

        Apakah akan memeriksa setelan konten untuk sesi samaran. (default salah)

      • primaryUrl

        string

        URL utama yang setelan kontennya harus diambil. Perhatikan bahwa arti URL utama bergantung pada jenis konten.

      • resourceIdentifier

        ResourceIdentifier opsional

        ID jenis konten yang lebih spesifik yang setelannya harus diambil.

      • secondaryUrl

        string opsional

        URL sekunder yang setelan kontennya harus diambil. Default-nya adalah URL utama. Perhatikan bahwa arti URL sekunder bergantung pada jenis konten, dan tidak semua jenis konten menggunakan URL sekunder.

    • callback

      fungsi opsional

      Parameter callback terlihat seperti: 

      (details: object) => void

      • detail

        objek

        • setelan

          T

          Setelan konten. Lihat deskripsi masing-masing objek ContentSetting untuk mengetahui kemungkinan nilai.

    • return

      Promise<object>

      Chrome 96+

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

  • getResourceIdentifiers

    void

    Janji

    Fungsi getResourceIdentifiers akan terlihat seperti: 

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

    • callback

      fungsi opsional

      Parameter callback terlihat seperti: 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] opsional

        Daftar ID resource untuk jenis konten ini, atau undefined jika jenis konten ini tidak menggunakan ID resource.

    • return

      Promise<ResourceIdentifier[]>

      Chrome 96+

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

  • tetapkan

    void

    Janji

    Menerapkan aturan setelan konten baru.

    Fungsi set akan terlihat seperti: 

    (details: object, callback?: function) => {...}

    • detail

      objek

      • primaryPattern

        string

        Pola untuk URL utama. Untuk mengetahui detail format pola, lihat Pola Setelan Konten.

      • resourceIdentifier

        ResourceIdentifier opsional

        ID resource untuk jenis konten.

      • cakupan

        Cakupan opsional

        Tempat untuk menyetel setelan (default: reguler).

      • secondaryPattern

        string opsional

        Pola untuk URL sekunder. Secara default, semua URL akan dicocokkan. Untuk mengetahui detail format pola, lihat Pola Setelan Konten.

      • setelan

        apa pun

        Setelan yang diterapkan oleh aturan ini. Lihat deskripsi masing-masing objek ContentSetting untuk mengetahui kemungkinan nilai.

    • callback

      fungsi opsional

      Parameter callback terlihat seperti: 

      () => void

    • return

      Promise<void>

      Chrome 96+

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

CookiesContentSetting

Chrome 44+

Enum

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44+

Nilai

"allow"

ImagesContentSetting

Chrome 44+

Enum

"allow"

"block"

JavascriptContentSetting

Chrome 44+

Enum

"allow"

"block"

LocationContentSetting

Chrome 44+

Enum

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome 46+

Enum

"allow"

"block"

"ask"

MouselockContentSetting

Chrome 44+

Nilai

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44+

Enum

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome 44+

Enum

"allow"

"block"

"ask"

PluginsContentSetting

Chrome 44+

Nilai

"block"

PopupsContentSetting

Chrome 44+

Enum

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44+

Nilai

"block"

ResourceIdentifier

Satu-satunya jenis konten yang menggunakan ID resource adalah contentSettings.plugins. Untuk mengetahui informasi selengkapnya, lihat ID Resource.

Properti

  • deskripsi

    string opsional

    Deskripsi resource yang dapat dibaca manusia.

  • id

    string

    ID resource untuk jenis konten tertentu.

Scope

Chrome 44+

Cakupan ContentSetting. Salah satu regular: setelan untuk profil reguler (yang diwarisi oleh profil samaran jika tidak diganti di tempat lain), incognito\_session\_only: setelan untuk profil samaran yang hanya dapat ditetapkan selama sesi samaran dan dihapus saat sesi samaran berakhir (menggantikan setelan reguler).

Enum

"regular"

"incognito_session_only"

SoundContentSetting

Chrome 141+

Enum

"allow"

"block"

Properti

automaticDownloads

Apakah akan mengizinkan situs mendownload beberapa file secara otomatis. Salah satu dari allow: Izinkan situs mendownload beberapa file secara otomatis, block: Jangan izinkan situs mendownload beberapa file secara otomatis, ask: Tanya saat situs ingin mendownload file secara otomatis setelah file pertama. Default-nya adalah ask. URL utama adalah URL bingkai level teratas. URL sekunder tidak digunakan.

Jenis

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113+

Apakah akan mengizinkan situs menggunakan Private State Tokens API. Salah satu dari allow: Izinkan situs menggunakan Private State Tokens API, block: Blokir situs agar tidak menggunakan Private State Tokens API. Default-nya adalah allow. Saat memanggil set(), pola URL utama harus berupa <all_urls>. URL sekunder tidak digunakan.

Jenis

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46+

Apakah situs diizinkan untuk mengakses kamera. Salah satu dari allow: Izinkan situs mengakses kamera, block: Jangan izinkan situs mengakses kamera, ask: Tanya saat situs ingin mengakses kamera. Default-nya adalah ask. URL utama adalah URL dokumen yang meminta akses kamera. URL sekunder tidak digunakan. CATATAN: Setelan 'izinkan' tidak valid jika kedua pola adalah '<all_urls>'.

Jenis

ContentSetting<CameraContentSetting>

clipboard

Chrome 121+

Apakah Anda ingin mengizinkan situs mengakses papan klip melalui kemampuan lanjutan Async Clipboard API atau tidak. Kemampuan "Lanjutan" mencakup apa pun selain menulis format bawaan setelah gestur pengguna, yaitu kemampuan untuk membaca, kemampuan untuk menulis format kustom, dan kemampuan untuk menulis tanpa gestur pengguna. Salah satu dari allow: Izinkan situs menggunakan kemampuan papan klip lanjutan, block: Jangan izinkan situs menggunakan kemampuan papan klip lanjutan, ask: Tanya saat situs ingin menggunakan kemampuan papan klip lanjutan. Default-nya adalah ask. URL utama adalah URL dokumen yang meminta akses papan klip. URL sekunder tidak digunakan.

Jenis

ContentSetting<ClipboardContentSetting>

cookies

Apakah akan mengizinkan cookie dan data lokal lainnya disetel oleh situs. Salah satu dari allow: Terima cookie, block: Blokir cookie, session\_only: Terima cookie hanya untuk sesi saat ini. Default-nya adalah allow. URL utama adalah URL yang merepresentasikan asal cookie. URL sekunder adalah URL bingkai level teratas.

Jenis

ContentSetting<CookiesContentSetting>

fullscreen

Tidak digunakan lagi. Tidak lagi memiliki efek. Izin layar penuh kini otomatis diberikan untuk semua situs. Nilainya selalu allow.

Jenis

ContentSetting<FullscreenContentSetting>

images

Apakah akan menampilkan gambar. Salah satu dari allow: Tampilkan gambar, block: Jangan tampilkan gambar. Jumlah defaultnya adalah allow URL utama adalah URL bingkai level teratas. URL sekunder adalah URL gambar.

Jenis

ContentSetting<ImagesContentSetting>

javascript

Apakah akan menjalankan JavaScript. Salah satu dari allow: Jalankan JavaScript, block: Jangan jalankan JavaScript. Jumlah defaultnya adalah allow URL utama adalah URL bingkai level teratas. URL sekunder tidak digunakan.

Jenis

ContentSetting<JavascriptContentSetting>

location

Apakah akan mengizinkan Geolokasi. Salah satu dari allow: Izinkan situs melacak lokasi fisik Anda, block: Jangan izinkan situs melacak lokasi fisik Anda, ask: Tanya sebelum mengizinkan situs melacak lokasi fisik Anda. Default-nya adalah ask. URL utama adalah URL dokumen yang meminta data lokasi. URL sekunder adalah URL frame tingkat teratas (yang mungkin atau mungkin tidak berbeda dari URL permintaan).

Jenis

ContentSetting<LocationContentSetting>

microphone

Chrome 46+

Apakah situs diizinkan mengakses mikrofon. Salah satu dari allow: Izinkan situs mengakses mikrofon, block: Jangan izinkan situs mengakses mikrofon, ask: Tanya saat situs ingin mengakses mikrofon. Default-nya adalah ask. URL utama adalah URL dokumen yang meminta akses mikrofon. URL sekunder tidak digunakan. CATATAN: Setelan 'izinkan' tidak valid jika kedua pola adalah '<all_urls>'.

Jenis

ContentSetting<MicrophoneContentSetting>

mouselock

Tidak digunakan lagi. Tidak lagi memiliki efek. Izin penguncian mouse kini otomatis diberikan untuk semua situs. Nilainya selalu allow.

Jenis

ContentSetting<MouselockContentSetting>

notifications

Apakah situs diizinkan menampilkan notifikasi desktop. Salah satu opsi allow: Izinkan situs menampilkan notifikasi desktop, block: Jangan izinkan situs menampilkan notifikasi desktop, ask: Tanya saat situs ingin menampilkan notifikasi desktop. Default-nya adalah ask. URL utama adalah URL dokumen yang ingin menampilkan notifikasi. URL sekunder tidak digunakan.

Jenis

ContentSetting<NotificationsContentSetting>

plugins

Tidak digunakan lagi. Dengan dihapusnya dukungan Flash di Chrome 88, izin ini tidak lagi memiliki efek apa pun. Nilainya selalu block. Panggilan ke set() dan clear() akan diabaikan.

Jenis

ContentSetting<PluginsContentSetting>

popups

Apakah situs diizinkan untuk menampilkan pop-up. Salah satu dari allow: Izinkan situs menampilkan pop-up, block: Jangan izinkan situs menampilkan pop-up. Jumlah defaultnya adalah block URL utama adalah URL bingkai level teratas. URL sekunder tidak digunakan.

Jenis

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Tidak digunakan lagi. Sebelumnya, mengontrol apakah situs diizinkan menjalankan plugin tanpa sandbox, tetapi dengan dihapusnya proses broker Flash di Chrome 88, izin ini tidak lagi berpengaruh. Nilainya selalu block. Panggilan ke set() dan clear() akan diabaikan.

Jenis

ContentSetting<PpapiBrokerContentSetting>