הגדרת יעדים של שיתוף ישיר

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

‫ShortcutManagerCompat הוא AndroidX API שמספק קיצורי דרך לשיתוף, והוא תואם לאחור ל-API ‏ChooserTargetService שהוצא משימוש. זו הדרך המועדפת לפרסום של כפתורים לשיתוף מהיר ושל ChooserTargets. הוראות מפורטות זמינות במאמר שימוש ב-AndroidX כדי לספק גם קיצורי דרך לשיתוף וגם מטרות לבחירה בדף הזה.

פרסום יעדים לשיתוף ישיר

בשורה 'שיתוף ישיר' בקובץ לשיתוף מוצגים רק קיצורי דרך דינמיים שסופקו על ידי Sharing Shortcuts API. כדי לפרסם יעדים של שיתוף ישיר:

1. בקובץ משאבי ה-XML של האפליקציה, צריך להצהיר על רכיבי share-target.

   <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
   <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity">
       <data android:mimeType="text/plain" />
       <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" />
   </share-target>
   </shortcuts>
   

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

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

   Kotlin

   ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))

   Java

   List<ShortcutInfoCompat> shortcuts = new ArrayList<>();
   shortcuts.add(shortcut1);
   shortcuts.add(shortcut2);
   ...
   ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);

3. אם אתם מפתחים אפליקציית תקשורת, עליכם לדווח על השימוש בקיצור הדרך באמצעות pushDynamicShortcut באופן מיידי בכל פעם שהמשתמש מקבל או שולח הודעה לאיש קשר. מידע נוסף מופיע בקטע דיווח על שימוש בקיצורי דרך באפליקציות תקשורת בדף הזה. לדוגמה, אפשר לדווח על השימוש בהודעות שנשלחו על ידי המשתמש על ידי ציון של קשרי יכולות בקיצור הדרך באמצעות ShortcutInfoCompat.Builder#addCapabilityBinding עם היכולת actions.intent.SEND_MESSAGE.

   Kotlin

   val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
     ...
     .setShortLabel(firstName)
     .setLongLabel(fullName)
     .setCategories(matchedCategories)
     .setLongLived(true)
   .addCapabilityBinding("actions.intent.SEND_MESSAGE").build()
   ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

   Java

   ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
     ...
     .setShortLabel(firstName)
     .setLongLabel(fullName)
     .setCategories(matchedCategories)
     .setLongLived(true)
     .addCapabilityBinding("actions.intent.SEND_MESSAGE")
     .build();
   
   ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

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

   Kotlin

   val deleteShortcutId = "..."
   ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))

   Java

   String deleteShortcutId = "...";
   ShortcutManagerCompat.removeLongLivedShortcuts(
       myContext, Arrays.asList(deleteShortcutId));

שיפור הדירוגים של היעדים לשיתוף ישיר

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

• חשוב לוודא שכל ערכי shortcutIds הם ייחודיים ושלא נעשה בהם שימוש חוזר ליעדים שונים.
• כדי לוודא שהקיצור יפעל לאורך זמן, צריך להתקשר אל setLongLived(true).
• כדי לדווח על השימוש במקשי קיצור שקשורים לשיחות, צריך לפרסם מחדש את מקשי הקיצור המתאימים להודעות יוצאות ונכנסות דרך ShortcutManagerCompat.pushDynamicShortcut. פרטים נוספים זמינים בקטע דיווח על השימוש בקיצורי דרך באפליקציות תקשורת בדף הזה.
• אל תציעו יעדים לא רלוונטיים או לא עדכניים לשיתוף ישיר – לדוגמה, אנשי קשר שהמשתמש לא שלח להם הודעות ב-30 הימים האחרונים.
• באפליקציות ל-SMS, מומלץ להימנע מקיצורי דרך למספרים מקוצרים או לשיחות שזוהו כספאם פוטנציאלי. הסיכוי שהמשתמשים ישתפו את התמונות בשיחות האלה הוא נמוך מאוד.
• מתקשרים למספר setCategories() כדי לשייך את קיצור הדרך למאפייני mimeType המתאימים. לדוגמה, באפליקציית SMS, אם איש הקשר לא מוגדר ל-RCS או ל-MMS, לא תשייכו את קיצור הדרך המתאים לסוגי MIME שאינם טקסט, כמו image/* ו-video/*.
• בשיחה מסוימת, אחרי שמוצג קיצור דרך דינמי ומדווח על השימוש בו, אסור לשנות את מזהה קיצור הדרך. כך מובטח שנתוני השימוש יישמרו לצורך דירוג.

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

Sharing Shortcuts API

החל מ-Android 10 (רמת API‏ 29),‏ ShortcutInfo.Builder נוספו שיטות ושיפורים שמספקים מידע נוסף על יעד השיתוף:

setCategories()

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

setLongLived()

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

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

setShortLabel(), setLongLabel()

כשמפרסמים קיצור דרך לאדם פרטי, צריך לכלול את השם המלא שלו ב-setLongLabel() ואת השם המקוצר, כמו כינוי או שם פרטי, ב-setShortLabel().

דוגמה לפרסום קיצורי דרך לשיתוף ב-GitHub

הוספת תמונות של קיצורי דרך

כדי ליצור קיצור דרך לשיתוף, צריך להוסיף תמונה דרך setIcon().

קיצורי הדרך לשיתוף יכולים להופיע בכל מיני מקומות במערכת, ויכול להיות שהם יופיעו בצורה שונה. בנוסף, במכשירים מסוימים שפועלות בהם גרסאות Android 7,‏ 8 או 9 (רמות API‏ 25,‏ 26,‏ 27 ו-28) יכול להיות שיוצגו סמלים מסוג bitmap בלבד ללא רקע, מה שיפחית באופן משמעותי את הניגודיות. כדי לוודא שקיצור הדרך ייראה כמו שרוצים, צריך לספק מפת סיביות אדפטיבית באמצעות IconCompat.createWithAdaptiveBitmap().

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

אל תספקו תמונות עם מסכה בצורה ספציפית. לדוגמה, לפני Android 10 (רמת API‏ 29), היה נפוץ לספק אווטרים של משתמשים ל-ChooserTargets של שיתוף ישיר שהוסתרו בעיגול. הקובץ לשיתוף ב-Android ופלטפורמות אחרות של המערכת ב-Android 10 מעצבים ומשנים את העיצוב של תמונות קיצורי הדרך. השיטה המומלצת לספק קיצורי דרך לשיתוף היא באמצעות ShortcutManagerCompat. כך, אובייקטים של שיתוף ישיר ChooserTarget עם תאימות לאחור מעוצבים אוטומטית בצורה של עיגולים.

הצהרה על יעד שיתוף

צריך להצהיר על יעדי השיתוף בקובץ המשאבים של האפליקציה, בדומה להגדרות של קיצורי דרך סטטיים. מוסיפים הגדרות של יעד שיתוף בתוך רכיב השורש <shortcuts> בקובץ המשאבים, יחד עם הגדרות אחרות של קיצורי דרך סטטיים. כל רכיב <share-targets> מכיל מידע על סוג הנתונים המשותפים, על הקטגוריות התואמות ועל מחלקת היעד שתטפל בכוונת השיתוף. קוד ה-XML נראה בערך כך:

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity">
    <data android:mimeType="text/plain" />
    <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" />
  </share-target>
</shortcuts>

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

אם המשתמש יבחר בקיצור הדרך לשיתוף בקובץ לשיתוף ב-Android שתואם ליעד השיתוף לדוגמה שלמעלה, האפליקציה תקבל את כוונת השיתוף הבאה:

Action: Intent.ACTION_SEND
ComponentName: {com.example.android.sharingshortcuts /
                com.example.android.sharingshortcuts.SendMessageActivity}
Data: Uri to the shared content
EXTRA_SHORTCUT_ID: <ID of the selected shortcut>

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

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

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

קישורי השימוש והיכולות של קיצורי הדרך תואמים לאחור עד Android 5.0‏ (API 21).

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

הדיווח על השימוש בהודעות שנשלחו על ידי המשתמש דומה מבחינה פונקציונלית ללחיצה על לחצן השליחה אחרי יצירת הודעה.

כדי להפעיל דיווח על השימוש, צריך לציין את הקישור של היכולות בקיצור הדרך באמצעות ShortcutInfoCompat.Builder#addCapabilityBinding עם היכולת actions.intent.SEND_MESSAGE.

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
.addCapabilityBinding("actions.intent.SEND_MESSAGE").build()
ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

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

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", listOf("Audience")).build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", Arrays.asList("Audience"))
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

דיווח על שימוש בקיצורי דרך להודעות נכנסות

כדי להפעיל דיווח על שימוש כשהמשתמש מקבל הודעה כמו SMS, הודעת צ'אט, אימייל או התראות, צריך גם לציין את ההרשאות של הקיצור דרך ShortcutInfoCompat.Builder#addCapabilityBinding עם ההרשאה actions.intent.RECEIVE_MESSAGE.

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE").build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

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

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", listOf("Audience")).build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", Arrays.asList("Audience"))
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

שימוש ב-AndroidX כדי לספק גם כפתורים לשיתוף מהיר וגם יעדים לבחירה

כדי לעבוד עם ספריית התאימות של AndroidX, קובץ המניפסט של האפליקציה צריך להכיל את המטא-נתונים chooser-target-service ואת מסנני ה-intent שהוגדרו. אפשר לעיין בממשק ה-API הנוכחי של ChooserTargetService Direct Share.

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

בדוגמה הבאה, ההטמעה של ChooserTargetService היא androidx.core.content.pm.ChooserTargetServiceCompat, שכבר מוגדרת ב-AndroidX:

<activity
    android:name=".SendMessageActivity"
    android:label="@string/app_name"
    android:theme="@style/SharingShortcutsDialogTheme">
    <!-- This activity can respond to Intents of type SEND -->
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
    <!-- Only needed if you import the sharetarget AndroidX library that
         provides backwards compatibility with the old DirectShare API.
         The activity that receives the Sharing Shortcut intent needs to be
         taken into account with this chooser target provider. -->
    <meta-data
        android:name="android.service.chooser.chooser_target_service"
        android:value="androidx.sharetarget.ChooserTargetServiceCompat" />
</activity>

שאלות נפוצות בנושא קיצורי דרך לשיתוף

איך נשמרים נתוני השימוש בקיצורי הדרך, והאם הם יוצאים מהמכשיר?

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

מה ההיסטוריה של שיתוף ישיר?

השקנו את התכונה 'שיתוף ישיר' ב-Android 6.0 (רמת API ‏23) כדי לאפשר לאפליקציות לספק אובייקטים ChooserTarget באמצעות ChooserTargetService. התוצאות אוחזרו באופן ריאקטיבי לפי דרישה, ולכן זמן הטעינה של היעדים היה ארוך.

ב-Android 10 (רמת API‏ 29), החלפנו את ממשקי ה-API של ChooserTargetService Direct Share ב-Sharing Shortcuts API החדש. במקום לאחזר תוצאות באופן ריאקטיבי לפי דרישה, ה-API של קיצורי דרך לשיתוף מאפשר לאפליקציות לפרסם מראש יעדים של שיתוף ישיר. השינוי הזה האיץ באופן משמעותי את תהליך אחזור היעדים של השיתוף הישיר בזמן הכנת גיליון השיתוף. המנגנון של ChooserTargetService שיתוף ישיר ימשיך לפעול, אבל המערכת מדרגת יעדים שסופקו בדרך הזו בדירוג נמוך יותר מכל יעד שמשתמש ב-API של מקשי הקיצור לשיתוף.

ב-Android 11 (רמת API‏ 30) הוצא משימוש שירות ChooserTargetService, ו-Sharing Shortcuts API היא הדרך היחידה לספק יעדים לשיתוף ישיר.

מה ההבדל בין קיצורי דרך שפורסמו ליעדי שיתוף לבין קיצורי דרך במרכז האפליקציות (השימוש הרגיל בקיצורי דרך כשלוחצים לחיצה ארוכה על סמלי אפליקציות במרכז האפליקציות)?

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

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

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