דף זה תורגם על ידי Cloud Translation API.

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", כל עוד יש לו סכמה תואמת.

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

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

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

string[] אופציונלי

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

שיטות

contains()

הבטחה

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

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

פרמטרים

הרשאות

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

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

הפרמטר callback נראה כך:
```
(result: boolean)=>void
```
- תוצאה אחת
  
  boolean
  
  True אם לתוסף יש את ההרשאות שצוינו. אם מקור מוגדר גם כהרשאה אופציונלית וגם כדפוס התאמה של סקריפט תוכן, הפונקציה הזו תחזיר false אלא אם שתי ההרשאות ייתנו.

החזרות

Promise<boolean>

Chrome 96 ומעלה

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

getAll()

הבטחה

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

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

פרמטרים

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

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

הפרמטר callback נראה כך:
```
(permissions: Permissions)=>void
```
- הרשאות
  
  הרשאות
  
  ההרשאות הפעילות של התוסף. חשוב לשים לב שהנכס origins יכיל מקורות מורשים שצוינו במפתחות permissions ו-optional_permissions במניפסט ובמקורות המשויכים לסקריפטים של תוכן.

החזרות

מבטיחים<הרשאות>

Chrome 96 ומעלה

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

remove()

הבטחה

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

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

פרמטרים

הרשאות

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

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

הפרמטר callback נראה כך:
```
(removed: boolean)=>void
```
- הוסר
  
  boolean
  
  True אם ההרשאות הוסרו.

החזרות

Promise<boolean>

Chrome 96 ומעלה

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

request()

הבטחה

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

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

פרמטרים

הרשאות

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

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

הפרמטר callback נראה כך:
```
(granted: boolean)=>void
```
- הוענקה
  
  boolean
  
  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
```
- הרשאות
  
  הרשאות