תיאור
יש להשתמש ב-API של chrome.contentSettings
כדי לשנות הגדרות שקובעות אם אתרים יכולים להשתמש בתכונות כמו קובצי cookie, JavaScript ויישומי פלאגין. באופן כללי, הגדרות תוכן מאפשרות לכם להתאים אישית את ההתנהגות של Chrome ברמת האתר, במקום באופן גלובלי.
הרשאות
contentSettings
כדי להשתמש ב-API, עליך להצהיר על ההרשאה "contentSettings"
במניפסט של התוסף. לדוגמה:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
מושגים ושימוש
דפוסים בהגדרות התוכן
אפשר להשתמש בתבניות כדי לציין את האתרים שמשפיעות כל הגדרת תוכן. לדוגמה, הערך https://*.youtube.com/*
מציין את youtube.com ואת כל תתי-הדומיין שלו. התחביר של תבניות להגדרת תוכן זהה לתחביר של דפוסי התאמה, עם כמה הבדלים:
- עבור כתובות URL מסוג
http
,https
ו-ftp
, הנתיב חייב להיות תו כללי לחיפוש (/*
). לגביfile
כתובות URL, יש לציין את הנתיב במלואו ולא לכלול תווים כלליים לחיפוש. - בניגוד לתבניות התאמה, תבניות של הגדרות תוכן יכולות לציין מספר יציאה. אם צוין מספר יציאה, התבנית תתאים רק לאתרים עם אותה יציאה. אם לא צוין מספר יציאה, התבנית תואמת לכל היציאות.
קדימות של קו ביטול נעילה
כשחל על אתר נתון יותר מכלל אחד להגדרת תוכן, הכלל עם התבנית הספציפית יותר מקבל עדיפות.
לדוגמה, התבניות הבאות מסודרות לפי קדימות:
https://www.example.com/*
https://*.example.com/*
(התאמה ל-example.com ולכל תתי-הדומיין)<all_urls>
(התאמה לכל כתובת URL)
קיימים שלושה סוגים של תווים כלליים שמשפיעים על מידת הספציפיות של דפוס:
- תווים כלליים לחיפוש ביציאה (לדוגמה
https://www.example.com:*/*
) - תווים כלליים לחיפוש בסכימה (לדוגמה
*://www.example.com:123/*
) - תווים כלליים לחיפוש בשם המארח (לדוגמה
https://*.example.com:123/*
)
אם דפוס מסוים ספציפי יותר מדפוס אחר בחלק אחד אבל פחות ספציפי בחלק אחר, החלקים השונים נבדקים בסדר הבא: שם מארח, סכמה, יציאה. לדוגמה, התבניות הבאות מסודרות לפי קדימות:
https://www.example.com:*/*
מציינים את שם המארח והסכימה.*:/www.example.com:123/*
הסכימה לא גבוהה כי למרות שהוא מציין את שם המארח, הסכמה לא מצוינת.https://*.example.com:123/*
נמוכה יותר כי למרות שהיא מציינת את היציאה והסכימה, יש בה תו כללי לחיפוש בשם המארח.
דפוסים ראשיים ומשניים
כתובת ה-URL נלקחת בחשבון כשמחליטים איזו הגדרת תוכן להחיל תלויה בסוג התוכן.
לדוגמה, ההגדרות של contentSettings.notifications
מבוססות על כתובת ה-URL שמוצגת
בסרגל הכתובות. כתובת ה-URL הזו נקראת כתובת ה-URL ה'ראשית'.
בחלק מסוגי התוכן המערכת מביאה בחשבון כתובות URL נוספות. לדוגמה, ההחלטה אם לאתר מסוים מותר להגדיר contentSettings.cookies
נקבעת על סמך כתובת ה-URL של בקשת ה-HTTP (שהיא כתובת ה-URL הראשית במקרה הזה) וגם על סמך כתובת ה-URL שמוצגת בסרגל הכתובות (שנקראת כתובת ה-URL ה'משנית').
אם למספר כללים יש דפוסים ראשיים ומשניים, הכלל עם התבנית הראשית הספציפית יותר מקבל קדימות. אם למספר כללים יש דפוס ראשי זהה, הכלל עם הדפוס המשני הספציפי יותר מקבל קדימות. לדוגמה, הרשימה הבאה של צמדי דפוס ראשיים/משניים מסודרת לפי קדימות:
קדימות | דפוס ראשי | דפוס משני |
---|---|---|
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> |
מזהי משאבים
מזהי משאבים מאפשרים לציין הגדרות תוכן לסוגי משנה ספציפיים של סוג תוכן.
בשלב זה, סוג התוכן היחיד שתומך במזהי משאבים הוא contentSettings.plugins
, שבו מזהה משאב מזהה פלאגין ספציפי. כשמחילים הגדרות תוכן, תחילה נבדקות ההגדרות של הפלאגין הספציפי. אם לא נמצאו הגדרות לפלאגין מסוים, הגדרות התוכן הכלליות ליישומי פלאגין נבדקות.
לדוגמה, אם כלל להגדרת תוכן כולל את מזהה המשאב adobe-flash-player
ואת התבנית <all_urls>
, הוא מקבל עדיפות על פני כלל ללא מזהה משאב והדפוס https://www.example.com/*
, גם אם הדפוס הזה ספציפי יותר.
אפשר לקבל רשימה של מזהי משאבים לסוג תוכן מסוים באמצעות קריאה ל-method contentSettings.ContentSetting.getResourceIdentifiers()
. הרשימה שמוחזרת יכולה להשתנות בהתאם לקבוצת יישומי הפלאגין המותקנים במחשב של המשתמש, אבל Chrome מנסה לשמור על יציבות המזהים בכל עדכוני הפלאגין.
דוגמאות
כדי לנסות את ה-API הזה, צריך להתקין את הדוגמה של ContentSettings API מהמאגר chrome-extension-samples.
סוגים
AutoVerifyContentSetting
טיפוסים בני מנייה (enum)
CameraContentSetting
טיפוסים בני מנייה (enum)
ClipboardContentSetting
טיפוסים בני מנייה (enum)
ContentSetting
תכונות
-
מחיקה
void
הבטחהניקוי כל הכללים להגדרת תוכן שהוגדרו על ידי התוסף הזה.
הפונקציה
clear
נראית כך:(details: object, callback?: function) => {...}
-
פרטים
אובייקט
-
היקף
היקף אופציונלי
איפה לנקות את ההגדרה (ברירת מחדל: רגיל).
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
-
החזרות
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
-
-
get
void
הבטחהקבלת הגדרת התוכן הנוכחית של זוג כתובות URL.
הפונקציה
get
נראית כך:(details: object, callback?: function) => {...}
-
פרטים
אובייקט
-
גלישה פרטית
בוליאני אופציונלי
האם לבדוק את הגדרות התוכן של סשן פרטי. (ברירת המחדל היא FALSE)
-
primaryUrl
מחרוזת
כתובת ה-URL הראשית שעבורה יש לאחזר את הגדרת התוכן. חשוב לשים לב שהמשמעות של כתובת URL ראשית תלויה בסוג התוכן.
-
resourceIdentifier
ResourceIdentifier אופציונלי
מזהה ספציפי יותר של סוג התוכן שעבורו צריך לאחזר את ההגדרות.
-
secondaryUrl
מחרוזת אופציונלי
כתובת ה-URL המשנית שעבורה יש לאחזר את הגדרת התוכן. ברירת המחדל היא כתובת ה-URL הראשית. חשוב לשים לב שהמשמעות של כתובת URL משנית תלויה בסוג התוכן, ולא בכל סוגי התוכן נעשה שימוש בכתובות URL משניות.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(details: object) => void
-
פרטים
אובייקט
-
הגדרה
T
הגדרת התוכן ניתן לעיין בתיאור של האובייקטים הנפרדים של ContentSetting לגבי הערכים האפשריים.
-
-
-
החזרות
Promise<object>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
-
-
getResourceIdentifiers
void
הבטחההפונקציה
getResourceIdentifiers
נראית כך:(callback?: function) => {...}
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] אופציונלי
רשימה של מזהי משאבים לסוג התוכן הזה, או
undefined
אם סוג התוכן הזה לא כולל מזהי משאבים.
-
-
החזרות
Promise<ResourceIdentifier[]>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
-
-
הוגדר
void
הבטחהמחיל כלל חדש להגדרת תוכן.
הפונקציה
set
נראית כך:(details: object, callback?: function) => {...}
-
פרטים
אובייקט
-
primaryPattern
מחרוזת
הדפוס של כתובת האתר הראשית. מידע נוסף על הפורמט של תבניות נמצא במאמר תבניות להגדרת תוכן.
-
resourceIdentifier
ResourceIdentifier אופציונלי
מזהה המשאב של סוג התוכן.
-
היקף
היקף אופציונלי
איפה לקבוע את ההגדרה (ברירת מחדל: רגילה).
-
secondaryPattern
מחרוזת אופציונלי
הדפוס של כתובת ה-URL המשנית. ברירת המחדל היא התאמה לכל כתובות האתר. למידע נוסף על הפורמט של תבנית, ראה תבניות להגדרת תוכן.
-
הגדרה
הכול
ההגדרה שהוחלה על ידי הכלל הזה. ניתן לעיין בתיאור של האובייקטים הנפרדים של ContentSetting לגבי הערכים האפשריים.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
-
החזרות
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
-
CookiesContentSetting
טיפוסים בני מנייה (enum)
"session_only"
FullscreenContentSetting
Value
ImagesContentSetting
טיפוסים בני מנייה (enum)
JavascriptContentSetting
טיפוסים בני מנייה (enum)
LocationContentSetting
טיפוסים בני מנייה (enum)
MicrophoneContentSetting
טיפוסים בני מנייה (enum)
MouselockContentSetting
Value
MultipleAutomaticDownloadsContentSetting
טיפוסים בני מנייה (enum)
NotificationsContentSetting
טיפוסים בני מנייה (enum)
PluginsContentSetting
Value
PopupsContentSetting
טיפוסים בני מנייה (enum)
PpapiBrokerContentSetting
Value
ResourceIdentifier
סוג התוכן היחיד שנעשה בו שימוש במזהי משאבים הוא contentSettings.plugins
. אפשר למצוא מידע נוסף במאמר מזהי משאבים.
תכונות
-
תיאור
מחרוזת אופציונלי
תיאור קריא (לבני אדם) של המשאב.
-
id
מחרוזת
מזהה המשאב של סוג התוכן הנתון.
Scope
ההיקף של ContentSetting. אחת מהאפשרויות הבאות: regular
: הגדרה של פרופיל רגיל (שעוברת בירושה לפרופיל הפרטי אם לא מבוטלת אחרת במקום אחר),
incognito\_session\_only
: הגדרה לפרופיל פרטי שאפשר להגדיר רק במהלך סשן פרטי, והיא נמחקת כשהסשן הפרטי מסתיים (מבטלת את ההגדרות הרגילות).
טיפוסים בני מנייה (enum)
תכונות
automaticDownloads
האם לאפשר לאתרים להוריד מספר קבצים באופן אוטומטי. אחת מהאפשרויות: allow
: מתן הרשאה לאתרים להוריד מספר קבצים באופן אוטומטי, block
: לא לאפשר לאתרים להוריד מספר קבצים באופן אוטומטי,
ask
: תוצג שאלה כשאתר ירצה להוריד קבצים באופן אוטומטי אחרי הקובץ הראשון.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית.
autoVerify
האם לאפשר לאתרים להשתמש ב-Private State Tokens API. אחת מהאפשרויות: allow
: אתרים יכולים להשתמש ב-Private State Tokens API,
block
: חוסמים אתרים כך שלא יוכלו להשתמש ב-Private State Tokens API.
ברירת המחדל היא allow
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית. הערה: כשמבצעים קריאה אל set()
, התבנית הראשית חייבת להיות .
camera
האם לאפשר לאתרים לגשת למצלמה. אחת מהאפשרויות: allow
: נותנים לאתרים גישה למצלמה,
block
: לא מאפשרים לאתרים לגשת למצלמה,
ask
: מוצגת שאלה כשאתר רוצה לגשת למצלמה.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש גישה למצלמה. לא נעשה שימוש בכתובת ה-URL המשנית.
הערה: ההגדרה 'allow' לא חוקית אם שתי התבניות הן ''.
clipboard
האם לאפשר לאתרים לגשת ללוח באמצעות יכולות מתקדמות של Async Clipboard API. יכולות "מתקדמות" כוללות כל דבר מלבד כתיבת פורמטים מובנים לאחר פעולת משתמש, כלומר היכולת לקרוא, היכולת לכתוב פורמטים מותאמים אישית והיכולת לכתוב ללא פעולת משתמש. אחת מהאפשרויות: allow
: אתרים יכולים להשתמש ביכולות מתקדמות ללוח העריכה,
block
: לא מאפשרים לאתרים להשתמש ביכולות מתקדמות של לוח העריכה,
ask
: צריך לשאול כשאתר רוצה להשתמש ביכולות מתקדמות ללוח העריכה.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש גישה ללוח העריכה. לא נעשה שימוש בכתובת ה-URL המשנית.
cookies
האם לאפשר לאתרים להגדיר קובצי cookie ונתונים מקומיים אחרים. אחת מהאפשרויות: allow
: אישור קובצי cookie,
block
: חסימת קובצי cookie,
session\_only
: אישור של קובצי cookie רק בסשן הנוכחי.
ברירת המחדל היא allow
.
כתובת ה-URL הראשית היא כתובת ה-URL שמייצגת את המקור של קובץ ה-cookie. כתובת ה-URL המשנית היא כתובת ה-URL של המסגרת ברמה העליונה.
fullscreen
הוצא משימוש. אין יותר השפעה. הרשאת מסך מלא מוענקת עכשיו באופן אוטומטי לכל האתרים. הערך הוא תמיד allow
.
images
האם להציג תמונות. אחת מהאפשרויות: allow
: הצגת תמונות, block
: אין להציג תמונות.
ברירת המחדל היא allow
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. כתובת ה-URL המשנית היא כתובת ה-URL של התמונה.
javascript
האם להריץ JavaScript. אחת מהאפשרויות allow
: הרצת JavaScript, ו-block
: לא להריץ JavaScript.
ברירת המחדל היא allow
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית.
location
האם לאפשר מיקום גיאוגרפי. אחת מהאפשרויות: allow
: מתן הרשאה לאתרים לעקוב אחר המיקום הפיזי שלך,
block
: אתרים לא יוכלו לעקוב אחר המיקום הפיזי שלך,
ask
: תוצג שאלה לפני מתן הרשאה לאתרים לעקוב אחר המיקום הפיזי שלך.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש לקבל נתוני מיקום. כתובת ה-URL המשנית היא כתובת ה-URL של המסגרת ברמה העליונה (שעשויה להיות שונה מכתובת ה-URL המבקשת או לא).
microphone
האם לאפשר לאתרים לגשת למיקרופון. אחת מהאפשרויות: allow
: מאשרים לאתרים לגשת למיקרופון,
block
: לא מאפשרים לאתרים לגשת למיקרופון,
ask
: מוצגת שאלה כשאתר רוצה לגשת למיקרופון.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש גישה למיקרופון. לא נעשה שימוש בכתובת ה-URL המשנית.
הערה: ההגדרה 'allow' לא חוקית אם שתי התבניות הן ''.
mouselock
הוצא משימוש. אין יותר השפעה. הרשאה לנעילת עכבר מוענקת עכשיו באופן אוטומטי לכל האתרים. הערך הוא תמיד allow
.
notifications
האם לאפשר לאתרים להציג התראות בשולחן העבודה. אחת מהאפשרויות: allow
: מתן הרשאה לאתרים להציג התראות בשולחן העבודה,
block
: לא לאפשר לאתרים להציג התראות בשולחן העבודה,
ask
: תוצג שאלה כשאתר רוצה להציג התראות בשולחן העבודה.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שעבורו נשלחה ההתראה. לא נעשה שימוש בכתובת ה-URL המשנית.
plugins
הוצא משימוש. מאחר שהתמיכה ב-Flash הוסרה בגרסה 88 של Chrome, להרשאה הזו אין יותר השפעה. הערך הוא תמיד block
. המערכת תתעלם משיחות אל set()
ואל clear()
.
popups
האם לאפשר לאתרים להציג חלונות קופצים. אחת
מ-allow
: הרשאה לאתרים להציג חלונות קופצים,
block
: אתרים לא יכולים להציג חלונות קופצים.
ברירת המחדל היא block
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית.
unsandboxedPlugins
הוצא משימוש. בעבר, קביעה אם לאפשר לאתרים להפעיל יישומי פלאגין ללא ארגז חול, אך לאחר הסרת תהליך מתווך Flash ב-Chrome 88, להרשאה זו אין יותר השפעה. הערך הוא תמיד block
. המערכת תתעלם משיחות אל set()
ואל clear()
.