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

כדי להקל על משתמשים באפליקציות אחרות לשתף כתובות 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) יכול להיות שיוצגו סמלים של מפת סיביות בלבד ללא רקע, מה שיפחית באופן משמעותי את הניגודיות. כדי לוודא שקיצור הדרך ייראה כמו שרוצים, צריך לספק מפת סיביות דינמית באמצעות IconCompat.createWithAdaptiveBitmap().

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

אל תספקו תמונות עם מסכה בצורה ספציפית. לדוגמה, לפני Android 10 (רמת API‏ 29), היה נהוג לספק אווטרים של משתמשים לשיתוף ישיר ChooserTargetשהוסתרו בעיגול. ב-Android 10, גיליון השיתוף ב-Android ופלטפורמות אחרות במערכת מעצבים את התמונות של קיצורי הדרך ומשנים את העיצוב שלהן. השיטה המומלצת לספק קיצורי דרך לשיתוף היא באמצעות 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 כדי לספק גם כפתורים לשיתוף מהיר וגם ChooserTargets

כדי לעבוד עם ספריית התאימות של 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 החדש. במקום לאחזר תוצאות באופן ריאקטיבי לפי דרישה, Sharing Shortcuts API מאפשר לאפליקציות לפרסם מראש יעדים של שיתוף ישיר. השינוי הזה האיץ באופן משמעותי את התהליך של אחזור יעדים של שיתוף ישיר בזמן הכנת גיליון השיתוף. המנגנון של ChooserTargetService שיתוף ישיר ימשיך לפעול, אבל המערכת מדרגת יעדים שסופקו בדרך הזו בדירוג נמוך יותר מכל יעד שמשתמש ב-API של מקשי הקיצור לשיתוף.

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

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

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

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

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