Doğrudan paylaşım hedefleri sağlama

ile gösterilen doğrudan paylaşım satırı

Diğer uygulama kullanıcılarının URL'leri, resimleri veya başka tür verileri 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, kullanıcıların uygulamayı seçip kişiyi aramak zorunda kalmadan mesajlaşma ve sosyal medya uygulamalarındaki kişileri doğrudan Android Paylaşım Sayfası'nda sunar.

ShortcutManagerCompat, paylaşım kısayolları sağlayan ve kullanımdan kaldırılan ChooserTargetService API ile geriye dönük uyumlu bir AndroidX API'sidir. Hem Paylaşım Kısayollarını hem de ChooserTargets'ü yayınlamanın tercih edilen yolu budur. Talimatlar için bu sayfadaki Paylaşım kısayolları ve ChooserTargets sağlamak için AndroidX'i kullanma başlıklı makaleyi inceleyin.

Doğrudan Paylaşım hedeflerini yayınlama

Paylaşım sayfası Doğrudan Paylaşım satırı yalnızca Paylaşım Kısayollarını 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 öğeleri 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 ilk başlatıldığında dinamik kısayolları öneme göre sıralamak için setDynamicShortcuts simgesini kullanın.

   Düşük bir endeks, daha yüksek önemi gösterir. Bir iletişim uygulaması geliştiriyorsanız bunlar, uygulamanızda göründükleri şekilde en sona göre sıralanan 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 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 mesaj gönderdiğinde pushDynamicShortcut üzerinden 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 aracılığıyla kısayolda özellik bağlamalarını belirterek kullanıcı tarafından gönderilen 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 simgesini kullanın. Sistem hizmetleri tarafından önbelleğe alınıp alınmadığına bakılmaksızın kısayolu kaldırmanın tercih edilen yolu 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ıralamalarına göre sıralama

Android paylaşım sayfasında sabit sayıda doğrudan paylaşım hedefi gösterilir. Bu öneriler sıralamaya göre sıralanır. 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) işlevini çağırarak kısayolun uzun ömürlü olmasını sağlayın.
• İleti dizisiyle ilgili kısayollar için ShortcutManagerCompat.pushDynamicShortcut aracılığıyla 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 (ör. kullanıcının son 30 gün içinde mesajlaşmadığı kişiler) sağlamamaya çalışın.
• SMS uygulamaları için kısa kodlar veya potansiyel spam olarak tanımlanan görüşmeler için kısayollar sağlamamaya çalışın. Kullanıcıların bu ileti dizilerini paylaşması pek olası değildir.
• Kısayolayı uygun mimeType özelliklerine ilişkilendirmek için setCategories() işlevini çağırın. Örneğin, bir SMS uygulamasında kişi RCS veya MMS'yi etkinleştirmiyorsa ilgili kısayolu image/* ve video/* gibi metin dışı MIME türleriyle ilişkilendirmezsiniz.
• Belirli bir görüşmede dinamik bir kısayol gönderildikten ve kullanım raporlandıktan 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ı doğrudan hedefin konusuyla ilgili işlem yapabileceği bir kullanıcı arayüzüne yönlendirmelidir. Kullanıcıya anlam ayrımı yapan bir kullanıcı arayüzü göstermeyin ve kullanıcıyı, dokunulan hedefle alakalı olmayan bir kullanıcı arayüzüne yerleştirmeyin. Örneğin, bir mesajlaşma uygulamasında Doğrudan Paylaşım hedefine dokunulduğunda kullanıcı, seçtiği kişiyle olan görüşme görünümüne yönlendirilir. Klavye görünür durumdadı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 ekledi:

setCategories()

Android 10'dan itibaren kategoriler, paylaşım intent'lerini veya işlemlerini işleyebilecek kısayolları filtrelemek için de kullanılır. Ayrıntılar için Paylaşım hedefi tanımlama başlıklı makaleyi inceleyin. Bu alan, paylaşım hedefleri olarak kullanılması amaçlanan kısayollar için gereklidir.

setLongLived()

Bir kısayolun yayınlanmamış veya uygulama tarafından görünmez hale getirilmiş (dinamik ya da sabitlenmiş kısayol olarak) durumda geçerli olup olmadığını belirtir. Uzun ömürlü bir kısayol, dinamik kısayol olarak yayınlandıktan sonra bile çeşitli sistem hizmetleri tarafından önbelleğe alınabilir.

Bir kısayolun uzun ömürlü olması, sıralamasını iyileştirebilir. Ayrıntılar için En iyi sıralamayı elde etme başlıklı makaleyi inceleyin.

setShortLabel(), setLongLabel()

Bir kişinin kısayolunu yayınlarken lütfen setLongLabel() alanına tam adını, setShortLabel() alanına ise takma ad veya ad gibi kısa bir adı ekleyin.

Paylaşım kısayollarını GitHub'da yayınlama örneğine göz atın.

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

Paylaşım kısayolu oluşturmak için setIcon() aracılığıyla bir resim eklemeniz gerekir.

Paylaşım kısayolları sistem platformlarında görünebilir ve yeniden şekillendirilebilir. Ayrıca, Android 7, 8 veya 9 sürümlerini (API seviyeleri 25, 26, 27 ve 28) çalıştıran bazı cihazlar, yalnızca bitmap simgelerini arka plan olmadan gösterebilir. Bu da kontrastı önemli ölçüde azaltır. Kısayolunuzun istediğiniz gibi görünmesini sağlamak için IconCompat.createWithAdaptiveBitmap() kullanarak uyarlanabilir bir bitmap sağlayın.

Uyarlanabilir bitmap'lerin uyarlanabilir simgeler için belirlenen yönergelere ve boyutlara uyduğundan emin olun. Bunu yapmanın en yaygın yolu, istenen kare bitmap'i 72x72 dp'ye ölçeklendirmek ve 108x108 dp şeffaf bir kanvasta ortalanmasıdır. Simgeniz şeffaf bölgeler içeriyorsa arka plan rengi eklemeniz gerekir. Aksi takdirde şeffaf bölgeler siyah görünür.

Belirli bir şekle maskelenmiş görüntüler göndermeyin. Örneğin, Android 10 (API düzeyi 29) öncesinde, Doğrudan Paylaşım ChooserTarget'ları için daire şeklinde maskelenmiş kullanıcı avatarları sağlamak yaygındı. Android 10'daki Android Paylaşım Sayfası ve diğer sistem platformları artık kısayol resimlerini şekillendirip temalandırıyor. Paylaşım kısayolları sağlamak için tercih edilen yöntem, ShortcutManagerCompat aracılığıyla, geriye dönük uyumlu Doğrudan Paylaş ChooserTarget nesnelerini sizin için otomatik olarak daireler şeklinde biçimlendirmektir.

Paylaşım hedefi belirtme

Paylaşım hedefleri, statik kısayol tanımlarına benzer şekilde uygulamanın kaynak dosyasında tanımlanmalıdır. Diğer statik kısayol tanımlarıyla birlikte, kaynak dosyasındaki <shortcuts> kök öğesine 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şleyen 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, intent filtresindeki veri spesifikasyonuna benzer. Her paylaşım hedefinin birden fazla kategorisi olabilir. Bu kategoriler yalnızca bir uygulamanın yayınlanan kısayollarını, paylaşım hedefi tanımlarıyla eşleştirmek için kullanılır. Kategoriler, uygulama tarafından tanımlanan herhangi bir değere 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 uygulamaya aşağıdaki paylaşım amacı gönderilir:

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ı, başlatıcı kısayollarından paylaşım hedefini açarsa uygulama, paylaşım kısayolu ShortcutManagerCompat'e eklenirken oluşturulan intent'i alır. Farklı bir intent olduğu için Intent.EXTRA_SHORTCUT_ID kullanılamaz ve ihtiyacınız varsa kimliği manuel olarak iletmeniz gerekir.

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

İletişim uygulaması geliştiriyorsanız hem giden hem de gelen mesajların kullanımını bildirerek Android Paylaş Sayfası'ndaki sıralamanızı yükseltebilirsiniz. Bunu yapmak için kişiyi temsil eden ileti dizisi 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ı bildirme

Kullanıcı tarafından gönderilen mesajların kullanımını bildirme işlevi, 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 sohbet içinse recipient 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.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 mesajlar 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 actions.intent.RECEIVE_MESSAGE özelliğiyle ShortcutInfoCompat.Builder#addCapabilityBinding aracılığıyla kısayolda ek olarak ö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 ChooserTargets 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-hizmet ve intent filtreleri grubu bulunmalı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 için AndroidX'te zaten tanımlanmış olan androidx.core.content.pm.ChooserTargetServiceCompat uygulaması kullanılmıştı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>

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

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

Kısayollar, şifrelenmiş bir disk bölümündeki sistem veri dizininde tamamen cihaz üzerinde depolanır. Kısayollardaki simge, intent, kullanıcı ve kaynak adları gibi bilgilere yalnızca sistem hizmetleri ve kısayolları yayınlayan uygulama erişebilir.

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

Uygulamaların ChooserTargetService üzerinden ChooserTarget nesneleri sağlamasına olanak tanımak için Android 6.0'ta (API düzeyi 23) Doğrudan Paylaşım özelliğini kullanıma sunduk. Sonuçlar, istek üzerine reaktif olarak alındı. Bu da hedeflerin yavaş yüklenmesine neden oldu.

Android 10'da (API düzeyi 29) ChooserTargetService Doğrudan Paylaşım API'lerini yeni Paylaşım Kısayolları API'siyle değiştirdik. Paylaşım Kısayolları API'si, sonuçları istek üzerine reaktif olarak almak yerine uygulamaların Doğrudan Paylaşım hedeflerini önceden yayınlamasına olanak tanır. Bu sayede, Paylaşım E-Tablosu hazırlanırken Doğrudan Paylaşım hedeflerinin alınması işlemi hızlandı. ChooserTargetService Doğ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 bir sıralamaya yerleştirir.

Android 11 (API düzeyi 30) ile ChooserTargetService hizmetinin desteği sonlandırıldı ve Doğrudan Paylaşım hedeflerini sağlamanın tek yolu Paylaşım Kısayolları API'sidir.

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?

"Hedefi paylaş" amacıyla yayınlanan tüm kısayollar, başlatıcı kısayoludur ve uygulamanızın simgesine uzun bastığınızda 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ı dahil) için de geçerlidir.

Yayınlanması gereken paylaşım kısayollarının sayısıyla ilgili kurallar 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 sahiptir. Bu sınıra kadar dilediğiniz sayıda kısayol yayınlayabilirsiniz ancak paylaşım kısayollarının, uygulama başlatıcıda uzun basıldığında ve paylaşım sayfasında görünebileceğini unutmayın. Uzun basıldığında çoğu uygulama başlatıcıda dikey modda en fazla dört veya beş, yatay modda ise sekiz kısayol gösterilir. Kısayol paylaşma hakkında daha fazla bilgi ve yol gösterici bilgiler için bu SSS sayfasına bakın.