chrome.permissions

תיאור

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

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

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

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

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

כדי להציג את האתרים המובילים של המשתמש, צריך את ההרשאה 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"	ה-API chrome.debugger משמש ככלי להעברה חלופית של פרוטוקול ניפוי הבאגים מרחוק של Chrome.
"declarativeNetRequest"	הרשאה שמעניקה לתוסף גישה לממשק ה-API chrome.declarativeNetRequest.
"devtools"	מאפשר לתוסף להרחיב את הפונקציונליות של Chrome DevTools.
"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 בלבד. שינוי הטפט ב-ChromeOS באמצעות ה-API chrome.wallpaper.

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

שלב 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()

Promise PendingMV3+

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

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

פרמטרים

• בקשה

  אובייקט

  • documentId

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

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

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

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

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

  • tabId

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

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

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

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

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

  () => void

החזרות

• Promise<void>

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

contains()

Promise

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

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

פרמטרים

• permissions

  הרשאות

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

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

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

  (result: boolean) => void

  • תוצאה

    בוליאני

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

החזרות

• Promise<boolean>

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

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

getAll()

Promise

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

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

פרמטרים

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

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

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

  (permissions: Permissions) => void

  • permissions

    הרשאות

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

החזרות

• Promise<Permissions>

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

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

remove()

Promise

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

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

פרמטרים

• permissions

  הרשאות

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

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

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

  (removed: boolean) => void

  • הוסר

    בוליאני

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

החזרות

• Promise<boolean>

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

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

removeHostAccessRequest()

Promise PendingMV3+

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

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

פרמטרים

• בקשה

  אובייקט

  • documentId

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

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

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

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

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

  • tabId

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

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

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

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

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

  () => void

החזרות

• Promise<void>

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

request()

Promise

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

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

פרמטרים

• permissions

  הרשאות

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

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

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

  (granted: boolean) => void

  • GRANTED

    בוליאני

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

החזרות

• Promise<boolean>

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

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

אירועים

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

    הרשאות