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

איור 1: השורה 'שיתוף ישיר' בקובץ לשיתוף, כפי שמסומן ב-1

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

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

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

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

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

1. מצהירים על רכיבי share-target בקובץ משאבי ה-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>
   

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

setCategories()

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

setLongLived()

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

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

setShortLabel(), setLongLabel()

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

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

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

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

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

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

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

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

צריך להצהיר על יעדי השיתוף בקובץ המשאבים של האפליקציה, בדומה להגדרות של קיצורי דרך סטטיים. מוסיפים הגדרות של יעד שיתוף בתוך רכיב הבסיס <shortcuts> בקובץ המשאבים, יחד עם הגדרות אחרות של קיצורי דרך סטטיים. כל רכיב <share-targets> מכיל מידע על סוג הנתונים המשותפים, על הקטגוריות התואמות ועל מחלקת היעד שתטפל בכוונת (Intent) השיתוף. קוד ה-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>

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

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

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

אם אתם מפתחים אפליקציית תקשורת, אתם יכולים לשפר את הדירוג שלה בקובץ לשיתוף ב-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 כדי לספק גם קיצורי דרך לשיתוף וגם יעדים לבחירה

כדי לעבוד עם ספריית התאימות של AndroidX, קובץ המניפסט של האפליקציה צריך להכיל את המטא-נתונים chooser-target-service ואת מסנני ה-intent שהוגדרו. אפשר לעיין ב-Direct Share 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>

שאלות נפוצות בנושא כפתורים לשיתוף מהיר

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

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

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

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

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

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

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

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

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

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