תיאור
אפשר להשתמש ב-API של chrome.permissions
כדי לבקש הרשאות אופציונליות מוצהרות בזמן הריצה במקום בזמן ההתקנה, כך שהמשתמשים יבינו למה ההרשאות נדרשות, ותעניקו רק את ההרשאות הדרושות.
מושגים ושימוש
קיימות אזהרות לגבי הרשאות כדי לתאר את היכולות שניתנות על ידי API, אבל יכול להיות שחלק מהאזהרות האלה לא יהיו ברורות מאליהן. Permissions API מאפשר למפתחים להסביר אזהרות לגבי הרשאות ולהציג תכונות חדשות בהדרגה, ומספקות למשתמשים היכרות עם התוסף ללא סיכון. כך, משתמשים יכולים לציין כמה גישה הם מוכנים להעניק ואילו תכונות הם רוצים לאפשר.
לדוגמה, הפונקציונליות העיקרית של תוסף ההרשאות האופציונליות מבטלת את דף הכרטיסייה החדשה. אחת התכונות מציגה את היעד היומי של המשתמש. לתכונה הזו נדרשת רק הרשאת אחסון, לא כוללת אזהרה. לתוסף יש תכונה נוספת, שמשתמשים יכולים להפעיל על ידי לחיצה על הלחצן הבא:
![לחצן תוסף שמאפשר להפעיל תכונות נוספות.](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/extension-button-enables-c53fe17733b8f.png?authuser=7&hl=he)
כדי להציג את האתרים המובילים של המשתמש נדרשת ההרשאה topSites, שכוללת את האזהרה הבאה.
![אזהרת הרחבה ב-topSites API.](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/extension-warning-topsit-8927d6b7cb863.png?authuser=7&hl=he)
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 מציג בקשה למשתמש אם הוספת ההרשאות גורמת להודעות אזהרה שונות מאלה המשתמש כבר ראה והתקבל. לדוגמה, הקוד הקודם עשוי להוביל להנחיה כמו הזה:
![דוגמה לבקשת אישור הרשאה.](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/perms-optional.png?authuser=7&hl=he)
שלב 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
-
permissions
-
onRemoved
chrome.permissions.onRemoved.addListener(
callback: function,
)
מופעל כשהגישה להרשאות הוסרה מהתוסף.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(permissions: Permissions) => void
-
permissions
-