browser.permissions

תיאור

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

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

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

שלב 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).
  }
});

chrome.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

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

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

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

chrome.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

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

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

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