Kısayolları yönet

Kısayolları oluşturduktan sonra uygulamanızın kullanım ömrü boyunca bunları yönetmeniz gerekebilir. Örneğin, kullanıcılarınızın kısayollarınızla belirli işlemleri ne sıklıkta tamamladığını belirleyerek uygulamanızı optimize etmek isteyebilirsiniz. Başka bir durumda, uygulamanızın eski veya eksik işlemler gerçekleştirmesini önlemek için sabitlenmiş bir kısayolu devre dışı bırakmaya karar verebilirsiniz. Görüşmelerde referans verilen kısayollar için, kısayol sıralamasını iyileştiren sinyaller sağlamak amacıyla kullanımı izlemek isteyebilirsiniz.

Bu sayfada, kısayollarınızı yönetmek için kullanabileceğiniz bu ve diğer yaygın yöntemler açıklanmaktadır.

Kısayol davranışı

Aşağıdaki bölümlerde, görünürlük, görüntüleme sırası ve sıralamalar dahil olmak üzere kısayol davranışıyla ilgili genel bilgiler yer almaktadır.

Kısayol görünürlüğü

Kullanıcı belirli bir hareket veya sesli komut gerçekleştirdiğinde, desteklenen bir başlatıcıda veya asistanda statik kısayollar ve dinamik kısayollar görünür. Desteklenen başlatıcılarda hareket, uygulamanın başlatıcı simgesine dokunup basılı tutmaktır ancak diğer başlatıcı uygulamalarında hareket farklı olabilir. Google Asistan ile kısayollar, Asistan'da gösterilebilir veya kullanıcı sesli komutuyla başlatılabilir.

LauncherApps sınıfı, başlatıcı uygulamalarının kısayollara erişmesi için API'ler sağlar.

Sabitlenen kısayollar başlatıcıda göründüğünden her zaman görünür durumdadır. Sabitlenmiş bir kısayol, başlatıcıdan yalnızca aşağıdaki durumlarda kaldırılır:

• Kullanıcı tarafından kaldırılması
• Kısayolla ilişkili uygulama kaldırıldığında
• Kullanıcı, Ayarlar > Uygulamalar ve bildirimler'e gidip uygulamayı seçtikten sonra Depolama alanı > Depolama alanını temizle'ye dokunarak uygulamanın verilerini temizler.

Paylaşım hedefleri, Android paylaşım sayfasının doğrudan paylaşım satırında görünen dinamik kısayolların bir alt kümesidir.

Kısayol görüntüleme sırası

Başlatıcı, bir uygulamanın kısayollarını gösterirken bunları aşağıdaki sırayla göstermelidir:

1. Statik kısayollar: isDeclaredInManifest() yöntemi true değerini döndüren kısayollar.
2. Dinamik kısayollar: ShortcutInfo.isDynamic() yönteminin true değerini döndürdüğü kısayollar.

Her kısayol türünde (statik ve dinamik) kısayollar, ShortcutInfo.getRank uyarınca artan sıralama düzenine göre sıralanır. Google Asistan, kullanıcılara gösterilecek bağlamsal kısayolları belirlerken kısayol sıralamasını da dikkate alır.

Sıralar, negatif olmayan sıralı tam sayılardır. Statik kısayollar, shortcuts.xml dosyanızda göründükleri sıraya göre baştan sona doğru sıralanır. Dinamik kısayollar için updateShortcuts(Context, List), addDynamicShortcuts(Context, List), pushDynamicShortcut(Context, ShortcutInfoCompat) veya setDynamicShortcuts(Context, List) yöntemini çağırarak mevcut kısayolların sıralamasını güncelleyebilirsiniz.

Paylaşım hedeflerinin sırası; geçmiş kullanıcı geçmişi, güncellik, sıklık, sıralama ipucu, uygulama kullanımı ve paylaşım kısayoluyla ilişkili görüşmeye ayarlanan öncelik gibi çeşitli faktörlere bağlıdır. Sharing Shortcuts API kullanılarak oluşturulan paylaşım hedefleri, Android 11'de desteği sonlandırılan ChooserTargetService tarafından oluşturulan paylaşım hedeflerine göre önceliklidir. Android 12 ve sonraki sürümlerde, desteği sonlandırılan ChooserTargetService tarafından oluşturulan paylaşım hedefleri artık paylaşım sayfasında görünmez.

Çoğu başlatıcıda en fazla dört kısayol gösterilir. Tanımlanan statik kısayollar ve dinamik kısayolların herhangi bir kombinasyonu için başlatıcı, en fazla iki statik kısayol ve iki dinamik kısayol gösterir. Örneğin, dört statik kısayol tanımlar ve programatik olarak üç dinamik kısayol oluşturursanız başlatıcı, ilk iki statik kısayolu ve en yüksek sıralamaya sahip iki dinamik kısayolu gösterir.

Birden fazla niyet ve etkinliği yönetme

Kullanıcınız bir kısayolu etkinleştirdiğinde uygulamanızın birden fazla işlem yapmasını istiyorsanız uygulamayı, birbirini izleyen etkinlikleri tetikleyecek şekilde yapılandırabilirsiniz. Kısayolun türüne bağlı olarak birden fazla intent atayarak, bir etkinliği diğerinden başlatarak veya intent işaretleri ayarlayarak bunu yapabilirsiniz.

Bir etkinliği başka bir etkinlikten başlatma

Statik kısayollarda özel amaç işaretleri bulunamaz. Statik bir kısayolun ilk intent'inde her zaman Intent.FLAG_ACTIVITY_NEW_TASK ve Intent.FLAG_ACTIVITY_CLEAR_TASK ayarlanır. Bu, uygulamanız çalışırken statik bir kısayol başlatıldığında uygulamadaki mevcut tüm etkinliklerin yok edildiği anlamına gelir. Bu davranışı istemiyorsanız bir başlatma bloğunda veya onCreate içinde, Oluşturma içeriği ayarlanmadan önce finish'i çağırarak bir trambolin etkinliği (başka bir etkinliği başlatan görünmez bir etkinlik) kullanabilirsiniz:

1. AndroidManifest.xml file içinde, trambolin etkinliğine özellik atamasını android:taskAffinity="" ekleyin.

2. Kısayollar kaynak dosyasında, statik kısayoldaki intent'te trambolin etkinliğine referans verin.

Trambolin etkinlikleri hakkında daha fazla bilgi için Bir etkinliği başka bir etkinlikten başlatma başlıklı makaleyi inceleyin.

Intent işaretlerini ayarlama

Dinamik kısayolları herhangi bir Intent işaret grubuyla yayınlayabilirsiniz. Tercihen, kısayolun intent'inde Intent.FLAG_ACTIVITY_SINGLE_TOP ve Intent.FLAG_ACTIVITY_CLEAR_TOP kombinasyonunu belirtin. Bu sayede, ComponentActivity etkinliğiniz zaten etkinse ön plana getirilir ve yok edilmeden yeniden kullanılır. Böylece tek etkinlikli mimariniz, kısayol etkinliğini onNewIntent() aracılığıyla sorunsuz bir şekilde işleyebilir.

Görevler ve intent işaretleri hakkında daha fazla bilgi edinmek için Görevler ve eski yığın başlıklı makaleyi inceleyin.

Kısayolları güncelleme

Her uygulamanın başlatıcı simgesi, en fazla getMaxShortcutCountPerActivity tarafından döndürülen değere eşit sayıda statik ve dinamik kısayol içerebilir. Bir uygulamanın oluşturabileceği sabitlenmiş kısayol sayısıyla ilgili bir sınır yoktur.

Dinamik kısayol sabitlendiğinde, yayıncı bunu dinamik kısayol olarak kaldırsa bile sabitlenen kısayol görünür ve başlatılabilir durumda kalır. Bu sayede bir uygulama getMaxShortcutCountPerActivity adetten fazla kısayola sahip olabilir.

getMaxShortcutCountPerActivity tarafından döndürülen değerin 4 olduğunu varsayan aşağıdaki örneği inceleyin:

1. Bir sohbet uygulaması, en son dört görüşmeyi temsil eden dört dinamik kısayol yayınlar: c1, c2, c3 ve c4.
2. Kullanıcı, dört kısayolun tümünü sabitler.
3. Kullanıcı daha sonra üç görüşme daha başlatır: c5, c6 ve c7. Yayıncı uygulama, dinamik kısayollarını yeniden yayınlar. Yeni dinamik kısayol listesi: c4, c5, c6 ve c7.

Uygulama, dörtten fazla dinamik kısayol gösteremediği için c1, c2 ve c3'ü kaldırmak zorundadır. Ancak c1, c2 ve c3, kullanıcının erişebileceği ve başlatabileceği sabitlenmiş kısayollar olmaya devam eder.

Kullanıcı daha sonra yayıncı uygulamasındaki etkinliklere bağlantı veren toplam yedi kısayola erişebilir. Bunun nedeni, toplamın maksimum kısayol sayısını ve sabitlenmiş üç kısayolu içermesidir.

1. Uygulama, mevcut yedi kısayoldan herhangi birini güncellemek için updateShortcuts(Context, List) kullanabilir. Örneğin, sohbet edilen kişilerin simgeleri değiştiğinde bu kısayol grubunu güncelleyebilirsiniz.
2. Aynı kimliklere sahip mevcut kısayolları güncellemek için addDynamicShortcuts(Context, List) ve setDynamicShortcuts(Context, List) yöntemlerini kullanabilirsiniz. Ancak bu yöntemleri dinamik olmayan, sabitlenmiş kısayolları güncellemek için kullanamazsınız. Bunun nedeni, bu iki yöntemin verilen kısayol listelerini dinamik kısayollara dönüştürmeye çalışmasıdır.

Google Asistan gibi asistan uygulamalarında gösterilmek üzere gönderilebilecek kısayol sayısı sınırlı değildir. Asistan uygulamalarında kullanılacak kısayollar oluşturmak ve güncellemek için ShortcutManagerCompat Jetpack kitaplığının pushDynamicShortcut yöntemini kullanın. Ayrıca, dinamik bağlantıların Google Asistan'da gösterilmeye uygun olması için uygulamanıza Google Shortcuts Integration kitaplığını ekleyin.

Kısayolları güncelleme de dahil olmak üzere uygulama kısayollarıyla ilgili yönergeler hakkında daha fazla bilgi edinmek için Kısayollar için en iyi uygulamalar başlıklı makaleyi inceleyin.

Sistem yerel ayar değişikliklerini işleme

Uygulamalar, sistem yerel ayarında değişiklik olduğunu belirten Intent.ACTION_LOCALE_CHANGED yayınını aldıklarında dinamik ve sabitlenmiş kısayolları güncellemelidir.

Kısayol kullanımını izleme

Başlatıcı, statik ve dinamik kısayolların göründüğü durumları belirlemek için kısayolların etkinleştirme geçmişini inceler. Statik kısayollar için, aşağıdaki etkinliklerden biri gerçekleştiğinde reportShortcutUsed yöntemini çağırıp kısayolun kimliğini ileterek kullanıcıların uygulamanızda belirli işlemleri ne zaman tamamladığını takip edebilirsiniz:

• Kullanıcı, belirtilen kimliğe sahip kısayolu seçer.
• Kullanıcı, uygulamada aynı kısayola karşılık gelen işlemi manuel olarak tamamlar.

Uygulamanız, ilgili bir etkinlik gerçekleştiğinde pushDynamicShortcut yöntemini çağırıp kısayolun kimliğini ileterek dinamik kısayolların kullanımını izler. Dinamik kısayol kullanımını bu yöntemle göndermek, Google Asistan gibi asistan uygulamalarının kullanıcılara alakalı kısayollar önermesini sağlar. pushDynamicShortcut yöntemi, çağrıldığında kullanımı raporladığından aynı kısayollar için reportShortcutUsed yöntemini çağırmayın.

Görüşmeyle ilgili kısayollarda, giden ve gelen mesajların kullanımını takip etmek önemlidir. Ayrıntılı bilgi için kişiler ve görüşmelerle ilgili en iyi uygulamalara bakın.

Kısayolları devre dışı bırak

Uygulamanız ve kullanıcıları, cihazın başlatıcısına kısayollar sabitleyebildiğinden, bu sabitlenmiş kısayollar kullanıcıları uygulamanızda güncel olmayan veya artık mevcut olmayan işlemlere yönlendirebilir. Bu durumu yönetmek için disableShortcuts yöntemini çağırarak kullanıcıların seçmesini istemediğiniz kısayolları devre dışı bırakabilirsiniz. Bu yöntem, belirtilen kısayolları statik ve dinamik kısayollar listesinden kaldırır ve bu kısayolların sabitlenmiş kopyalarını devre dışı bırakır. Bu yöntemin, özel hata mesajı olarak CharSequence kabul eden aşırı yüklenmiş bir sürümünü de kullanabilirsiniz. Kullanıcılar devre dışı bırakılmış bir kısayolu başlatmaya çalıştığında bu hata mesajı gösterilir.

Sıklık sınırlaması

setDynamicShortcuts, addDynamicShortcuts veya updateShortcuts yöntemlerini kullanırken bu yöntemleri arka plan uygulamasında (ön planda etkinliği veya hizmeti olmayan bir uygulama) yalnızca belirli sayıda çağırabilirsiniz. Bu yöntemleri çağırabileceğiniz belirli sayıdaki sınır, sıklık sınırlaması olarak adlandırılır. Bu özellik, ShortcutManagerCompat uygulamasının cihaz kaynaklarını aşırı tüketmesini önler.

Sıklık sınırlaması etkin olduğunda isRateLimitingActive, "true" değerini döndürür. Ancak sıklık sınırlaması belirli etkinlikler sırasında sıfırlanır. Bu nedenle, arka plan uygulamaları bile sıklık sınırına tekrar ulaşılana kadar ShortcutManager yöntemlerini çağırabilir. Bu etkinlikler aşağıdakileri içerir:

• Bir uygulama ön plana geldiğinde
• Sistem yerel ayarı değişir.
• Kullanıcı, bir bildirimde satır içi yanıt işlemini gerçekleştirir.

Geliştirme veya test sırasında sıklık sınırlamasıyla karşılaşırsanız cihazın ayarlarından Geliştirici Seçenekleri > ShortcutManager sıklık sınırlamasını sıfırla'yı seçebilir veya adb aracına aşağıdaki komutu girebilirsiniz:

adb shell cmd shortcut reset-throttling [ --user your-user-id ]

Yedekleme ve geri yükleme

Uygulamanızın manifest dosyasına android:allowBackup="true" özellik atamasını ekleyerek kullanıcıların cihaz değiştirirken uygulamanızda yedekleme ve geri yükleme işlemleri yapmasına izin verebilirsiniz. Yedekleme ve geri yükleme özelliğini destekliyorsanız uygulama kısayollarıyla ilgili aşağıdaki noktaları aklınızda bulundurun:

• Statik kısayollar otomatik olarak yeniden yayınlanır ancak bu işlem yalnızca kullanıcı uygulamanızı yeni bir cihaza yeniden yükledikten sonra gerçekleşir.
• Dinamik kısayollar yedeklenmez. Bu nedenle, kullanıcı uygulamanızı yeni bir cihazda açtığında bunları yeniden yayınlamak için uygulamanıza mantık ekleyin.
• Sabitlenmiş kısayollar cihazın başlatıcısına otomatik olarak geri yüklenir ancak sistem, sabitlenmiş kısayollarla ilişkili simgeleri yedeklemez. Bu nedenle, sabitlenmiş kısayollarınızın resimlerini uygulamanıza kaydederek yeni bir cihazda hızlıca geri yükleyebilirsiniz.

Aşağıdaki kod snippet'i, uygulamanızın dinamik kısayollarını geri yüklemenin ve uygulamanızın sabitlenmiş kısayollarının korunup korunmadığını kontrol etmenin en iyi yolunu gösterir:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getShortcuts(this, ShortcutManagerCompat.FLAG_MATCH_PINNED).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}
ShortcutsSnippets.kt