chrome.contentSettings

תיאור

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

קדימות של קו ביטול נעילה

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

לדוגמה, התבניות הבאות מסודרות לפי קדימות:

  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 ומעלה

טיפוסים בני מנייה (enum)

CameraContentSetting

Chrome 46 ואילך

טיפוסים בני מנייה (enum)

ClipboardContentSetting

Chrome 121 ומעלה

טיפוסים בני מנייה (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

Chrome 44 ואילך

טיפוסים בני מנייה (enum)

"session_only"

FullscreenContentSetting

Chrome 44 ואילך

Value

ImagesContentSetting

Chrome 44 ואילך

טיפוסים בני מנייה (enum)

JavascriptContentSetting

Chrome 44 ואילך

טיפוסים בני מנייה (enum)

LocationContentSetting

Chrome 44 ואילך

טיפוסים בני מנייה (enum)

MicrophoneContentSetting

Chrome 46 ואילך

טיפוסים בני מנייה (enum)

MouselockContentSetting

Chrome 44 ואילך

Value

MultipleAutomaticDownloadsContentSetting

Chrome 44 ואילך

טיפוסים בני מנייה (enum)

NotificationsContentSetting

Chrome 44 ואילך

טיפוסים בני מנייה (enum)

PluginsContentSetting

Chrome 44 ואילך

Value

PopupsContentSetting

Chrome 44 ואילך

טיפוסים בני מנייה (enum)

PpapiBrokerContentSetting

Chrome 44 ואילך

Value

ResourceIdentifier

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

תכונות

  • תיאור

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

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

  • id

    מחרוזת

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

Scope

Chrome 44 ואילך

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

טיפוסים בני מנייה (enum)

תכונות

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. כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית. הערה: כשמבצעים קריאה אל set(), התבנית הראשית חייבת להיות .

סוג

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 ואילך

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

סוג

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' לא חוקית אם שתי התבניות הן ''.

סוג

ContentSetting<MicrophoneContentSetting>

mouselock

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

סוג

ContentSetting<MouselockContentSetting>

notifications

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

סוג

ContentSetting<NotificationsContentSetting>

plugins

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

סוג

ContentSetting<PluginsContentSetting>

popups

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

סוג

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

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

סוג

ContentSetting<PpapiBrokerContentSetting>