chrome.permissions

refresh date: 2026-09-25 robots: noindex

תיאור

משתמשים ב-API של chrome.permissions כדי לבקש הרשאות אופציונליות שהוצהרו בזמן הריצה ולא בזמן ההתקנה, כדי שהמשתמשים יבינו למה ההרשאות נחוצות ויתנו רק את ההרשאות שצריך.

סקירה כללית

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

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

כפתור של תוסף שמאפשר תכונות נוספות

כדי להציג את האתרים המובילים של המשתמש, נדרשת ההרשאה topSites, שכוללת את האזהרה הבאה.

אזהרה לגבי תוסף ל-topSites API

הטמעת הרשאות אופציונליות

שלב 1: מחליטים אילו הרשאות נדרשות ואילו הרשאות הן אופציונליות

תוסף יכול להצהיר על הרשאות נדרשות ועל הרשאות אופציונליות. באופן כללי, כדאי:

  • השתמשו בהרשאות הנדרשות כשהן נחוצות לפונקציונליות הבסיסית של התוסף.
  • השתמשו בהרשאות אופציונליות כשהן נדרשות לתכונות אופציונליות בתוסף.

יתרונות של הרשאות נדרשות:

  • פחות בקשות: תוסף יכול לבקש מהמשתמש לאשר את כל ההרשאות בבת אחת.
  • פיתוח פשוט יותר: ההרשאות הנדרשות מובטחות.

היתרונות של הרשאות אופציונליות:

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

שלב 2: הצהרה על הרשאות אופציונליות במניפסט

מצהירים על הרשאות אופציונליות במניפסט של התוסף באמצעות המפתח optional_permissions, באותו פורמט כמו השדה permissions:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

אם אתם רוצים לבקש מארחים שאתם מגלים רק בזמן הריצה, הוסיפו את "https://*/*" לשדה optional_host_permissions של התוסף. כך אפשר לציין כל מקור ב-Permissions.origins, כל עוד יש לו סכימה תואמת.

הרשאות שאי אפשר לציין כאופציונליות

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

הרשאה תיאור
"debugger" ‫chrome.debugger API משמש כהעברה חלופית לפרוטוקול ניפוי הבאגים מרחוק של Chrome.
"declarativeNetRequest" נותנת לתוסף גישה ל-API של chrome.declarativeNetRequest.
"devtools" מאפשרת לתוסף להרחיב את הפונקציונליות של כלי הפיתוח ל-Chrome.
"experimental" Canary ו-Dev channel בלבד. נותנת לתוסף גישה לממשקי API של chrome.experimental.
"geolocation" מאפשרת לתוסף להשתמש ב-API של המיקום הגיאוגרפי ב-HTML5.
"mdns" מעניקה לתוסף גישה ל-API של chrome.mdns.
"proxy" נותנת לתוסף גישה ל-API של chrome.proxy כדי לנהל את ההגדרות של שרת ה-proxy ב-Chrome.
"tts" ‫chrome.tts API משמיע המרת טקסט לדיבור (TTS) מסונתזת.
"ttsEngine" ‫chrome.ttsEngine API מטמיע מנוע המרת טקסט לדיבור (TTS) באמצעות תוסף.
"wallpaper" ב-ChromeOS בלבד. משתמשים ב-API‏ chrome.wallpaper כדי לשנות את הטפט ב-ChromeOS.

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

‫שלב 3: מבקשים הרשאות אופציונליות

מבקשים את ההרשאות מתוך תנועה של המשתמש באמצעות permissions.request():

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  chrome.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

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

דוגמה להודעה לאישור הרשאה

שלב 4: בודקים את ההרשאות הנוכחיות של התוסף

כדי לבדוק אם לתוסף יש הרשאה ספציפית או קבוצת הרשאות, משתמשים ב-permission.contains():

chrome.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

שלב 5: מסירים את ההרשאות

מומלץ להסיר הרשאות כשכבר לא צריך אותן. אחרי שהרשאה הוסרה, קריאה ל-permissions.request() בדרך כלל מוסיפה את ההרשאה בחזרה בלי להציג בקשה למשתמש.

chrome.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

סוגים

Permissions

מאפיינים

  • מקורות

    string[] אופציונלי

    רשימת ההרשאות למארחים, כולל אלה שצוינו במפתחות optional_permissions או permissions במניפסט, ואלה שמשויכות לסקריפטים של תוכן.

  • permissions

    string[] אופציונלי

    רשימה של הרשאות עם שם (לא כולל מארחים או מקורות).

Methods

contains()

Promise 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

בודק אם לתוסף יש את ההרשאות שצוינו.

פרמטרים

  • permissions

    הרשאות

  • callback

    function optional

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

    (result: boolean) => void

    • תוצאה

      בוליאני

      True אם לתוסף יש את ההרשאות שצוינו. אם מקור מסוים צוין גם כהרשאה אופציונלית וגם כתבנית התאמה של סקריפט תוכן, הפונקציה תחזיר את הערך false, אלא אם שתי ההרשאות ניתנו.

החזרות

  • Promise<boolean>

    ‫Chrome מגרסה 96 ואילך

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

getAll()

Promise 
chrome.permissions.getAll(
  callback?: function,
): Promise<Permissions>

מקבלת את קבוצת ההרשאות הנוכחית של התוסף.

פרמטרים

  • callback

    function optional

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

    (permissions: Permissions) => void

    • permissions

      הרשאות

      ההרשאות הפעילות של התוסף. שימו לב שהמאפיין origins יכיל מקורות מורשים מאלה שצוינו במפתחות permissions ו-optional_permissions במניפסט, ומאלה שמשויכים לסקריפטים של תוכן.

החזרות

  • Promise<Permissions>

    ‫Chrome מגרסה 96 ואילך

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

remove()

Promise 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

הסרת הגישה להרשאות שצוינו. אם יש בעיות בהסרת ההרשאות, ההבטחה תידחה.

פרמטרים

  • permissions

    הרשאות

  • callback

    function optional

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

    (removed: boolean) => void

    • הוסר

      בוליאני

      הערך True אם ההרשאות הוסרו.

החזרות

  • Promise<boolean>

    ‫Chrome מגרסה 96 ואילך

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

request()

Promise 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

מבקשת גישה להרשאות שצוינו, ומציגה למשתמש בקשה אם צריך. ההרשאות האלה צריכות להיות מוגדרות בשדה optional_permissions של המניפסט, או להיות הרשאות נדרשות שהמשתמש לא העניק. המערכת תתעלם מנתיבים בתבניות המקור. אפשר לבקש קבוצות משנה של הרשאות מקור אופציונליות. לדוגמה, אם מציינים את *://*\/* בקטע optional_permissions של המניפסט, אפשר לבקש את http://example.com/. אם יש בעיות בבקשת ההרשאות, ה-promise יידחה.

פרמטרים

  • permissions

    הרשאות

  • callback

    function optional

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

    (granted: boolean) => void

    • GRANTED

      בוליאני

      הערך True אם המשתמש העניק את ההרשאות שצוינו.

החזרות

  • Promise<boolean>

    ‫Chrome מגרסה 96 ואילך

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

אירועים

onAdded

chrome.permissions.onAdded.addListener(
  callback: function,
)

מופעל כשהתוסף מקבל הרשאות חדשות.

פרמטרים

  • callback

    פונקציה

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

    (permissions: Permissions) => void

onRemoved

chrome.permissions.onRemoved.addListener(
  callback: function,
)

מופעל כשגישה להרשאות הוסרה מהתוסף.

פרמטרים

  • callback

    פונקציה

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

    (permissions: Permissions) => void