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

איור 1: שורה של שיתוף ישיר בקובץ לשיתוף, כפי שמוצג ב-1

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

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

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

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

בשורה 'שיתוף ישיר' בחלונית השיתוף מוצגים רק מקשי קיצור דינמיים שסופקו על ידי ה-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()

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

setLongLived()

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

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

setShortLabel(), setLongLabel()

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

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

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

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

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

חשוב לוודא שהקובצי ה-bitmap המותאמים עומדים באותן הנחיות ובאותן מידות שהוגדרו לסמלים מותאמים. הדרך הנפוצה ביותר לעשות זאת היא לשנות את הגודל של קובץ ה-bitmap הריבועי הרצוי ל-72x72dp ולמקם אותו במרכז של לוח שקוף בגודל 108x108dp. אם הסמל כולל אזורים שקופים, צריך לכלול צבע רקע. אחרת, האזורים השקופים יופיעו בשחור.

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

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);

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

Kotlin

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)

Java

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.

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_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.RECEIVE_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

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

Kotlin

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)

Java

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

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

בדוגמה הבאה, ההטמעה של 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>

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

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

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

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

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

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

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

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

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

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

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