chrome.contentSettings

תיאור

אפשר להשתמש ב-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, הנתיב חייב להיות מפורט לחלוטין ואסור להכיל תווים כלליים.
  • בניגוד לתבניות התאמה, תבניות של הגדרות תוכן יכולות לציין מספר יציאה. אם מציינים מספר יציאה, התבנית מתאימה רק לאתרים עם היציאה הזו. אם לא מציינים מספר יציאה, הדפוס תואם לכל היציאות.

קדימות של דפוסים

אם יותר מכלל אחד של הגדרות תוכן חל על אתר מסוים, הכלל עם הדפוס הספציפי יותר מקבל עדיפות.

לדוגמה, הדפוסים הבאים מסודרים לפי סדר העדיפות:

  1. https://www.example.com/*
  2. ‫https://*.example.com/* (התאמה ל-example.com ולכל תתי-הדומיינים)
  3. <all_urls> (התאמה לכל כתובת URL)

יש שלושה סוגים של תווים כלליים שמשפיעים על מידת הספציפיות של תבנית:

  • תווים כלליים לחיפוש ביציאה (לדוגמה, https://www.example.com:*/*)
  • תווים כלליים בסכמה (לדוגמה, *://www.example.com:123/*)
  • תווים כלליים לחיפוש בשם המארח (לדוגמה, https://*.example.com:123/*)

אם תבנית אחת ספציפית יותר מתבנית אחרת בחלק אחד אבל פחות ספציפית בחלק אחר, החלקים השונים נבדקים בסדר הבא: שם המארח, הסכימה, היציאה. לדוגמה, הדפוסים הבאים מסודרים לפי סדר עדיפות:

  1. https://www.example.com:*/* מציין את שם המארח ואת הסכימה.
  2. *:/www.example.com:123/* לא גבוהה, כי למרות שהיא מציינת את שם המארח, היא לא מציינת את הסכימה.
  3. ‫https://*.example.com:123/* הדירוג נמוך יותר כי למרות שהיציאה והסכמה מוגדרות, יש תו כללי בשם המארח.

תבניות ראשיות ומשניות

כתובת ה-URL שנלקחת בחשבון כשמחליטים איזו הגדרת תוכן להחיל תלויה בסוג התוכן. לדוגמה, ההגדרות של contentSettings.notifications מבוססות על כתובת ה-URL שמוצגת בתיבת הכתובת. כתובת ה-URL הזו נקראת כתובת ה-URL הראשית.

יכול להיות שסוגי תוכן מסוימים יכללו כתובות URL נוספות. לדוגמה, ההחלטה אם לאתר מסוים מותר להגדיר contentSettings.cookies מתקבלת על סמך כתובת ה-URL של בקשת ה-HTTP (שהיא כתובת ה-URL הראשית במקרה הזה) וגם על סמך כתובת ה-URL שמוצגת בסרגל הכתובות (שנקראת כתובת ה-URL המשנית).

אם לכמה כללים יש תבניות ראשיות ומשניות, הכלל עם התבנית הראשית הספציפית יותר מקבל עדיפות. אם לכמה כללים יש את אותה תבנית ראשית, הכלל עם התבנית המשנית הספציפית יותר מקבל עדיפות. לדוגמה, הרשימה הבאה של צמדי דפוסים ראשיים/משניים מסודרת לפי סדר עדיפות:

קדימותדוגמה ראשיתדפוס משני
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>

מזהי משאבים

מזהי משאבים מאפשרים לכם לציין הגדרות תוכן לסוגי משנה ספציפיים של סוג תוכן. נכון לעכשיו, סוג התוכן היחיד שתומך במזהי משאבים הוא contentSettings.plugins, שבו מזהה משאב מציין פלאגין ספציפי. כשמחילים הגדרות תוכן, קודם נבדקות ההגדרות של הפלאגין הספציפי. אם לא נמצאו הגדרות עבור הפלאגין הספציפי, המערכת בודקת את הגדרות התוכן הכלליות של הפלאגינים.

לדוגמה, אם לכלל הגדרות תוכן יש מזהה משאב adobe-flash-player ותבנית <all_urls>, הוא מקבל עדיפות על פני כלל ללא מזהה משאב והתבנית https://www.example.com/*, גם אם התבנית הזו ספציפית יותר.

כדי לקבל רשימה של מזהי משאבים לסוג תוכן מסוים, צריך להפעיל את ה-method‏ contentSettings.ContentSetting.getResourceIdentifiers. הרשימה שמוחזרת יכולה להשתנות בהתאם לסט של התוספים המותקנים במחשב של המשתמש, אבל Chrome מנסה לשמור על יציבות המזהים גם אחרי עדכוני תוספים.

דוגמאות

כדי לנסות את ה-API הזה, צריך להתקין את הדוגמה של contentSettings API ממאגר chrome-extension-samples.

סוגים

AutoVerifyContentSetting

‫Chrome 113 ואילך

ספירה

‫'allow'

"block"

CameraContentSetting

‫Chrome 46 ואילך

ספירה

‫'allow'

"block"

‎"ask"

ClipboardContentSetting

‫Chrome 121 ואילך

ספירה

‫'allow'

"block"

‎"ask"

ContentSetting

מאפיינים

  • נקה

    void

    Promise

    ניקוי כל כללי הגדרות התוכן שהוגדרו על ידי התוסף הזה.

    הפונקציה clear נראית כך: 

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

    • פרטים

      אובייקט

      • היקף

        היקף אופציונלי

        איפה מבטלים את ההגדרה (ברירת מחדל: רגילה).

    • callback

      פונקציה אופציונלית

      הפרמטר callback נראה כך: 

      () => void

    • החזרות

      Promise<void>

      ‫Chrome 96 ואילך

      ההבטחות נתמכות רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש בפונקציות קריאה חוזרת (callback).

  • get

    void

    Promise

    מקבל את הגדרת התוכן הנוכחית עבור צמד נתון של כתובות URL.

    הפונקציה get נראית כך: 

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

    • פרטים

      אובייקט

      • מצב פרטי

        ‫boolean אופציונלי

        האם לבדוק את הגדרות התוכן עבור סשן במצב פרטי. (ברירת מחדל: false)

      • primaryUrl

        מחרוזת

        כתובת ה-URL הראשית שצריך לאחזר עבורה את הגדרת התוכן. חשוב לזכור שהמשמעות של כתובת URL ראשית תלויה בסוג התוכן.

      • resourceIdentifier

        ‫ResourceIdentifier אופציונלי

        מזהה ספציפי יותר של סוג התוכן שעבורו צריך לאחזר את ההגדרות.

      • secondaryUrl

        מחרוזת אופציונלי

        כתובת ה-URL המשנית שעבורה צריך לאחזר את הגדרת התוכן. ברירת המחדל היא כתובת ה-URL הראשית. חשוב לדעת שהמשמעות של כתובת URL משנית תלויה בסוג התוכן, ולא כל סוגי התוכן משתמשים בכתובות URL משניות.

    • callback

      פונקציה אופציונלית

      הפרמטר callback נראה כך: 

      (details: object) => void

      • פרטים

        אובייקט

        • הגדרה

          T

          הגדרת התוכן. הערכים האפשריים מפורטים בתיאור של כל אחד מאובייקטי ContentSetting.

    • החזרות

      Promise<object>

      ‫Chrome 96 ואילך

      ההבטחות נתמכות רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש בפונקציות קריאה חוזרת (callback).

  • getResourceIdentifiers

    void

    Promise

    הפונקציה getResourceIdentifiers נראית כך: 

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

    • callback

      פונקציה אופציונלית

      הפרמטר callback נראה כך: 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ‫ResourceIdentifier[] optional

        רשימה של מזהי משאבים לסוג התוכן הזה, או undefined אם סוג התוכן הזה לא משתמש במזהי משאבים.

    • החזרות

      Promise<ResourceIdentifier[]>

      ‫Chrome 96 ואילך

      ההבטחות נתמכות רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש בפונקציות קריאה חוזרת (callback).

  • הוגדר

    void

    Promise

    החלה של כלל חדש להגדרת תוכן.

    הפונקציה set נראית כך: 

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

    • פרטים

      אובייקט

      • primaryPattern

        מחרוזת

        התבנית של כתובת ה-URL הראשית. פרטים על הפורמט של תבנית מופיעים במאמר תבניות של הגדרות תוכן.

      • resourceIdentifier

        ‫ResourceIdentifier אופציונלי

        מזהה המשאב של סוג התוכן.

      • היקף

        היקף אופציונלי

        איפה מגדירים את ההגדרה (ברירת מחדל: רגיל).

      • secondaryPattern

        מחרוזת אופציונלי

        התבנית של כתובת ה-URL המשנית. ברירת המחדל היא התאמה לכל כתובות ה-URL. פרטים על הפורמט של תבנית מופיעים במאמר תבניות של הגדרות תוכן.

      • הגדרה

        כל

        ההגדרה שמוחלת על ידי הכלל הזה. הערכים האפשריים מפורטים בתיאור של כל אחד מאובייקטי ContentSetting.

    • callback

      פונקציה אופציונלית

      הפרמטר callback נראה כך: 

      () => void

    • החזרות

      Promise<void>

      ‫Chrome 96 ואילך

      ההבטחות נתמכות רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש בפונקציות קריאה חוזרת (callback).

CookiesContentSetting

‫Chrome 44 ואילך

ספירה

‫'allow'

"block"

‫"session_only"

FullscreenContentSetting

‫Chrome 44 ואילך

ערך

‫'allow'

ImagesContentSetting

‫Chrome 44 ואילך

ספירה

‫'allow'

"block"

JavascriptContentSetting

‫Chrome 44 ואילך

ספירה

‫'allow'

"block"

LocationContentSetting

‫Chrome 44 ואילך

ספירה

‫'allow'

"block"

‎"ask"

MicrophoneContentSetting

‫Chrome 46 ואילך

ספירה

‫'allow'

"block"

‎"ask"

MouselockContentSetting

‫Chrome 44 ואילך

ערך

‫'allow'

MultipleAutomaticDownloadsContentSetting

‫Chrome 44 ואילך

ספירה

‫'allow'

"block"

‎"ask"

NotificationsContentSetting

‫Chrome 44 ואילך

ספירה

‫'allow'

"block"

‎"ask"

PluginsContentSetting

‫Chrome 44 ואילך

ערך

"block"

PopupsContentSetting

‫Chrome 44 ואילך

ספירה

‫'allow'

"block"

PpapiBrokerContentSetting

‫Chrome 44 ואילך

ערך

"block"

ResourceIdentifier

סוג התוכן היחיד שמשתמש במזהי משאבים הוא contentSettings.plugins. מידע נוסף זמין במאמר מזהי משאבים.

מאפיינים

  • תיאור

    מחרוזת אופציונלי

    תיאור קריא (לבני אדם) של המשאב.

  • id [מזהה]

    מחרוזת

    מזהה המשאב של סוג התוכן הנתון.

Scope

‫Chrome 44 ואילך

ההיקף של ContentSetting. אחת מהאפשרויות הבאות:regular: הגדרה לפרופיל רגיל (שמועברת בירושה לפרופיל במצב פרטי אם לא מוגדרת אחרת במקום אחר),incognito\_session\_only: הגדרה לפרופיל במצב פרטי שאפשר להגדיר רק במהלך סשן במצב פרטי ונמחקת כשהסשן מסתיים (מבטלת את ההגדרות הרגילות).

ספירה

‫"regular"

‫"incognito_session_only"

SoundContentSetting

‫Chrome 141+‎

ספירה

‫'allow'

"block"

מאפיינים

automaticDownloads

האם לאפשר לאתרים להוריד מספר קבצים באופן אוטומטי. אחת מהאפשרויות הבאות: allow: לאפשר לאתרים להוריד באופן אוטומטי קבצים מרובים, block: לא לאפשר לאתרים להוריד באופן אוטומטי קבצים מרובים, ask: לשאול כשאתר רוצה להוריד קבצים באופן אוטומטי אחרי הקובץ הראשון. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

‫Chrome 113 ואילך

האם לאפשר לאתרים להשתמש ב-Private State Tokens API. אחת מהאפשרויות הבאות: allow: מאפשר לאתרים להשתמש ב-Private State Tokens API, block: חסימת אתרים משימוש ב-Private State Tokens API. ברירת המחדל היא allow. כשמתקשרים אל set(), תבנית כתובת ה-URL הראשית חייבת להיות <all_urls>. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

ContentSetting<AutoVerifyContentSetting>

camera

‫Chrome 46 ואילך

האם לאפשר לאתרים גישה למצלמה. אחת מהאפשרויות הבאות: allow: לאפשר לאתרים לגשת למצלמה, block: לא לאפשר לאתרים לגשת למצלמה, ask: לשאול כשאתר רוצה לגשת למצלמה. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שבו התבקשה גישה למצלמה. לא נעשה שימוש בכתובת ה-URL המשנית. הערה: ההגדרה 'allow' לא תקפה אם שני הדפוסים הם '<all_urls>'.

סוג

ContentSetting<CameraContentSetting>

clipboard

‫Chrome 121 ואילך

האם לאפשר לאתרים לגשת ללוח העריכה באמצעות יכולות מתקדמות של Async Clipboard API. היכולות ה'מתקדמות' כוללות כל דבר חוץ מכתיבת פורמטים מוטמעים אחרי פעולת משתמש, כלומר היכולת לקרוא, היכולת לכתוב פורמטים בהתאמה אישית והיכולת לכתוב ללא פעולת משתמש. אחת מהאפשרויות הבאות: allow: אתרים יכולים להשתמש ביכולות מתקדמות של לוח העריכה, block: אתרים לא יכולים להשתמש ביכולות מתקדמות של לוח העריכה, ask: תופיע בקשה כשאתר ירצה להשתמש ביכולות מתקדמות של לוח העריכה. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש גישה ללוח העריכה. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

ContentSetting<ClipboardContentSetting>

cookies

האם לאפשר לאתרים להגדיר קובצי Cookie ונתונים מקומיים אחרים. אחת מהאפשרויות הבאות: allow: קבלת קובצי Cookie, block: חסימת קובצי Cookie, session\_only: קבלת קובצי Cookie רק לסשן הנוכחי. ברירת המחדל היא allow. כתובת ה-URL הראשית היא כתובת ה-URL שמייצגת את מקור קובץ ה-Cookie. כתובת ה-URL המשנית היא כתובת ה-URL של המסגרת ברמה העליונה.

סוג

ContentSetting<CookiesContentSetting>

fullscreen

הוצא משימוש. אין לה יותר השפעה. ההרשאה למסך מלא ניתנת עכשיו באופן אוטומטי לכל האתרים. הערך הוא תמיד allow.

סוג

ContentSetting<FullscreenContentSetting>

images

האם להציג תמונות. אחת מהאפשרויות הבאות: allow: הצגת תמונות, block: לא להציג תמונות. ברירת המחדל היא allow. כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. כתובת ה-URL המשנית היא כתובת ה-URL של התמונה.

סוג

‪ContentSetting<ImagesContentSetting>

javascript

האם להריץ JavaScript. אחת מהאפשרויות הבאות: allow: הפעלת JavaScript, block: לא להפעיל JavaScript. ברירת המחדל היא allow. כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

ContentSetting<JavascriptContentSetting>

location

האם לאפשר מיקום גיאוגרפי. אחת מהאפשרויות הבאות:allow: לאפשר לאתרים לעקוב אחרי המיקום הפיזי שלכם,block: לא לאפשר לאתרים לעקוב אחרי המיקום הפיזי שלכם,ask: לשאול לפני שמאפשרים לאתרים לעקוב אחרי המיקום הפיזי שלכם. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש נתוני מיקום. כתובת ה-URL המשנית היא כתובת ה-URL של המסגרת ברמה העליונה (יכול להיות שהיא שונה מכתובת ה-URL של הבקשה ויכול להיות שלא).

סוג

‫ContentSetting<LocationContentSetting>

microphone

‫Chrome 46 ואילך

האם לאפשר לאתרים לגשת למיקרופון. אחת מהאפשרויות הבאות: allow: לאפשר לאתרים לגשת למיקרופון, block: לא לאפשר לאתרים לגשת למיקרופון, ask: לשאול כשאתר רוצה לגשת למיקרופון. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש גישה למיקרופון. לא נעשה שימוש בכתובת ה-URL המשנית. הערה: ההגדרה 'allow' לא תקפה אם שני הדפוסים הם '<all_urls>'.

סוג

ContentSetting<MicrophoneContentSetting>

mouselock

הוצא משימוש. אין לה יותר השפעה. ההרשאה לנעילת העכבר מוענקת עכשיו באופן אוטומטי לכל האתרים. הערך הוא תמיד allow.

סוג

ContentSetting<MouselockContentSetting>

notifications

האם לאפשר לאתרים להציג התראות בשולחן העבודה. אחת מהאפשרויות הבאות: allow: לאפשר לאתרים להציג התראות בשולחן העבודה, block: לא לאפשר לאתרים להציג התראות בשולחן העבודה, ask: לשאול כשאתר רוצה להציג התראות בשולחן העבודה. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שבו רוצים להציג את ההתראה. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

‫ContentSetting<NotificationsContentSetting>

plugins

הוצא משימוש. התמיכה ב-Flash הוסרה ב-Chrome 88, ולכן להרשאה הזו אין יותר השפעה. הערך הוא תמיד block. המערכת תתעלם משיחות אל set() ואל clear().

סוג

ContentSetting<PluginsContentSetting>

popups

האם לאפשר לאתרים להציג חלונות קופצים. אחת מהאפשרויות הבאות: allow: אפשר לאתרים להציג חלונות קופצים, block: אתרים לא יכולים להציג חלונות קופצים. ברירת המחדל היא block. כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

‫ContentSetting<PopupsContentSetting>

unsandboxedPlugins

הוצא משימוש. בעבר, ההגדרה הזו קבעה אם לאפשר לאתרים להפעיל פלאגינים ללא ארגז חול, אבל אחרי שהסרנו את תהליך ברוקר Flash ב-Chrome 88, להרשאה הזו אין יותר השפעה. הערך הוא תמיד block. המערכת תתעלם משיחות אל set() ואל clear().

סוג

ContentSetting<PpapiBrokerContentSetting>