Doğrudan paylaşım hedefleri sağlama

Diğer uygulama kullanıcılarının URL, resim veya diğer tür verileri uygulamanızla daha kolay ve hızlı bir şekilde paylaşmasını kolaylaştırmak için Doğrudan Paylaşım hedeflerini kullanın. Doğrudan Paylaşım, mesajlaşma ve sosyal medya uygulamalarındaki kişileri doğrudan Android Sharesheet'te sunarak çalışır. Kullanıcıların uygulamayı seçip daha sonra kişiyi aramasına gerek kalmaz.

ShortcutManagerCompat, paylaşım kısayolları sağlayan ve desteği sonlandırılan ChooserTargetService API ile geriye dönük uyumlu olan bir AndroidX API'dir. Hem Kısayolları Paylaşma hem de ChooserTargets yayınlamanın tercih edilen yolu budur. Talimatlar için bu sayfadaki Hem Paylaşım Kısayolları hem deChooserTarget hedefleri sağlamak için AndroidX'i kullanma bölümüne bakın.

Doğrudan Paylaşım hedeflerini yayınlama

Sharesheet Doğrudan Paylaşım satırı yalnızca Shared Kısayollar API'si tarafından sağlanan dinamik kısayolları gösterir. 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 tanımlayın.

   <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 derecesine göre sıralamak için setDynamicShortcuts aracını kullanın.

   Dizinin düşük olması önemin daha yüksek olduğunu gösterir. Bir iletişim uygulaması hazırlıyorsanız, bunlar uygulamanızda göründükleri yeniliğe göre sıralanmış en popüler konuşmalar olabilir. Eski kısayolları yayınlamayın; son 30 gün içinde kullanıcı etkinliği olmayan bir ileti dizisi, 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 her mesaj gönderdiğinde 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ı için kısayol kullanımını bildirme bölümüne bakın. Örneğin, actions.intent.SEND_MESSAGE özelliğiyle ShortcutInfoCompat.Builder#addCapabilityBinding arasındaki kısayolda özellik bağlamalarını belirterek kullanıcının gönderdiği mesajların kullanımını raporlayın.

   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 özelliğini kullanın. Sistem hizmetleri tarafından önbelleğe alınıp alınmamasından bağımsız olarak kısayolu kaldırmak için tercih edilen yöntem budur. 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ıralamasını iyileştirin

Android Sharesheet'te sabit sayıda Doğrudan Paylaşım hedefi gösteriliyor. Bu öneriler sıralamaya göre sıralanır. Aşağıdakileri yaparak kısayollarınızın sıralamasını artırabilirsiniz:

• Tüm shortcutIds öğelerinin benzersiz olduğundan ve hiçbir zaman farklı hedefler için yeniden kullanılmadığından emin olun.
• setLongLived(true) yöntemini çağırarak kısayolun uzun ömürlü olduğundan emin olun.
• İleti dizisiyle ilgili kısayollar için, ilgili kısayolları ShortcutManagerCompat.pushDynamicShortcut üzerinden yeniden yayınlayarak giden ve gelen mesajların 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.
• Kullanıcının son 30 gün içinde mesaj göndermediği kişiler gibi alakasız veya eski Doğrudan Paylaşım hedefleri sağlamaktan kaçının.
• SMS uygulamalarında, potansiyel spam olarak tanımlanan kısa kodlar veya görüşmeler için kısayol sunmaktan kaçının. Kullanıcıların bu sohbetlerde bir şeyi paylaşması pek olası değildir.
• Kısayolu uygun mimeType özellikleriyle ilişkilendirmek için setCategories() numaralı telefonu arayın. Örneğin, bir SMS uygulaması söz konusu olduğunda kişi RCS veya MMS özellikli değilse karşılık gelen kısayolu image/* ve video/* gibi metin dışı MIME türleriyle ilişkilendiremezsiniz.
• Belirli bir görüşme için dinamik kısayol aktarıldıktan ve kullanım raporlandıktan sonra kısayol kimliğini değiştirmeyin. Bu, sıralama için kullanım verilerinin saklanmasını sağlar.

Kullanıcı herhangi bir Direct Share hedefine dokunursa uygulamanız, kullanıcıyı doğrudan hedefin konusuyla ilgili işlem gerçekleştirebileceği bir kullanıcı arayüzüne yönlendirmelidir. Kullanıcıya açıklama amaçlı bir kullanıcı arayüzü sunmayın ve kullanıcıyı dokunulan hedefle ilgili olmayan bir kullanıcı arayüzüne yerleştirmeyin. Örneğin, bir mesajlaşma uygulamasında Doğrudan Paylaşım hedefine dokunulması, kullanıcıyı seçtiği kişiyle bir görüşme görünümüne yönlendirir. Klavye görünür ve mesaj, paylaşılan verilerle önceden doldurulur.

Paylaşım Kısayolları API'sı

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

setCategories()

Android 10'dan itibaren kategoriler, paylaşım amaçlarının veya işlemlerinin işleyebilen kısayolları filtrelemek için de kullanılmaktadır. Ayrıntılar için Paylaşım hedefi bildirme bölümüne bakın. Bu alan, paylaşım hedefi olarak kullanılacak kısayollar için zorunludur.

setLongLived()

Bir kısayolun, yayından kaldırıldığında veya uygulama tarafından görünmez hale getirildiğinde (dinamik veya sabitlenmiş kısayol olarak) geçerli olup olmadığını belirtir. Bir kısayol uzun ömürlüyse, dinamik kısayol olarak yayından kaldırılmış olsa bile çeşitli sistem hizmetleri tarafından önbelleğe alınabilir.

Bir kısayolu uzun ömürlü hale getirmek, sıralamasını iyileştirebilir. Daha fazla bilgi için En iyi sıralamayı alma bölümüne bakın.

setShortLabel(), setLongLabel()

Bir kullanıcı için kısayol yayınlarken lütfen setLongLabel() bölümüne tam adını ve takma ad ya da ad gibi kısa adları setShortLabel() biçiminde ekleyin.

GitHub'da Paylaşım Kısayolları Yayınlama örneğine bakın.

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

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

Paylaşım kısayolları sistem yüzeylerinde görünebilir ve yeniden şekillendirilebilir. Ayrıca, Android sürüm 7, 8 veya 9'u (API düzeyleri 25, 26, 27 ve 28) çalıştıran bazı cihazlarda arka plan olmadan yalnızca bit eşlem simgeleri görüntülenebilir. Bu durum, kontrastı önemli ölçüde azaltır. Kısayolunuzun istediğiniz gibi göründüğünden emin olmak için IconCompat.createWithAdaptiveBitmap() kullanarak uyarlanabilir bit eşleme sağlayın.

Uyarlanabilir bit eşlemlerin, uyarlanabilir simgeler için ayarlanan kurallara ve boyutlara uyduğundan emin olun. Bunu başarmanın en yaygın yolu, amaçlanan kare bit eşlemin 72x72 dp boyutuna ölçeklenmesi ve bunu 108x108 dp şeffaf tuvalin içine almaktır. Simgeniz şeffaf bölgeler içeriyorsa bir arka plan rengi eklemeniz gerekir. Aksi takdirde şeffaf bölgeler siyah görünür.

Belirli bir şekle maskelenmiş görüntüler sağlamayın. Örneğin, Android 10'dan (API düzeyi 29) önce, bir daire şeklinde maskelenen Doğrudan Paylaşım ChooserTarget'ler için kullanıcı avatarları yaygın olarak sağlanıyordu. Android Sharesheet ve Android 10'daki diğer sistem yüzeyleri artık kısayol görüntülerini şekillendiriyor ve temaya dönüştürüyor. ShortcutManagerCompat üzerinden Paylaşım Kısayolları sağlamak için tercih edilen yöntem, geriye dönük karşılaştırma Doğrudan Paylaşım ChooserTarget nesnelerini sizin için otomatik olarak şekiller.

Paylaşım hedefi tanımlama

Paylaşım hedefleri, statik kısayol tanımlarına benzer şekilde, uygulamanın kaynak dosyasında bildirilmelidir. Diğer statik kısayol tanımlarıyla birlikte kaynak dosyasındaki <shortcuts> kök öğesinin içine 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 şuna benzer:

<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 hedefinin birden fazla kategorisi olabilir. Bunlar yalnızca bir uygulamanın yayınlanan kısayollarını, paylaşım hedefi tanımlarıyla eşleştirmek için kullanılır. Kategorilerde rastgele uygulama tanımlı değerler olabilir.

Kullanıcının Android Sharesheet'te yukarıdaki örnek hedef paylaşım ile eşleşen Paylaşım Kısayolu'nu seçmesi durumunda uygulama aşağıdaki paylaşım amacını elde eder:

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ısayolunu shortManagerCompat komutlarına eklerken oluşturulan niyeti görür. Farklı bir amaç olduğu için Intent.EXTRA_SHORTCUT_ID kullanılamaz. Ayrıca, gerekirse 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 Sharesheet'te sıralamanızı iyileştirebilirsiniz. Bunu yapmak için, kişiyi temsil eden görüşme kısayolunu ShortcutManagerCompat.pushDynamicShortcut üzerinden 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ı raporla

Kullanıcı tarafından gönderilen mesajların rapor kullanımı, işlevsel olarak mesaj oluşturduktan sonra "gönder" düğmesini tıklamaya benzer.

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

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

Giden mesaj bir grup sohbeti içinse recipient türü özellikle ilişkilendirildiğinden Audience parametre değerini de eklemeniz gerekir.

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

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

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

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

Gelen mesaj bir grup sohbetinden geliyorsa sender türü özellikle ilişkili olduğundan Audience parametre değerini de eklemeniz gerekir.

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

Hem Paylaşım Kısayolları hem de Seçici Hedefleri sağlamak için AndroidX'i kullanın

AndroidX uyumluluk kitaplığıyla çalışılabilmesi için uygulamanın manifest dosyasında meta-veri seçici-hedef-hizmet ve intent-filtreleri grubunun bulunması gerekir. Mevcut ChooserTargetService Doğrudan Paylaşım API'sini inceleyin.

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

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

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

Kısayolları paylaşmayla ilgili SSS

Kısayol kullanım verileri nasıl saklanıyor ve cihazdan çıkıyor mu?

Kısayollar tamamen cihaz üzerinde, şifrelenmiş bir disk bölümündeki sistem veri dizininde depolanır. Kısayollardaki bilgilere (ör. simge, amaç, kişilerin ve kaynakların adları) yalnızca sistem hizmetleri ve kısayolları yayınlayan uygulama tarafından erişilebilir.

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

Uygulamaların ChooserTargetService aracılığıyla ChooserTarget nesneleri sağlamasına izin vermek için Android 6.0'da (API düzeyi 23) Direct Share'i kullanıma sunduk. Sonuçlar isteğe bağlı olarak tepkisel olarak alındığından hedefler yavaş yükleniyordu.

Android 10'da (API düzeyi 29) ChooserTargetService Direct Share API'leri yeni Share Kısayollar API'siyle değiştirdik. Paylaşım Kısayolları API'si, sonuçları istek üzerine tepkisel olarak almak yerine, uygulamaların Doğrudan Paylaşım hedeflerini önceden yayınlamasına olanak tanır. Bu da ShareSheet hazırlanırken Doğrudan Paylaşım hedefleri alma sürecini hızla hızlandırdı. ChooserTargetService Direct Share mekanizması çalışmaya devam edecektir. Ancak sistem, bu şekilde sağlanan hedefleri Paylaşım Kısayolları API'sini kullanan tüm hedeflerden çok daha düşük bir sırada sıralar.

Android 11 (API düzeyi 30), ChooserTargetService hizmetini kullanımdan kaldırmıştır. Doğrudan Paylaşım hedefleri sağlamanın tek yolu da Shared Kısayollar API'sidir.

Paylaşım hedefleri için yayınlanan kısayolların, başlatıcı kısayollarından (başlatıcıdaki uygulama simgelerine uzun basıldığında tipik kısayolların kullanımı) farkı nedir?

"Paylaşım hedefi" amacıyla yayınlanan tüm kısayollar, aynı zamanda bir başlatıcı kısayoludur ve uygulamanızın simgesine uzun süre 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şma hedefleri ve eski başlatıcı kısayolları) için de geçerlidir.

Yayınlanması gereken paylaşım kısayollarının sayısıyla ilgili yol gösterici bilgiler nelerdir?

Paylaşım kısayollarının sayısı, getMaxShortcutCountPerActivity(android.content.Context) üzerinden kullanılabilen aynı dinamik kısayol sınırıyla sınırlıdır. Bu sınır için 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ülebileceğini unutmayın. Uzun basıldığında çoğu uygulama başlatıcıda en fazla dört veya beş kısayol dikey modda, sekiz tane ise yatay modda görüntülenir. Kısayolları paylaşmayla ilgili daha fazla ayrıntı ve yardım için bu SSS bölümüne bakın.