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

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

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

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

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

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

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

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

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

הקודם
קבלת נתונים פשוטים מאפליקציות אחרות