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

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

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

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

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

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

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

1. בקובץ AndroidManifest.xml של האפליקציה, מחפשים את הפעילות שמסנני ה-Intent שלה מוגדרים לפעולה 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>, צריך לכלול מידע על קיצור דרך סטטי, כולל הסמל שלו, תוויות התיאור וה-intent שהוא מפעיל באפליקציה:

   <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>
   shortcuts.xml

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

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

android:shortcutId

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

android:shortcutShortLabel

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

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

android:shortcutLongLabel

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

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

android:shortcutDisabledMessage

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

android:enabled

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

android:icon

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

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

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

intent

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

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

categories

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

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

capability-binding

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

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

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

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

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

באמצעות ה-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)
ShortcutsSnippets.kt

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

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

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

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

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

כדי להשתמש בספרייה הזו באפליקציה, צריך להוסיף יחסי תלות של ספריית השילוב של קיצורי הדרך של Google ו-ShortcutManagerCompat לקובץ app/build.gradle או app/build.gradle.kts:

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

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

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

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

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

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

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

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

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

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

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

if (ShortcutManagerCompat.isRequestPinShortcutSupported(context)) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfoCompat.Builder(context, "my-shortcut")
        .setShortLabel("Website")
        .setIntent(
            Intent(
                Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")
            )
        )
        .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 =
        ShortcutManagerCompat.createShortcutResultIntent(context, 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 */ PendingIntent.FLAG_IMMUTABLE
    )

    ShortcutManagerCompat.requestPinShortcut(
        context,
        pinShortcutInfo,
        successCallback.intentSender
    )
}
ShortcutsSnippets.kt

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

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

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

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

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

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

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

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