יצירת קיצורי דרך

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

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

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

יצירת קיצורי דרך סטטיים

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

כדי ליצור קיצור דרך סטטי:

1. בקובץ AndroidManifest.xml של האפליקציה, מחפשים את הפעילות שמסנני הכוונות שלה מוגדרים לפעולה android.intent.action.MAIN ולסיווג android.intent.category.LAUNCHER.

2. מוסיפים לרכיב הפעילות הזה את הרכיב <meta-data> שמפנה לקובץ המשאבים שבו מוגדרים קיצורי הדרך של האפליקציה:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
             package="com.example.myapplication">
     <application ... >
       <activity android:name="Main">
         <intent-filter>
           <action android:name="android.intent.action.MAIN" />
           <category android:name="android.intent.category.LAUNCHER" />
         </intent-filter>
         <meta-data android:name="android.app.shortcuts"
                    android:resource="@xml/shortcuts" />
       </activity>
     </application>
   </manifest>
   

3. יוצרים קובץ משאבים חדש בשם res/xml/shortcuts.xml.

4. בקובץ המשאבים החדש, מוסיפים רכיב בסיס <shortcuts> שמכיל רשימה של רכיבי <shortcut>. בכל רכיב <shortcut>, צריך לכלול מידע על קיצור דרך סטטי, כולל הסמל, תוויות התיאור והכוונות שהוא מפעיל באפליקציה:

   <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
     <shortcut
       android:shortcutId="compose"
       android:enabled="true"
       android:icon="@drawable/compose_icon"
       android:shortcutShortLabel="@string/compose_shortcut_short_label1"
       android:shortcutLongLabel="@string/compose_shortcut_long_label1"
       android:shortcutDisabledMessage="@string/compose_disabled_message1">
       <intent
         android:action="android.intent.action.VIEW"
         android:targetPackage="com.example.myapplication"
         android:targetClass="com.example.myapplication.Main" />
       <!-- If your shortcut is associated with multiple intents, include them
            here. The last intent in the list determines what the user sees when
            they launch this shortcut. -->
       <categories android:name="android.shortcut.conversation" />
       <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
     </shortcut>
     <!-- Specify more shortcuts here. -->
   </shortcuts>
   

התאמה אישית של ערכי מאפיינים

הרשימה הבאה כוללת תיאורים של המאפיינים השונים בקיצור דרך סטטי. צריך לספק ערך למאפיינים android:shortcutId ו-android:shortcutShortLabel. כל שאר הערכים הם אופציונליים.

android:shortcutId

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

android:shortcutShortLabel

ביטוי תמציתי שמתאר את מטרת קיצור הדרך. אם אפשר, כדאי להגביל את התיאור הקצר הזה ל-10 תווים.

מידע נוסף זמין במאמר setShortLabel().

android:shortcutLongLabel

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

מידע נוסף זמין במאמר setLongLabel().

android:shortcutDisabledMessage

ההודעה שמופיעה ב-Launcher נתמך כשהמשתמש מנסה להפעיל קיצור דרך מושבת. בהודעה צריך להסביר למשתמש למה קיצור הדרך מושבת. לערך של המאפיין הזה אין השפעה אם android:enabled הוא true.

android:enabled

קובעת אם המשתמש יכול ליצור אינטראקציה עם קיצור הדרך ממפעיל נתמך. ערך ברירת המחדל של android:enabled הוא true. אם בוחרים באפשרות false, צריך להגדיר android:shortcutDisabledMessage שמסביר למה משביתים את קיצור הדרך. אם לדעתכם אין צורך להציג הודעה כזו, צריך להסיר את קיצור הדרך מקובץ ה-XML.

android:icon

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

הגדרת רכיבים פנימיים

קובץ ה-XML שמפרט את קיצורי הדרך הסטטיים של האפליקציה תומך באלמנטים הבאים בתוך כל אלמנט <shortcut>. חובה לכלול intent אלמנט פנימי לכל קיצור דרך סטטי שמגדירים.

intent

הפעולה שהמערכת מפעילה כשהמשתמש בוחר את קיצור הדרך. בכוונת המשתמש הזו צריך לספק ערך למאפיין android:action.

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

categories

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

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

capability-binding

הצהרה על היכולת שמקושרת לקיצור הדרך.

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

יצירת קיצורי דרך דינמיים

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

ספריית Jetpack‏ ShortcutManagerCompat היא כלי עזר ל-API‏ ShortcutManager, שמאפשר לכם לנהל קיצורי דרך דינמיים באפליקציה. השימוש בספרייה ShortcutManagerCompat מצמצם את כמות הקוד שחוזר על עצמו (boilerplate) ועוזר לוודא שקיצורי הדרך פועלים באופן עקבי בגרסאות שונות של Android. הספרייה הזו נדרשת גם כדי לשלוח קיצורי דרך דינמיים, כך שהם יעמדו בדרישות להצגה בפלטפורמות של Google – כמו Assistant – באמצעות Google Shortcuts Integration Library.

ממשק ה-API‏ ShortcutManagerCompat מאפשר לאפליקציה לבצע את הפעולות הבאות באמצעות קיצורי דרך דינמיים:

• דחיפה ועדכון: משתמשים ב-pushDynamicShortcut() כדי לפרסם ולעדכן את קיצורי הדרך הדינמיים. אם כבר יש קיצורי דרך דינמיים או מוצמדים עם אותו מזהה, כל קיצור דרך שניתן לשינוי מתעדכן.
• הסרה: הסרת קבוצה של קיצורי דרך דינמיים באמצעות removeDynamicShortcuts(). מסירים את כל קיצורי הדרך הדינמיים באמצעות removeAllDynamicShortcuts().

מידע נוסף על ביצוע פעולות בקיצורי דרך זמין במאמר ניהול קיצורי דרך ובמאמר ShortcutManagerCompat.

דוגמה ליצירת קיצור דרך דינמי ושיוך שלו לאפליקציה:

val shortcut = ShortcutInfoCompat.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

הוספת ספריית השילוב של קיצורי הדרך של Google

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

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

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

ספריית השילוב של קיצורי הדרך של Google לא מציעה פונקציונליות שאפשר לפנות אליה ישירות. הוספת הספרייה הזו לאפליקציה מאפשרת לפלטפורמות של Google לקבל את קיצורי הדרך שהאפליקציה שולחת באמצעות ShortcutManagerCompat.

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

1. מעדכנים את קובץ gradle.properties כדי לתמוך בספריות AndroidX:

   android.useAndroidX=true
   # Automatically convert third-party libraries to use AndroidX
   android.enableJetifier=true
   

2. ב-app/build.gradle, מוסיפים תלויות לספריית Google Shortcuts Integration ול-ShortcutManagerCompat:

   dependencies {
     implementation "androidx.core:core:1.6.0"
     implementation 'androidx.core:core-google-shortcuts:1.0.0'
     ...
   }
   

אחרי שמוסיפים את התלויות בספרייה לפרויקט Android, האפליקציה יכולה להשתמש בשיטה pushDynamicShortcut() מ-ShortcutManagerCompat כדי לדחוף קיצורי דרך דינמיים שעומדים בדרישות להצגה במפעיל האפליקציות ובפלטפורמות של Google שמשתתפות בתוכנית.

יצירת קיצורי דרך מוצמדים

ב-Android מגרסה 8.0 (רמת API‏ 26) ואילך, אפשר ליצור קיצורי דרך מוצמדים. בשונה מקיצורי דרך סטטיים ודינמיים, קיצורי דרך מוצמדים מופיעים בתוכנות הפעלה נתמכות כסמלים נפרדים. איור 1 מציג את ההבדל בין שני סוגי קיצורי הדרך האלה.

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

1. משתמשים ב-isRequestPinShortcutSupported() כדי לוודא שמשגר האפליקציות שמוגדר כברירת מחדל במכשיר תומך בהצמדת קיצורי דרך בתוך האפליקציה.

2. אפשר ליצור אובייקט ShortcutInfo באחת משתי דרכים, בהתאם לשאלה אם קיצור הדרך קיים:

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

3. כדי להצמיד את קיצור הדרך למרכז האפליקציות של המכשיר, צריך לשלוח קריאה אל requestPinShortcut(). במהלך התהליך הזה, אפשר להעביר אובייקט PendingIntent, שמודיע לאפליקציה רק כשהקיצור מוצמד בהצלחה.

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

בקטע הקוד הבא אפשר לראות איך יוצרים קיצור דרך מוצמד.

val shortcutManager = getSystemService<ShortcutManager>()

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

יצירת פעילות של קיצור דרך בהתאמה אישית

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

בקובץ המניפסט של האפליקציה, מוסיפים את ACTION_CREATE_SHORTCUT לרכיב <intent-filter> של הפעילות. ההצהרה הזו מגדירה את ההתנהגות הבאה כשמשתמש מנסה ליצור קיצור דרך:

1. המערכת מפעילה את הפעילות המיוחדת של האפליקציה.
2. המשתמש מגדיר את האפשרויות לקיצור הדרך.
3. המשתמש לוחץ על לחצן האישור.
4. האפליקציה יוצרת את קיצור הדרך באמצעות ה-method‏ createShortcutResultIntent(). השיטה הזו מחזירה Intent, שהאפליקציה מעבירה חזרה לפעילות שהופעלה קודם באמצעות setResult().
5. האפליקציה שלך קוראת ל-finish() בפעילות שמשמשת ליצירת קיצור הדרך המותאם אישית.

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

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

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

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