chrome.permissions

תיאור

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

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

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

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

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

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

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

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

שלב 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"	‫chrome.debugger API משמש כהעברה חלופית לפרוטוקול של ניפוי באגים מרחוק ב-Chrome.
"declarativeNetRequest"	מעניקה לתוסף גישה ל-API ‏ chrome.declarativeNetRequest.
"devtools"	מאפשר לתוסף להרחיב את הפונקציונליות של כלי הפיתוח של Chrome.
"geolocation"	מאפשרת לתוסף להשתמש ב-API של מיקום גיאוגרפי ב-HTML5.
"mdns"	ההרשאה מעניקה לתוסף גישה לממשק ה-API של 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[] אופציונלי

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

Methods

addHostAccessRequest()

‫Chrome 133 ואילך MV3 ואילך

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

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

פרמטרים

• בקשה

  אובייקט

  • documentId

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

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

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

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

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

  • tabId

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

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

החזרות

• Promise<void>

contains()

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

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

פרמטרים

• permissions

  הרשאות

החזרות

• Promise<boolean>

  ‫Chrome 96 ואילך

getAll()

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

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

החזרות

• Promise<Permissions>

  ‫Chrome 96 ואילך

remove()

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

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

פרמטרים

• permissions

  הרשאות

החזרות

• Promise<boolean>

  ‫Chrome 96 ואילך

removeHostAccessRequest()

‫Chrome 133 ואילך MV3 ואילך

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

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

פרמטרים

• בקשה

  אובייקט

  • documentId

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

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

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

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

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

  • tabId

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

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

החזרות

• Promise<void>

request()

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

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

פרמטרים

• permissions

  הרשאות

החזרות

• Promise<boolean>

  ‫Chrome 96 ואילך

אירועים

onAdded

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

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

פרמטרים

• callback

  פונקציה

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

  (permissions: Permissions) => void

  • permissions

    הרשאות

onRemoved

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

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

פרמטרים

• callback

  פונקציה

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

  (permissions: Permissions) => void

  • permissions

    הרשאות