תיאור
צריך להשתמש ב-API chrome.permissions
כדי לבקש הרשאות אופציונליות מוצהרות בזמן הריצה במקום בזמן ההתקנה, כדי שהמשתמשים יבינו למה ההרשאות נדרשות ולהעניק רק את ההרשאות הנדרשות.
מושגים ושימוש
קיימות אזהרות על הרשאות כדי לתאר את היכולות שניתנות על ידי ה-API, אבל יכול להיות שחלק מהאזהרות האלה לא יהיו ברורות. ה-Permissions 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
-
הרשאות
-