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

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

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

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

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

setLongLived()

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

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

setShortLabel(), setLongLabel()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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