chrome.permissions

תיאור

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

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

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

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

לחצן תוסף שמאפשר להפעיל תכונות נוספות.
לחצן תוסף שמאפשר להפעיל תכונות נוספות.

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

אזהרת הרחבה ב-topSites 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" כל עוד יש לו scheme.

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

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

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

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

שיטות

contains()

הבטחה 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

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

פרמטרים

  • permissions

    הרשאות

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    (result: boolean) => void

    • תוצאה

      בוליאני

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

החזרות

  • Promise<boolean>

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

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

getAll()

הבטחה 
chrome.permissions.getAll(
  callback?: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    (permissions: Permissions) => void

    • permissions

      הרשאות

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

החזרות

  • Promise<Permissions>

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

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

remove()

הבטחה 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

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

פרמטרים

  • permissions

    הרשאות

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    (removed: boolean) => void

    • הוסר

      בוליאני

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

החזרות

  • Promise<boolean>

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

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

request()

הבטחה 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

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

פרמטרים

  • permissions

    הרשאות

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    (granted: boolean) => void

    • הוענקה

      בוליאני

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

החזרות

  • Promise<boolean>

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

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

אירועים

onAdded

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

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

    (permissions: Permissions) => void

onRemoved

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

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

    (permissions: Permissions) => void