תיאור
שימוש ב-chrome.contentSettings
API כדי לשנות את ההגדרות ששולטות ביכולת של אתרים להשתמש בתכונות כמו קובצי cookie, JavaScript ויישומי פלאגין. באופן כללי, הגדרות התוכן מאפשרות לכם להתאים אישית את התנהגות Chrome בכל אתר בנפרד, במקום באופן גלובלי.
הרשאות
contentSettings
כדי להשתמש ב-API, צריך להצהיר על ההרשאה "contentSettings"
במניפסט של התוסף. לדוגמה:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
מושגים ושימוש
דפוסים של הגדרות תוכן
תוכלו להשתמש בתבניות כדי לציין את האתרים שאליהם משפיעה כל הגדרת תוכן. לדוגמה,
https://*.youtube.com/*
מציין את youtube.com ואת כל תתי-הדומיין שלו. התחביר לתבניות של הגדרת תוכן זהה לתחביר של תבניות התאמה, עם כמה הבדלים:
- בכתובות ה-URL מסוג
http
,https
ו-ftp
, הנתיב חייב להיות תו כללי לחיפוש (/*
). בכתובות ה-URL מסוגfile
, הנתיב חייב להיות מפורט במלואו ואסור שיכיל תווים כלליים לחיפוש. - בניגוד להתאמה לתבניות, התבניות של הגדרות התוכן יכולות לציין מספר יציאה. אם מציינים מספר יציאה, הדפוס תואם רק לאתרים עם אותה היציאה. אם לא מציינים מספר יציאה, הדפוס תואם לכל היציאות.
קדימות של דפוסים
כאשר יותר מכלל אחד של הגדרת תוכן חל על אתר נתון, הכלל עם התבנית הספציפית יותר מקבל עדיפות.
לדוגמה, התבניות הבאות מסודרות לפי קדימות:
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
"block"
"ask"
ClipboardContentSetting
Enum
"block"
ContentSetting
מאפיינים
-
נקה
ריק
Promiseמחיקת כל כללי הגדרת התוכן שהוגדרו על ידי התוסף הזה.
הפונקציה
clear
נראית כך:(details: object, callback?: function) => {...}
-
פרטים
אובייקט
-
היקף
היקף אופציונלי
היכן לנקות את ההגדרה (ברירת מחדל: רגילה).
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
-
החזרות
Promise<void>
Chrome מגרסה 96 ואילךיש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
-
-
get
ריק
Promiseהפונקציה מקבלת את הגדרת התוכן הנוכחית עבור זוג נתון של כתובות 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 ואילךיש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
-
-
getResourceIdentifiers
ריק
Promiseהפונקציה
getResourceIdentifiers
נראית כך:(callback?: function) => {...}
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] אופציונלי
רשימה של מזהי משאבים לסוג התוכן הזה, או
undefined
אם בסוג התוכן הזה לא נעשה שימוש במזהי משאבים.
-
-
החזרות
Promise<ResourceIdentifier[]>
Chrome מגרסה 96 ואילךיש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
-
-
הוגדר
ריק
Promiseהחלת כלל חדש להגדרת תוכן.
הפונקציה
set
נראית כך:(details: object, callback?: function) => {...}
-
פרטים
אובייקט
-
primaryPattern
מחרוזת
התבנית של כתובת ה-URL הראשית. פרטים על הפורמט של התבנית מופיעים במאמר תבניות של הגדרות תוכן.
-
resourceIdentifier
ResourceIdentifier אופציונלי
מזהה המשאב של סוג התוכן.
-
היקף
היקף אופציונלי
המיקום שבו מגדירים את ההגדרה (ברירת המחדל: רגיל).
-
secondaryPattern
מחרוזת אופציונלי
הדפוס של כתובת ה-URL המשנית. ברירת המחדל היא התאמה לכל כתובות ה-URL. פרטים על הפורמט של התבנית מופיעים במאמר תבניות של הגדרות תוכן.
-
הגדרה
כל
ההגדרה שהוחלה על ידי הכלל הזה. הערכים האפשריים מפורטים בתיאור של אובייקטי ContentSetting השונים.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
-
החזרות
Promise<void>
גרסה 96 ואילך של Chromeהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל יש גם קריאות חוזרות (callback) לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
-
CookiesContentSetting
Enum
"block"
"session_only"
FullscreenContentSetting
ערך
"allow"
ImagesContentSetting
Enum
JavascriptContentSetting
Enum
LocationContentSetting
Enum
"block"
"ask"
MicrophoneContentSetting
Enum
"block"
"ask"
MouselockContentSetting
ערך
"allow"
MultipleAutomaticDownloadsContentSetting
Enum
"block"
"ask"
NotificationsContentSetting
Enum
"block"
"ask"
PluginsContentSetting
ערך
"block"
PopupsContentSetting
Enum
PpapiBrokerContentSetting
ערך
"block"
ResourceIdentifier
סוג התוכן היחיד שמשתמשים במזהי משאבים הוא contentSettings.plugins
. מידע נוסף זמין במאמר מזהי משאבים.
מאפיינים
-
תיאור
מחרוזת אופציונלי
תיאור קריא של המשאב.
-
id [מזהה]
מחרוזת
מזהה המשאב של סוג התוכן הנתון.
Scope
ההיקף של הגדרות התוכן. אחת מהאפשרויות: 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 המשנית לא בשימוש.
הערה: ההגדרה 'אישור' אינה חוקית אם שתי הדפוסים הן ''.
סוג
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 המשנית לא בשימוש.
הערה: ההגדרה 'הרשאה' לא תקפה אם שני התבניות הן ''.
סוג
mouselock
הוצא משימוש. אין יותר השפעה. ההרשאה לנעילת העכבר הוענקה עכשיו באופן אוטומטי לכל האתרים. הערך הוא תמיד allow
.
סוג
notifications
האם לאפשר לאתרים להציג התראות בשולחן העבודה. אחת מהאפשרויות
allow
: מתן הרשאה לאתרים להציג התראות בשולחן העבודה,
block
: לא לאפשר לאתרים להציג התראות בשולחן העבודה,
ask
: צריך לשאול אותי כשאתר רוצה להציג התראות בשולחן העבודה.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שבו תוצג ההתראה. לא נעשה שימוש בכתובת ה-URL המשנית.
סוג
plugins
הוצא משימוש. התמיכה ב-Flash הוסרה ב-Chrome 88, ולכן להרשאה הזו אין יותר השפעה. הערך הוא תמיד block
. המערכת תתעלם משיחות אל set()
ואל clear()
.
popups
האם לאפשר לאתרים להציג חלונות קופצים. אחת מהאפשרויות הבאות: allow
: לאפשר לאתרים להציג חלונות קופצים, block
: לא לאפשר לאתרים להציג חלונות קופצים.
ברירת המחדל היא block
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית.
unsandboxedPlugins
הוצא משימוש. בעבר, ההרשאה הזו שלטה אם לאפשר לאתרים להפעיל יישומי פלאגין ללא ארגז חול. עם זאת, לאחר ההסרה של תהליך Flash Broker ב-Chrome 88, ההרשאה הזו כבר לא משפיעה. הערך הוא תמיד block
. המערכת תתעלם מהשיחות אל set()
ו-clear()
.