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 per situs, bukan secara global.
Izin
contentSettings
Anda harus mendeklarasikan izin "contentSettings"
dalam manifes ekstensi Anda untuk menggunakan API. Contoh:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
Konsep dan penggunaan
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 konten
pola setelan adalah sama dengan pola pencocokan, dengan beberapa perbedaan:
- Untuk URL
http
,https
, danftp
, jalur harus berupa karakter pengganti (/*
). Untukfile
URL, jalur harus ditentukan sepenuhnya dan tidak boleh berisi karakter pengganti. - Berbeda dengan pola pencocokan, pola setelan konten dapat menentukan nomor port. Jika port nomor ditentukan, polanya hanya akan mencocokkan situs web dengan porta tersebut. Jika tidak ada nomor port yang ditentukan, polanya akan cocok dengan semua porta.
Prioritas pola
Jika lebih dari satu aturan setelan konten berlaku untuk situs tertentu, aturan dengan pola yang akan diprioritaskan.
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 karakter pengganti memengaruhi seberapa spesifik 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 sebuah pola lebih spesifik daripada pola lain di satu bagian tetapi kurang spesifik di bagian lain, bagian yang berbeda diperiksa dalam urutan berikut: nama {i>host<i}, skema, {i>port<i}. Misalnya, pola berikut diurutkan berdasarkan prioritas:
https://www.example.com:*/*
Menentukan nama host dan skema.*:/www.example.com:123/*
Tidak setinggi, karena meskipun menentukan nama {i>host<i}, itu tidak menentukan skema.https://*.example.com:123/*
Lebih rendah karena meskipun menentukan port dan skema, kode ini memiliki karakter pengganti di nama host.
Pola primer dan sekunder
URL yang dipertimbangkan saat menentukan setelan konten yang akan diterapkan bergantung pada jenis konten.
Misalnya, untuk contentSettings.notifications
, setelan didasarkan pada URL yang ditampilkan di
omnibox. URL ini disebut "utama" .
Beberapa jenis konten dapat mempertimbangkan URL tambahan. Misalnya, apakah sebuah situs diizinkan untuk
menetapkan contentSettings.cookies
ditentukan berdasarkan URL permintaan HTTP (yang
dalam kasus ini) serta URL yang ditampilkan di omnibox (yang disebut "sekunder"
(URL) kami.
Jika beberapa aturan memiliki pola primer dan sekunder, aturan dengan aturan primer yang lebih spesifik pola yang 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 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
,
dengan ID resource
mengidentifikasi plugin tertentu. Saat menerapkan setelan konten, pertama-tama
setelan untuk plugin tertentu akan dicentang. Jika tidak ditemukan setelan untuk
, setelan konten umum untuk plugin akan diperiksa.
Misalnya, jika aturan setelan konten memiliki ID resource adobe-flash-player
dan
pola <all_urls>
, aturan ini akan diprioritaskan di atas 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
Metode contentSettings.ContentSetting.getResourceIdentifiers()
. Daftar yang dikembalikan
dapat berubah dengan
kumpulan plugin yang terinstal pada komputer pengguna, tetapi Chrome mencoba menjaga agar ID tetap stabil
di seluruh update plugin.
Contoh
Untuk mencoba API ini, instal contoh contentSettings API dari chrome-extension-samples repositori resource.
Jenis
AutoVerifyContentSetting
Enum
"izinkan"
"blokir"
CameraContentSetting
Enum
"izinkan"
"blokir"
"tanyakan"
ClipboardContentSetting
Enum
"izinkan"
"blokir"
"tanyakan"
ContentSetting
Properti
-
hapus
void
JanjiHapus semua aturan setelan konten yang ditetapkan oleh ekstensi ini.
Fungsi
clear
akan terlihat seperti ini:(details: object, callback?: function) => {...}
-
detail
objek
-
cakupan
Cakupan opsional
Tempat untuk menghapus setelan (default: reguler).
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
-
akan menampilkan
Janji<void>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
-
get
void
JanjiMendapatkan setelan konten saat ini untuk sepasang URL tertentu.
Fungsi
get
akan terlihat seperti ini:(details: object, callback?: function) => {...}
-
detail
objek
-
samaran
boolean opsional
Apakah akan memeriksa setelan konten untuk sesi samaran. (default salah)
-
primaryUrl
string
URL utama tempat setelan kontennya harus diambil. Perlu diperhatikan bahwa arti URL utama bergantung pada jenis konten.
-
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 ini:(details: object) => void
-
detail
objek
-
setelan
S
Setelan konten. Lihat deskripsi setiap objek ContentSetting untuk kemungkinan nilai.
-
-
-
akan menampilkan
Promise<object>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
-
getResourceIdentifiers
void
JanjiFungsi
getResourceIdentifiers
akan terlihat seperti ini:(callback?: function) => {...}
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(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 didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
-
set
void
JanjiMenerapkan aturan setelan konten baru.
Fungsi
set
akan terlihat seperti ini:(details: object, callback?: function) => {...}
-
detail
objek
-
primaryPattern
string
Pola untuk URL utama. Untuk mengetahui 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 mengetahui detail tentang format pola, lihat Pola Setelan Konten.
-
setelan
apa pun
Setelan yang diterapkan oleh aturan ini. Lihat deskripsi setiap objek ContentSetting untuk kemungkinan nilai.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
-
akan menampilkan
Janji<void>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
-
CookiesContentSetting
Enum
"izinkan"
"blokir"
"session_only"
FullscreenContentSetting
Nilai
"izinkan"
ImagesContentSetting
Enum
"izinkan"
"blokir"
JavascriptContentSetting
Enum
"izinkan"
"blokir"
LocationContentSetting
Enum
"izinkan"
"blokir"
"tanyakan"
MicrophoneContentSetting
Enum
"izinkan"
"blokir"
"tanyakan"
MouselockContentSetting
Nilai
"izinkan"
MultipleAutomaticDownloadsContentSetting
Enum
"izinkan"
"blokir"
"tanyakan"
NotificationsContentSetting
Enum
"izinkan"
"blokir"
"tanyakan"
PluginsContentSetting
Nilai
"blokir"
PopupsContentSetting
Enum
"izinkan"
"blokir"
PpapiBrokerContentSetting
Nilai
"blokir"
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 Setelan Konten. 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 disetel selama sesi samaran dan dihapus saat sesi samaran berakhir (mengganti setelan reguler).
Enum
"reguler"
"incognito_session_only"
Properti
automaticDownloads
Apakah akan mengizinkan situs mendownload beberapa file secara otomatis. Salah satu
allow
: Memungkinkan situs mendownload beberapa file secara otomatis,
block
: Jangan izinkan 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 dari {i>frame<i} tingkat atas. URL sekunder tidak digunakan.
Jenis
autoVerify
Apakah akan mengizinkan situs menggunakan Private State Tokens API. Salah satu
allow
: Mengizinkan situs menggunakan Private State Tokens API,
block
: Blokir situs agar tidak menggunakan Private State Tokens API.
Default-nya adalah allow
.
URL utama adalah URL dari {i>frame<i} tingkat atas. URL sekunder tidak digunakan. CATATAN: Saat memanggil set()
, pola utama harus .
Jenis
camera
Apakah akan mengizinkan situs mengakses kamera. Salah satu
allow
: Mengizinkan situs mengakses kamera,
block
: Jangan izinkan 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: 'allow' tidak valid jika kedua pola adalah ''.
Jenis
clipboard
Apakah akan mengizinkan situs mengakses papan klip melalui kemampuan lanjutan Asynchronous Clipboard API. "Lanjutan" kemampuan mencakup apa pun selain menulis format bawaan setelah {i>gesture <i}pengguna, yaitu kemampuan untuk membaca, kemampuan untuk menulis format khusus, dan kemampuan untuk menulis tanpa {i>gesture <i}pengguna. Salah satu
allow
: Mengizinkan situs menggunakan kemampuan papan klip lanjutan,
block
: Jangan izinkan 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 papan klip. URL sekunder tidak digunakan.
Jenis
cookies
Apakah akan mengizinkan cookie dan data lokal lainnya disetel oleh situs. Salah satu
allow
: Terima cookie,
block
: Memblokir 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 dari {i>frame<i} tingkat atas.
Jenis
fullscreen
Tidak digunakan lagi. Tidak lagi memiliki pengaruh. Izin layar penuh kini diberikan secara otomatis untuk semua situs. Nilai selalu allow
.
Jenis
images
Apakah akan menampilkan gambar. Salah satu
allow
: Tampilkan gambar,
block
: Jangan tampilkan gambar.
Jumlah defaultnya adalah allow
URL utama adalah URL dari {i>frame<i} tingkat atas. URL sekunder adalah URL gambar.
Jenis
javascript
Apakah akan menjalankan JavaScript. Salah satu
allow
: Menjalankan JavaScript,
block
: Jangan jalankan JavaScript.
Jumlah defaultnya adalah allow
URL utama adalah URL dari {i>frame<i} tingkat atas. URL sekunder tidak digunakan.
Jenis
location
Apakah akan mengizinkan Geolokasi. Salah satu
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 tingkat teratas (yang mungkin berbeda atau tidak berbeda dari URL yang meminta).
Jenis
microphone
Apakah akan mengizinkan situs mengakses mikrofon. Salah satu
allow
: Mengizinkan situs mengakses mikrofon,
block
: Jangan izinkan 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: 'allow' tidak valid jika kedua pola adalah ''.
Jenis
mouselock
Tidak digunakan lagi. Tidak lagi memiliki pengaruh. Izin kunci mouse kini diberikan secara otomatis untuk semua situs. Nilai selalu allow
.
Jenis
notifications
Apakah akan mengizinkan situs menampilkan notifikasi desktop. Salah satu
allow
: Mengizinkan situs menampilkan notifikasi desktop,
block
: Jangan izinkan 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.
Jenis
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.
Jenis
popups
Apakah mengizinkan situs menampilkan pop-up. Salah satu
allow
: Mengizinkan situs menampilkan pop-up,
block
: Jangan izinkan situs menampilkan pop-up.
Jumlah defaultnya adalah block
URL utama adalah URL dari {i>frame<i} tingkat atas. URL sekunder tidak digunakan.
Jenis
unsandboxedPlugins
Tidak digunakan lagi. Sebelumnya, mengontrol apakah situs akan diizinkan menjalankan plugin yang tidak di-sandbox atau tidak. Namun, setelah proses broker Flash dihapus di Chrome 88, izin ini tidak lagi memiliki pengaruh. Nilai selalu block
. Panggilan ke set()
dan clear()
akan diabaikan.