browser.permissions

תיאור

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

מושגים ושימוש

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

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

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

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

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

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

שלב 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" ‫browser.debugger API משמש כהעברה חלופית לפרוטוקול ניפוי הבאגים מרחוק של Chrome.
"declarativeNetRequest" נותנת לתוסף גישה ל-API של browser.declarativeNetRequest.
"devtools" מאפשרת לתוסף להרחיב את הפונקציונליות של כלי הפיתוח ל-Chrome.
"geolocation" מאפשרת לתוסף להשתמש ב-API של המיקום הגיאוגרפי ב-HTML5.
"mdns" מעניקה לתוסף גישה ל-API של browser.mdns.
"proxy" נותנת לתוסף גישה ל-API של browser.proxy כדי לנהל את הגדרות שרת ה-proxy של Chrome.
"tts" ‫browser.tts API משמיע המרת טקסט לדיבור (TTS) מסונתזת.
"ttsEngine" ה-API‏ browser.ttsEngine מטמיע מנוע המרת טקסט לדיבור (TTS) באמצעות תוסף.
"wallpaper" ב-ChromeOS בלבד. משתמשים ב-API‏ browser.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.
  browser.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():

browser.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() בדרך כלל מוסיפה את ההרשאה בחזרה בלי להציג בקשה למשתמש.

browser.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

addHostAccessRequest()

‫Chrome 133 ואילך ‫browser.* ‎ מגרסה Chrome 148 ‫MV3 ואילך 
browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

מוסיפה בקשת גישה למארח. הבקשה תועבר למשתמש רק אם אפשר לתת לתוסף גישה למארח בבקשה. הבקשה תאופס בניווט ממקורות שונים. אם הבקשה תאושר, האתר יקבל גישה קבועה למקור הראשי של האתר

פרמטרים

  • בקשה

    אובייקט

    • documentId

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

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

    • קו ביטול נעילה

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

      תבנית ה-URL שבה אפשר להציג בקשות גישה למארח. אם מציינים את המאפיין הזה, בקשות גישה למארח יוצגו רק בכתובות URL שתואמות לתבנית הזו.

    • tabId

      מספר אופציונלי

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

החזרות

  • Promise<void>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

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

פרמטרים

החזרות

  • Promise<boolean>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

getAll()

browser.permissions.getAll(): Promise<Permissions>

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

החזרות

  • Promise<Permissions>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

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

פרמטרים

החזרות

  • Promise<boolean>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

removeHostAccessRequest()

‫Chrome 133 ואילך ‫browser.* ‎ מגרסה Chrome 148 ‫MV3 ואילך 
browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

הסרת בקשת גישה של מארח, אם קיימת.

פרמטרים

  • בקשה

    אובייקט

    • documentId

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

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

    • קו ביטול נעילה

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

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

    • tabId

      מספר אופציונלי

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

החזרות

  • Promise<void>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

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

פרמטרים

החזרות

  • Promise<boolean>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

אירועים

onAdded

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

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

פרמטרים

  • callback

    פונקציה

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

    (permissions: Permissions) => void

onRemoved

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

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

פרמטרים

  • callback

    פונקציה

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

    (permissions: Permissions) => void