chrome.permissions

תיאור

סקירה כללית

קיימות אזהרות לגבי הרשאות כדי לתאר את היכולות שניתנות על ידי API, אבל יכול להיות שחלק מהאזהרות האלה לא יהיו ברורות מאליהן. Permissions 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, כל עוד יש לו ערך תואם. scheme.

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

את רוב ההרשאות של תוספים ל-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.
  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).
  }
});

chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

chrome.permissions.getAll(
  callback?: function,
)

chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

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

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