chrome.permissions

תיאור

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

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

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

כדי להציג את האתרים המובילים של המשתמש, צריך את ההרשאה 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.
  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.addHostAccessRequest(
  request: object,
  callback?: function,
)

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

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

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

chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

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

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

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