Deskripsi
Gunakan chrome.contentSettings
API untuk mengubah setelan yang mengontrol apakah situs dapat menggunakan fitur seperti cookie, JavaScript, dan plugin. Secara lebih umum, setelan konten memungkinkan Anda menyesuaikan perilaku Chrome berdasarkan situs, bukan secara global.
Izin
contentSettings
Manifes
Anda harus mendeklarasikan izin "contentSettings" dalam manifes ekstensi untuk menggunakan API. Contoh:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
Pola setelan konten
Anda dapat menggunakan pola untuk menentukan situs yang dipengaruhi oleh setiap setelan konten. Misalnya,
https://*.youtube.com/*
menentukan youtube.com dan semua subdomainnya. Sintaksis untuk pola setelan konten sama dengan pola pencocokan, dengan beberapa perbedaan:
- Untuk URL
http
,https
, danftp
, jalur harus berupa karakter pengganti (/*
). Untuk URLfile
, 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 dengan port tersebut. Jika tidak ada nomor port yang ditentukan, polanya akan cocok dengan semua port.
Prioritas pola
Jika lebih dari satu aturan setelan konten berlaku untuk suatu situs, aturan dengan pola yang lebih spesifik akan lebih diutamakan.
Misalnya, pola berikut diurutkan berdasarkan prioritas:
https://www.example.com/*
https://*.example.com/*
(example.com yang cocok dan semua subdomain)<all_urls>
(cocok dengan setiap URL)
Tiga jenis {i>wildcard<i} 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 dalam nama host (misalnya
https://*.example.com:123/*
)
Jika pola lebih spesifik daripada pola lainnya di satu bagian tetapi tidak terlalu spesifik di bagian lainnya, bagian yang berbeda akan diperiksa dengan urutan berikut: nama host, skema, port. Misalnya, pola berikut diurutkan berdasarkan prioritas:
https://www.example.com:*/*
Menentukan nama host dan skema.*:/www.example.com:123/*
Tidak terlalu tinggi, karena meskipun menentukan nama host, tetapi tidak menentukan skemanya.https://*.example.com:123/*
Lebih rendah karena meskipun menentukan port dan skema, atribut ini memiliki karakter pengganti pada nama host.
Pola primer dan sekunder
URL yang dipertimbangkan saat menentukan setelan konten yang akan diterapkan bergantung pada jenis kontennya.
Misalnya, untuk 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
atau tidak ditentukan berdasarkan URL permintaan HTTP (yang merupakan
URL utama dalam kasus ini) serta URL yang ditampilkan di omnibox (yang disebut URL
sekunder).
Jika beberapa aturan memiliki pola primer dan sekunder, aturan dengan pola utama yang lebih spesifik akan diprioritaskan. Jika ada beberapa aturan yang memiliki pola utama yang sama, aturan dengan pola sekunder yang lebih spesifik akan diprioritaskan. Misalnya, daftar pasangan pola primer/sekunder berikut diurutkan berdasarkan prioritas:
Prioritas | Pola utama | Pola sekunder |
---|---|---|
1 | https://www.moose.com/* , | https://www.wombat.com/* |
2 | https://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
,
tempat 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 diutamakan daripada aturan yang tidak memiliki ID resource dan pola https://www.example.com/*
, meskipun pola tersebut lebih spesifik.
Anda dapat memperoleh daftar ID resource untuk suatu jenis konten dengan memanggil metode contentSettings.ContentSetting.getResourceIdentifiers
. Daftar yang ditampilkan dapat berubah dengan
kumpulan plugin terinstal di komputer pengguna, tetapi Chrome akan mencoba menjaga ID tetap stabil
di seluruh update plugin.
Contoh
Untuk mencoba API ini, instal contoh contentSettings API dari repositori chrome-extension-samples.
Jenis
AutoVerifyContentSetting
Enum
CameraContentSetting
Enum
ClipboardContentSetting
Enum
ContentSetting
Properti
-
hapus
void
PromiseHapus semua aturan setelan konten yang ditetapkan oleh ekstensi ini.
Fungsi
clear
terlihat seperti:(details: object, callback?: function) => {...}
-
detail
objek
-
cakupan
Cakupan opsional
Tempat menghapus setelan (default: reguler).
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
-
akan menampilkan
Promise<void>
Chrome 96 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
-
-
get
void
PromiseMendapatkan setelan konten saat ini untuk pasangan URL tertentu.
Fungsi
get
terlihat seperti:(details: object, callback?: function) => {...}
-
detail
objek
-
samaran
boolean opsional
Apakah ingin memeriksa setelan konten untuk sesi samaran atau tidak. (salah default)
-
primaryUrl
string
URL utama tempat setelan kontennya akan diambil. Perhatikan bahwa arti URL utama bergantung pada jenis kontennya.
-
resourceIdentifier
ResourceIdentifier opsional
ID yang lebih spesifik untuk jenis konten yang setelannya harus diambil.
-
secondaryUrl
string opsional
URL sekunder yang setelan kontennya harus diambil. Default-nya adalah URL utama. Perlu diperhatikan 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
-
setting
T
Setelan konten. Lihat deskripsi setiap objek ContentSetting untuk kemungkinan nilai.
-
-
-
akan menampilkan
Promise<object>
Chrome 96 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
-
-
getResourceIdentifiers
void
PromiseFungsi
getResourceIdentifiers
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.
-
-
akan menampilkan
Promise<ResourceIdentifier[]>
Chrome 96 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
-
-
set
void
PromiseMenerapkan aturan setelan konten baru.
Fungsi
set
terlihat seperti:(details: object, callback?: function) => {...}
-
detail
objek
-
primaryPattern
string
Pola untuk URL utama. Untuk detail tentang format pola, lihat Pola Setelan Konten.
-
resourceIdentifier
ResourceIdentifier opsional
ID resource untuk jenis konten.
-
cakupan
Cakupan opsional
Tempat menetapkan setelan (default: reguler).
-
secondaryPattern
string opsional
Pola untuk URL sekunder. Setelan defaultnya adalah cocok dengan semua URL. Untuk detail tentang format pola, lihat Pola Setelan Konten.
-
setting
apa pun
Setelan yang diterapkan oleh aturan ini. Lihat deskripsi setiap objek ContentSetting untuk kemungkinan nilai.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
-
akan menampilkan
Promise<void>
Chrome 96 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
-
CookiesContentSetting
Enum
"session_only"
FullscreenContentSetting
Nilai
ImagesContentSetting
Enum
JavascriptContentSetting
Enum
LocationContentSetting
Enum
MicrophoneContentSetting
Enum
MouselockContentSetting
Nilai
MultipleAutomaticDownloadsContentSetting
Enum
NotificationsContentSetting
Enum
PluginsContentSetting
Nilai
PopupsContentSetting
Enum
PpapiBrokerContentSetting
Nilai
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 yang ditentukan.
Scope
Cakupan ContentSetting. Salah satu dari
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 disetel selama sesi samaran dan dihapus saat sesi samaran berakhir (menggantikan setelan reguler).
Enum
"regular"
"incognito_session_only"
Properti
automaticDownloads
Apakah akan mengizinkan situs mendownload beberapa file secara otomatis. Salah satu dari
allow
: Mengizinkan situs mendownload beberapa file secara otomatis,
block
: Tidak mengizinkan situs mendownload beberapa file secara otomatis,
ask
: Tanyakan saat situs ingin mendownload file secara otomatis setelah file pertama.
Default-nya adalah ask
.
URL utama adalah URL frame tingkat atas. URL sekunder tidak digunakan.
autoVerify
Apakah akan mengizinkan situs menggunakan Private State Tokens API. Salah satu dari
allow
: Mengizinkan situs menggunakan Private State Tokens API,
block
: Memblokir situs agar tidak menggunakan Private State Tokens API.
Default-nya adalah allow
.
URL utama adalah URL frame tingkat atas. URL sekunder tidak digunakan. CATATAN: Saat memanggil set()
, pola utamanya harus .
camera
Apakah akan mengizinkan situs mengakses kamera. Salah satu dari
allow
: Mengizinkan situs mengakses kamera,
block
: Tidak mengizinkan situs mengakses kamera,
ask
: Tanyakan 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 tersebut adalah ''.
clipboard
Apakah akan mengizinkan situs mengakses papan klip melalui kemampuan lanjutan Async Clipboard API. Kemampuan "Lanjutan" mencakup apa saja 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
: Mengizinkan situs menggunakan kemampuan papan klip lanjutan,
block
: Tidak mengizinkan situs menggunakan kemampuan papan klip lanjutan,
ask
: Tanyakan saat situs ingin menggunakan kemampuan papan klip lanjutan.
Default-nya adalah ask
.
URL utama adalah URL dokumen yang meminta akses ke papan klip. URL sekunder tidak digunakan.
cookies
Apakah akan mengizinkan cookie dan data lokal lainnya disetel oleh situs. Salah satu dari
allow
: Terima cookie,
block
: Blokir cookie,
session\_only
: Menerima cookie hanya untuk sesi saat ini.
Default-nya adalah allow
.
URL utama adalah URL yang mewakili asal cookie. URL sekunder adalah URL frame tingkat atas.
fullscreen
Tidak digunakan lagi. Tidak lagi berpengaruh. Izin layar penuh kini diberikan secara otomatis untuk semua situs. Nilai selalu allow
.
images
Apakah akan menampilkan gambar. Salah satu dari
allow
: Menampilkan gambar,
block
: Jangan tampilkan gambar.
Jumlah defaultnya adalah allow
URL utama adalah URL frame tingkat atas. URL sekunder adalah URL gambar.
javascript
Apakah akan menjalankan JavaScript. Salah satu dari
allow
: Jalankan JavaScript,
block
: Jangan jalankan JavaScript.
Jumlah defaultnya adalah allow
URL utama adalah URL frame tingkat atas. URL sekunder tidak digunakan.
location
Apakah akan mengizinkan Geolokasi. Salah satu dari
allow
: Mengizinkan situs melacak lokasi fisik Anda,
block
: Jangan izinkan situs melacak lokasi fisik Anda,
ask
: Tanyakan 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 level teratas (yang mungkin atau mungkin tidak berbeda dari URL yang meminta).
microphone
Apakah akan mengizinkan situs mengakses mikrofon. Salah satu dari
allow
: Mengizinkan situs mengakses mikrofon,
block
: Tidak mengizinkan situs mengakses mikrofon,
ask
: Tanyakan 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 tersebut adalah ''.
mouselock
Tidak digunakan lagi. Tidak lagi berpengaruh. Izin kunci mouse kini otomatis diberikan untuk semua situs. Nilai selalu allow
.
notifications
Apakah mengizinkan situs menampilkan notifikasi desktop. Salah satu dari
allow
: Mengizinkan situs menampilkan notifikasi desktop,
block
: Tidak mengizinkan situs menampilkan notifikasi desktop,
ask
: Tanyakan saat situs ingin menampilkan notifikasi desktop.
Default-nya adalah ask
.
URL utama adalah URL dokumen yang ingin menampilkan notifikasi. URL sekunder tidak digunakan.
plugins
Tidak digunakan lagi. Dengan dihapusnya dukungan Flash di Chrome 88, izin ini tidak akan berpengaruh lagi. Nilai selalu block
. Panggilan ke set()
dan clear()
akan diabaikan.
popups
Apakah mengizinkan situs menampilkan pop-up. Salah satu dari
allow
: Mengizinkan situs menampilkan pop-up,
block
: Tidak mengizinkan situs menampilkan pop-up.
Jumlah defaultnya adalah block
URL utama adalah URL frame tingkat atas. URL sekunder tidak digunakan.
unsandboxedPlugins
Tidak digunakan lagi. Sebelumnya, izin ini mengontrol apakah situs akan menjalankan plugin yang tidak di-sandbox atau tidak, tetapi dengan proses broker Flash yang dihapus di Chrome 88, izin ini tidak lagi berpengaruh. Nilai selalu block
. Panggilan ke set()
dan clear()
akan diabaikan.