ניהול קיצורי הדרך

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

בדף הזה מתוארות הדרכים האלה ועוד כמה דרכים נפוצות לניהול קיצורי הדרך.

התנהגות של קיצור דרך

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

הרשאות הגישה של קיצור הדרך

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

הכיתה LauncherApps מספקת ממשקי API לאפליקציות של מרכז האפליקציות כדי לגשת לקיצורי דרך.

קיצורי הדרך המוצמדים מופיעים במרכז האפליקציות עצמו, ולכן הם תמיד גלויים. קיצור דרך מוצמד יוסר ממרכז האפליקציות רק במקרים הבאים:

• המשתמש מסיר אותו.
• האפליקציה שמשויכת לקיצור הדרך הוסרה.
• המשתמש מוחק את נתוני האפליקציה דרך הגדרות > אפליקציות והתראות, בוחר את האפליקציה ולוחץ על אחסון > פינוי נפח אחסון.

יעדי שיתוף הם קבוצת משנה של קיצורי דרך דינמיים שמופיעים בשורת השיתוף הישיר בגיליון השיתוף של Android.

סדר התצוגה של קיצורי הדרך

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

1. קיצורי דרך סטטיים: קיצורי דרך שה-method‏ isDeclaredInManifest() שלהם מחזירה את הערך true.
2. קיצורי דרך דינמיים: קיצורי דרך שה-method‏ ShortcutInfo.isDynamic() שלהם מחזירה את הערך true.

בכל סוג של קיצור דרך – סטטי ודינמי – קיצורי הדרך ממוינים בסדר עולה של דירוג לפי ShortcutInfo.getRank. ‫Google Assistant גם מתייחסת לדירוג של קיצור הדרך כשהיא קובעת אילו קיצורי דרך לפי הקשר להציג למשתמשים.

הדירוגים הם מספרים שלמים חיוביים עוקבים. קיצורי דרך סטטיים מדורגים מהראשון לאחרון לפי הסדר שבו הם מופיעים בקובץ shortcuts.xml. בקיצורי דרך דינמיים, אפשר לעדכן את הדירוגים של קיצורי דרך קיימים כשמפעילים את updateShortcuts(Context, List), addDynamicShortcuts(Context, List), pushDynamicShortcut(Context, ShortcutInfoCompat) או setDynamicShortcuts(Context, List).

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

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

ניהול של כמה כוונות ופעילויות

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

התחלת פעילות אחת מתוך פעילות אחרת

לקיצורי דרך סטטיים לא יכולים להיות דגלי Intent בהתאמה אישית. ה-Intent הראשון של קיצור דרך סטטי תמיד מוגדר עם Intent.FLAG_ACTIVITY_NEW_TASK ו-Intent.FLAG_ACTIVITY_CLEAR_TASK. כלומר, כשהאפליקציה פועלת, כל הפעילויות הקיימות באפליקציה נהרסות כשמפעילים קיצור דרך סטטי. אם אתם לא רוצים שזה יקרה, אתם יכולים להשתמש ב-trampoline activity – פעילות בלתי נראית שמתחילה פעילות אחרת – על ידי קריאה ל-finish בתוך בלוק הפעלה או onCreate לפני שמוגדר תוכן של Compose:

1. ב-AndroidManifest.xml file, כוללים את הקצאת המאפיין android:taskAffinity="" בפעילות הטרמפולינה.

2. בקובץ המשאבים של קיצורי הדרך, מפנים לפעילות הטרמפולינה ב-Intent בתוך קיצור הדרך הסטטי.

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

הגדרת דגלי Intent

אפשר לפרסם קיצורי דרך דינמיים עם כל קבוצה של דגלי Intent. עדיף לציין את השילוב של Intent.FLAG_ACTIVITY_SINGLE_TOP ו-Intent.FLAG_ACTIVITY_CLEAR_TOP ב-intent של קיצור הדרך. כך, אם ComponentActivity כבר פעיל, הוא מועבר לחזית ונעשה בו שימוש חוזר בלי להרוס אותו, מה שמאפשר לארכיטקטורת הפעילות היחידה לטפל באירוע של קיצור הדרך בצורה חלקה דרך onNewIntent().

מידע נוסף על משימות ודגלי Intent זמין במאמר משימות ומקבץ פעילויות קודמות (back stack).

עדכון קיצורי הדרך

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

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

בדוגמה הבאה, נניח שהערך שמוחזר על ידי getMaxShortcutCountPerActivity הוא 4:

1. אפליקציית צ'אט מפרסמת ארבעה קיצורי דרך דינמיים, שמייצגים את ארבע השיחות האחרונות: c1,‏ c2,‏ c3 ו-c4.
2. המשתמש מצמיד את כל ארבעת מקשי הקיצור.
3. בהמשך, המשתמש מתחיל שלוש שיחות נוספות: c5,‏ c6 ו-c7. האפליקציה של בעל התוכן הדיגיטלי מפרסמת מחדש את קיצורי הדרך הדינמיים שלה. רשימת קיצורי הדרך הדינמיים החדשה היא: c4,‏ c5,‏ c6 ו-c7.

האפליקציה צריכה להסיר את c1,‏ c2 ו-c3, כי היא לא יכולה להציג יותר מארבעה קיצורי דרך דינמיים. עם זאת, c1,‏ c2 ו-c3 עדיין מוצמדים כקיצורי דרך שהמשתמש יכול לגשת אליהם ולהפעיל אותם.

המשתמש יכול לגשת ל-7 קיצורי דרך שמקשרים לפעילויות באפליקציה של בעל התוכן הדיגיטלי. הסיבה לכך היא שהמספר הכולל כולל את המספר המקסימלי של קיצורי דרך ואת 3 קיצורי הדרך המוצמדים.

1. האפליקציה יכולה להשתמש ב-updateShortcuts(Context, List) כדי לעדכן כל אחד משבעת קיצורי הדרך הקיימים. לדוגמה, יכול להיות שתעדכנו את קבוצת קיצורי הדרך הזו כשהסמלים של המשתתפים בצ'אט ישתנו.
2. אתם יכולים להשתמש ב-addDynamicShortcuts(Context, List) וב-setDynamicShortcuts(Context, List) כדי לעדכן קיצורי דרך קיימים עם אותם מזהים. עם זאת, אי אפשר להשתמש בהן כדי לעדכן קיצורי דרך מוצמדים לא דינמיים, כי שתי השיטות האלה מנסות להמיר את רשימות קיצורי הדרך הנתונות לקיצורי דרך דינמיים.

אין הגבלה על מספר קיצורי הדרך שאפשר להעביר להצגה באפליקציות עזרה כמו Google Assistant. משתמשים ב-method‏ pushDynamicShortcut של ספריית Jetpack‏ ShortcutManagerCompat כדי ליצור ולעדכן קיצורי דרך לשימוש באפליקציות של Assistant. בנוסף, צריך להוסיף לאפליקציה את ספריית Google Shortcuts Integration כדי שקישורים דינמיים יוכלו להופיע ב-Google Assistant.

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

טיפול בשינויים בלוקאל של המערכת

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

מעקב אחרי השימוש בקיצורי דרך

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

• המשתמש בוחר את קיצור הדרך עם המזהה שצוין.
• באפליקציה, המשתמש משלים באופן ידני את הפעולה שתואמת לאותו קיצור דרך.

האפליקציה עוקבת אחרי השימוש בקיצורי דרך דינמיים על ידי קריאה ל-method‏ pushDynamicShortcut והעברת המזהה של קיצור הדרך כשהאירוע הרלוונטי מתרחש. כשמדווחים על שימוש בקיצורי דרך דינמיים בשיטה הזו, אפליקציות עזרה כמו Google Assistant יכולות להציע למשתמשים קיצורי דרך רלוונטיים. ה-method‏ pushDynamicShortcut מדווחת על השימוש כשקוראים לה, לכן אל תקראו ל-method‏ reportShortcutUsed לאותם קיצורי דרך.

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

השבתת קיצורי הדרך

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

הגבלת קצב של יצירת בקשות

כשמשתמשים ב-setDynamicShortcuts, addDynamicShortcuts או ב-updateShortcuts, יכול להיות שאפשר יהיה להפעיל את השיטות האלה רק מספר מסוים של פעמים באפליקציה שפועלת ברקע – אפליקציה בלי פעילויות או שירותים בחזית. המגבלה על מספר הפעמים הספציפי שבו אפשר להפעיל את השיטות האלה נקראת הגבלת קצב של יצירת בקשות. התכונה הזו מונעת מ-ShortcutManagerCompat לצרוך יותר מדי משאבים במכשיר.

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

• אפליקציה עוברת לחזית.
• הלוקאל של המערכת משתנה.
• המשתמש מבצע את הפעולה תשובה מוטבעת בהתראה.

אם נתקלתם בהגבלת קצב של יצירת בקשות במהלך הפיתוח או הבדיקה, אתם יכולים לבחור באפשרות אפשרויות למפתחים > איפוס הגבלת הקצב של יצירת הבקשות ב-ShortcutManager בהגדרות המכשיר, או להזין את הפקודה הבאה ב-adb:

adb shell cmd shortcut reset-throttling [ --user your-user-id ]

גיבוי ושחזור

כדי לאפשר למשתמשים לבצע פעולות גיבוי ושחזור באפליקציה כשהם מחליפים מכשירים, צריך לכלול את הקצאת המאפיין android:allowBackup="true" בקובץ המניפסט של האפליקציה. אם אתם תומכים בגיבוי ובשחזור, חשוב לזכור את הנקודות הבאות לגבי קיצורי דרך לאפליקציות:

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

בקטע הקוד הבא מוצגת הדרך הטובה ביותר לשחזר את קיצורי הדרך הדינמיים של האפליקציה, ואיך לבדוק אם קיצורי הדרך המוצמדים של האפליקציה נשמרו:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getShortcuts(this, ShortcutManagerCompat.FLAG_MATCH_PINNED).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}
ShortcutsSnippets.kt