Doğrudan paylaşım hedefleri sağlama

Şekil 1: Sharesheet'teki doğrudan paylaşım satırı (1 ile gösterilmiştir)

Diğer uygulamaların kullanıcılarının URL'leri, resimleri veya diğer veri türlerini uygulamanızla paylaşmasını kolaylaştırmak ve hızlandırmak için doğrudan paylaşım hedeflerini kullanın. Doğrudan paylaşım, mesajlaşma ve sosyal uygulamalardaki kişileri doğrudan Android paylaşım sayfasında göstererek çalışır. Böylece kullanıcıların önce uygulamayı seçip ardından kişiyi araması gerekmez.

ShortcutManagerCompat AndroidX API'sidir. Paylaşım kısayolları sağlar ve kullanımdan kaldırılan ChooserTargetService API'siyle geriye dönük uyumludur. Hem paylaşım kısayollarını hem de ChooserTargets yayınlamak için tercih edilen yöntem budur. Talimatlar için bu sayfadaki Hem paylaşım kısayolları hem de ChooserTarget'lar sağlamak için AndroidX'i kullanma bölümüne bakın.

Doğrudan paylaşım hedeflerini yayınlama

Paylaşım sayfası doğrudan paylaşım satırında yalnızca Paylaşım Kısayolları API'si tarafından sağlanan dinamik kısayollar gösterilir. Doğrudan Paylaşım hedeflerini yayınlamak için aşağıdaki adımları tamamlayın.

  1. Uygulamanızın XML kaynak dosyasında share-target öğelerini bildirin.

    <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. Uygulamanız başlatıldığında, dinamik kısayolları önem sırasına göre sıralamak için setDynamicShortcuts kullanın.

    Daha düşük bir endeks, daha fazla önem gösterir. İletişim uygulaması geliştiriyorsanız bunlar, uygulamanızda göründükleri gibi en son etkinliklere göre sıralanmış en iyi görüşmeler olabilir. Eski kısayolları yayınlamayın. Son 30 gün içinde kullanıcı etkinliği olmayan görüşmeler eski olarak kabul edilir.

    Kotlin

    ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))

    Java

    List<ShortcutInfoCompat> shortcuts = new ArrayList<>();
    shortcuts.add(shortcut1);
    shortcuts.add(shortcut2);
    ...
    ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
  3. Bir iletişim uygulaması geliştiriyorsanız kullanıcı bir kişiye mesaj aldığında veya gönderdiğinde pushDynamicShortcut aracılığıyla kısayol kullanımını hemen bildirin. Daha fazla bilgi için bu sayfadaki İletişim uygulamalarında kısayol kullanımını bildirme bölümüne bakın. Örneğin, ShortcutInfoCompat.Builder#addCapabilityBinding ile kısayolda yetenek bağlamaları belirterek kullanıcı tarafından gönderilen mesajların kullanımını actions.intent.SEND_MESSAGE yeteneğiyle raporlayabilirsiniz.

    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. Kullanıcı bir kişiyi silerse removeLongLivedShortcut kullanın. Bu, kısayolun sistem hizmetleri tarafından önbelleğe alınıp alınmadığına bakılmaksızın kısayolu kaldırmak için tercih edilen yöntemdir. Aşağıdaki kod snippet'inde bunun nasıl yapılacağına dair bir örnek gösterilmektedir.

    Kotlin

    val deleteShortcutId = "..."
    ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))

    Java

    String deleteShortcutId = "...";
    ShortcutManagerCompat.removeLongLivedShortcuts(
        myContext, Arrays.asList(deleteShortcutId));

Doğrudan paylaşım hedeflerinizin sıralamalarını iyileştirme

Android paylaşım sayfası, sabit sayıda doğrudan paylaşım hedefi gösterir. Bu öneriler sıralamaya göre düzenlenir. Aşağıdakileri yaparak kısayollarınızın sıralamasını iyileştirebilirsiniz:

  • Tüm shortcutIds değerlerinin benzersiz olduğundan ve farklı hedefler için asla yeniden kullanılmadığından emin olun.
  • setLongLived(true) numaralı telefonu arayarak kısayolun uzun ömürlü olmasını sağlayın.
  • İleti dizisiyle ilgili kısayollar için, ShortcutManagerCompat.pushDynamicShortcut üzerinden ilgili kısayolları yeniden yayınlayarak giden ve gelen iletilerde kısayol kullanımını bildirin. Ayrıntılar için bu sayfadaki İletişim uygulamaları için kısayol kullanımını bildirme bölümüne bakın.
  • Alakasız veya eski Doğrudan Paylaşım hedefleri sağlamaktan kaçının. Örneğin, kullanıcının son 30 gün içinde mesaj göndermediği kişiler.
  • SMS uygulamalarında, kısa kodlar veya olası spam olarak tanımlanan görüşmeler için kısayollar sağlamaktan kaçının. Kullanıcıların bu ileti dizilerinde paylaşım yapma olasılığı çok düşüktür.
  • Kısayolu uygun mimeType özellikleriyle ilişkilendirmek için setCategories() numaralı telefonu arayın. Örneğin, bir SMS uygulamasında, kişi RCS veya MMS özellikli değilse ilgili kısayolu image/* ve video/* gibi metin olmayan MIME türleriyle ilişkilendirmezsiniz.
  • Belirli bir görüşmede, dinamik kısayol gönderilip kullanımı bildirildikten sonra kısayol kimliğini değiştirmeyin. Bu sayede, sıralama için kullanım verilerinin saklanması sağlanır.

Kullanıcı herhangi bir doğrudan paylaşım hedefine dokunursa uygulamanız, kullanıcıyı hedef konusu üzerinde doğrudan işlem yapabileceği bir kullanıcı arayüzüne yönlendirmelidir. Kullanıcıya netleştirme kullanıcı arayüzü göstermeyin ve kullanıcıyı dokunulan hedefle alakasız bir kullanıcı arayüzüne yerleştirmeyin. Örneğin, bir mesajlaşma uygulamasında Doğrudan Paylaşım hedefi seçildiğinde kullanıcı, seçtiği kişiyle olan görüşme görünümüne yönlendirilir. Klavye görünür ve mesaj, paylaşılan verilerle önceden doldurulur.

Sharing Shortcuts API

Android 10 (API düzeyi 29) sürümünden itibaren, ShortcutInfo.Builder paylaşım hedefi hakkında ek bilgi sağlayan yöntemler ve geliştirmeler eklendi:

setCategories()
Android 10'dan itibaren, kategoriler paylaşım amaçlarını veya işlemleri işleyebilen kısayolları filtrelemek için de kullanılır. Ayrıntılar için Paylaşım hedefi bildirme başlıklı makaleyi inceleyin. Bu alan, paylaşım hedefi olarak kullanılacak kısayollar için gereklidir.
setLongLived()

Bir kısayolun, uygulamanın yayından kaldırması veya görünmez hale getirmesi (dinamik veya sabitlenmiş kısayol olarak) durumunda geçerli olup olmadığını belirtir. Uzun süreli bir kısayol, dinamik kısayol olarak yayından kaldırıldıktan sonra bile çeşitli sistem hizmetleri tarafından önbelleğe alınabilir.

Kısa yolu uzun ömürlü hale getirmek, sıralamasını yükseltebilir. Ayrıntılar için En iyi sıralamayı elde etme başlıklı makaleye bakın.

setShortLabel(), setLongLabel()

Bir kişiye kısayol yayınlarken lütfen tam adını setLongLabel(), takma ad veya ad gibi kısa adını ise setShortLabel() içine ekleyin.

GitHub'da paylaşım kısayollarını yayınlama örneğine bakın.

Kısayol görüntüleri sağlama

Paylaşım kısayolu oluşturmak için setIcon() üzerinden resim eklemeniz gerekir.

Paylaşım kısayolları, sistem yüzeylerinde görünebilir ve yeniden şekillendirilebilir. Ayrıca, Android'in 7, 8 veya 9 sürümlerini (API seviyeleri 25, 26, 27 ve 28) çalıştıran bazı cihazlarda yalnızca bit eşlem içeren ve arka planı olmayan simgeler gösterilebilir. Bu durum, kontrastı önemli ölçüde azaltır. Kısayolunuzun istediğiniz gibi görünmesi için IconCompat.createWithAdaptiveBitmap() kullanarak uyarlanabilir bir bit eşlem sağlayın.

Uyarlanabilir bit eşlemlerin, uyarlanabilir simgeler için belirlenen yönergeler ve boyutlara uygun olduğundan emin olun. Bunu yapmanın en yaygın yolu, amaçlanan kare bit eşlemi 72x72 dp boyutuna ölçeklendirmek ve bunu 108x108 dp boyutundaki şeffaf bir tuvalin ortasına yerleştirmektir. Simgenizde şeffaf bölgeler varsa arka plan rengi eklemeniz gerekir. Aksi takdirde, şeffaf bölgeler siyah görünür.

Belirli bir şekil için maskelenmiş görüntüler sağlamayın. Örneğin, Android 10'dan (API düzeyi 29) önce, Doğrudan Paylaşım ChooserTarget için kullanıcı avatarlarını daire şeklinde maskelemek yaygındı. Android 10'daki Android paylaşım sayfası ve diğer sistem yüzeyleri artık kısayol resimlerini şekillendirip temalandırıyor. ShortcutManagerCompat aracılığıyla paylaşım kısayolları sağlamak için tercih edilen yöntemdir. Bu yöntem, geriye dönük uyumluluk için doğrudan paylaşım ChooserTarget nesnelerini sizin için otomatik olarak daire şeklinde düzenler.

Paylaşım hedefi bildirme

Paylaşım hedefleri, statik kısayol tanımlarına benzer şekilde uygulamanın kaynak dosyasında tanımlanmalıdır. Kaynak dosyasındaki <shortcuts> kök öğesinin içine, diğer statik kısayol tanımlarıyla birlikte paylaşım hedefi tanımları ekleyin. Her <share-targets> öğesi; paylaşılan veri türü, eşleşen kategoriler ve paylaşım amacını işleyecek hedef sınıf hakkında bilgi içerir. XML kodu şu şekilde görünür:

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

Paylaşım hedefindeki veri öğesi, amaç filtresindeki veri spesifikasyonuna benzer. Her paylaşım hedefi, yalnızca bir uygulamanın yayınlanmış kısayollarını paylaşım hedefi tanımlarıyla eşleştirmek için kullanılan birden fazla kategoriye sahip olabilir. Kategoriler, uygulamayla tanımlanmış rastgele değerlere sahip olabilir.

Kullanıcı, Android paylaşım sayfasında yukarıdaki hedef paylaşım örneğiyle eşleşen paylaşım kısayolunu seçerse uygulama aşağıdaki paylaşım amaçlarını alır:

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>

Kullanıcı, paylaşım hedefini başlatıcı kısayollarından açarsa uygulama, paylaşım kısayolu ShortcutManagerCompat'a eklenirken oluşturulan amaca ulaşır. Farklı bir amaç olduğundan Intent.EXTRA_SHORTCUT_ID kullanılamaz ve ihtiyacınız olursa kimliği manuel olarak iletmeniz gerekir.

İletişim uygulamaları için kısayol kullanımını bildirme

Bir iletişim uygulaması geliştiriyorsanız hem giden hem de gelen mesajların kullanımını bildirerek Android paylaşım sayfasındaki sıralamanızı iyileştirebilirsiniz. Bunu yapmak için ShortcutManagerCompat.pushDynamicShortcut üzerinden kişiyi temsil eden görüşme kısayolunu yeniden yayınlayın.

Kısayol kullanımı ve özellik bağlamaları, Android 5.0 (API 21) ile geriye dönük uyumludur.

Giden iletiler için kısayol kullanımını raporlama

Kullanıcı tarafından gönderilen iletilerle ilgili kullanım raporlaması, ileti oluşturduktan sonra "Gönder" düğmesini tıklamaya işlevsel olarak benzerdir.

Kullanım raporlamasını tetiklemek için kısayolda ShortcutInfoCompat.Builder#addCapabilityBinding aracılığıyla actions.intent.SEND_MESSAGE özelliğiyle birlikte özellik bağlamalarını belirtin.

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

Giden mesaj bir grup sohbeti içinse Audience parametre değerini de recipient türüyle ilişkilendirilen özellik olarak eklemeniz gerekir.

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

Gelen iletiler için kısayol kullanımını bildirme

Kullanıcı SMS, sohbet mesajı, e-posta veya bildirim gibi bir mesaj aldığında kullanım raporlamasını tetiklemek için ShortcutInfoCompat.Builder#addCapabilityBinding ile kısayolda actions.intent.RECEIVE_MESSAGE özelliğiyle birlikte ek olarak özellik bağlamalarını belirtmeniz gerekir.

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

Gelen mesaj bir grup sohbetinden geliyorsa Audience parametre değerini de eklemeniz gerekir. Bunun nedeni, sender türünün bu özellik ile ilişkili olmasıdır.

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

Hem paylaşım kısayollarını hem de ChooserTarget'ları sağlamak için AndroidX'i kullanma

AndroidX uyumluluk kitaplığıyla çalışabilmek için uygulamanın manifest dosyasında meta veri seçici hedef hizmeti ve intent filtreleri ayarlanmış olmalıdır. Mevcut ChooserTargetService Direct Share API'yi inceleyin.

Bu hizmet, uyumluluk kitaplığında zaten beyan edildiği için kullanıcının hizmeti uygulamanın manifest dosyasında beyan etmesi gerekmez. Ancak, paylaşım etkinliğinden hizmete giden bağlantı, seçici hedef sağlayıcı olarak dikkate alınmalıdır.

Aşağıdaki örnekte, ChooserTargetService öğesinin uygulanması, AndroidX'te zaten tanımlanmış olan androidx.core.content.pm.ChooserTargetServiceCompat şeklindedir:

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

Paylaşım kısayolları hakkında SSS

Kısayol kullanım verileri nasıl depolanır ve cihazdan ayrılır mı?

Kısayollar, şifrelenmiş bir disk bölümündeki sistem veri dizininde tamamen cihaz üzerinde saklanır. Simgeler, amaç ve kişilerin ve kaynakların adları gibi kısayollardaki bilgilere yalnızca sistem hizmetleri ve kısayolları yayınlayan aynı uygulama erişebilir.

Doğrudan Paylaşım'ın geçmişi nedir?

Uygulamaların ChooserTargetService aracılığıyla ChooserTarget nesneleri sağlamasına olanak tanımak için Android 6.0 (API düzeyi 23) sürümünde Doğrudan Paylaşım özelliğini kullanıma sunduk. Sonuçlar, talep üzerine reaktif olarak alındığından hedeflerin yüklenme süresi yavaşlıyordu.

Android 10'da (API düzeyi 29), ChooserTargetService Direct Share API'lerinin yerini yeni Sharing Shortcuts API aldı. Paylaşım Kısayolları API'si, uygulamaların sonuçları talep üzerine reaktif olarak alması yerine doğrudan paylaşım hedeflerini önceden yayınlamasına olanak tanır. Bu, paylaşım sayfası hazırlanırken doğrudan paylaşım hedeflerinin alınması sürecini önemli ölçüde hızlandırdı. ChooserTargetServiceDoğrudan Paylaşım mekanizması çalışmaya devam edecek ancak sistem, bu şekilde sağlanan hedefleri, Paylaşım Kısayolları API'sini kullanan hedeflerden daha düşük sıralayacak.

Android 11 (API düzeyi 30), ChooserTargetService hizmetinin desteğini sonlandırdı ve Direct Share hedefleri sağlamanın tek yolu Sharing Shortcuts API'dir.

Paylaşım hedefleri için yayınlanan kısayollar, başlatıcı kısayollarından (başlatıcıda uygulama simgelerine uzun basıldığında kısayolların tipik kullanımı) nasıl farklıdır?

"Paylaşım hedefi" amacıyla yayınlanan tüm kısayollar, başlatıcı kısayolu olarak da kabul edilir ve uygulamanızın simgesine uzun basıldığında menüde gösterilir. Etkinlik başına maksimum kısayol sayısı sınırı, bir uygulamanın yayınladığı toplam kısayol sayısı (paylaşım hedefleri ve eski başlatıcı kısayolları birlikte) için de geçerlidir.

Kaç paylaşım kısayolu yayınlanması gerektiğiyle ilgili yönergeler nelerdir?

Paylaşım kısayollarının sayısı, getMaxShortcutCountPerActivity(android.content.Context) üzerinden kullanılabilen dinamik kısayolların sayısıyla aynı sınıra tabidir. Bu sınıra kadar herhangi bir sayı yayınlanabilir ancak paylaşım kısayollarının uygulama başlatıcıya uzun basıldığında ve paylaşım sayfasında görünebileceği unutulmamalıdır. Çoğu uygulama başlatıcı, uzun basıldığında dikey modda en fazla dört veya beş kısayol, yatay modda ise sekiz kısayol gösterir. Kısayolları paylaşma hakkında daha ayrıntılı bilgi ve rehberlik için bu SSS sayfasına göz atın.