Kısayol oluşturma

Kısayollar, kullanıcıların uygulamanızın bölümlerine hızlıca erişmesine yardımcı olarak onlara belirli içerik türleri sunar.

Şekil 1. Uygulama kısayolları ve sabitlenmiş kısayollar.

Kısayollarla içerik sunma şekliniz, kullanım alanınıza ve kısayolun bağlamının uygulama odaklı mı yoksa kullanıcı odaklı mı olduğuna bağlıdır. Statik kısayolların bağlamı değişmezken dinamik kısayolların bağlamı sürekli değişir. Ancak her iki durumda da bağlamı uygulamanız belirler. Kullanıcının, uygulamanızın içeriği kendisine nasıl sunacağını seçtiği durumlarda (ör. sabitlenmiş kısayol) bağlam kullanıcı tarafından tanımlanır. Aşağıdaki senaryolarda her kısayol türü için birkaç kullanım alanı açıklanmaktadır:

• Statik kısayollar, kullanıcının uygulamayla etkileşimi boyunca tutarlı bir yapı kullanarak içeriğe bağlanan uygulamalar için en uygun olanıdır. Çoğu başlatıcı yalnızca dört kısayolu aynı anda gösterdiğinden statik kısayollar, rutin bir görevi tutarlı bir şekilde gerçekleştirmek için kullanışlıdır. Örneğin, kullanıcı takvimini veya e-postasını belirli bir şekilde görüntülemek istiyorsa bu kısayolları kullanabilir.
• Dinamik kısayollar, bağlama duyarlı uygulamalardaki işlemler için kullanılır. Bağlama duyarlı kısayollar, kullanıcıların bir uygulamada gerçekleştirdiği işlemlere göre uyarlanır. Örneğin, kullanıcının başlatıldığında mevcut seviyesinden başlamasına olanak tanıyan bir oyun oluşturursanız kısayolu sık sık güncellemeniz gerekir. Dinamik kısayol kullanarak, kullanıcı bir seviyeyi her tamamladığında kısayolu güncelleyebilirsiniz.
• Sabitlenmiş kısayollar, kullanıcı tarafından gerçekleştirilen belirli işlemler için kullanılır. Örneğin, bir kullanıcı belirli bir web sitesini başlatıcıya sabitlemek isteyebilir. Bu, kullanıcının web sitesine gitmek gibi özel bir işlemi tek adımda, tarayıcının varsayılan bir örneğini kullanmaktan daha hızlı bir şekilde gerçekleştirmesine olanak tanıdığı için faydalıdır.

Statik kısayollar oluşturma

Statik kısayollar, uygulamanızdaki genel işlemlere bağlantılar sağlar. Bu işlemler, uygulamanızın mevcut sürümünün kullanım ömrü boyunca tutarlı kalmalıdır. Statik kısayollar için iyi seçenekler arasında gönderilen iletileri görüntüleme, alarm ayarlama ve kullanıcının o günkü egzersiz etkinliğini gösterme yer alır.

Statik kısayol oluşturmak için aşağıdakileri yapın:

1. Uygulamanızın AndroidManifest.xml dosyasında, amaç filtreleri android.intent.action.MAIN işlemi ve android.intent.category.LAUNCHER kategorisine ayarlanmış etkinliği bulun.

2. Bu etkinliğe, uygulamanın kısayollarının tanımlandığı kaynak dosyasına referans veren bir <meta-data> öğesi ekleyin:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
             package="com.example.myapplication">
     <application ... >
       <activity android:name="Main">
         <intent-filter>
           <action android:name="android.intent.action.MAIN" />
           <category android:name="android.intent.category.LAUNCHER" />
         </intent-filter>
         <meta-data android:name="android.app.shortcuts"
                    android:resource="@xml/shortcuts" />
       </activity>
     </application>
   </manifest>
   

   Not: activity-alias kullanıyorsanız meta verileri, targetActivity özelliğini kullanarak hedeflediği etkinlik yerine etkinlik takma adında tanımlayın.

3. res/xml/shortcuts.xml adlı yeni bir kaynak dosyası oluşturun.

4. Yeni kaynak dosyasına, <shortcut> öğelerinin listesini içeren bir <shortcuts> kök öğesi ekleyin. Her <shortcut> öğesine, simgesi, açıklama etiketleri ve uygulama içinde başlattığı amaçlar dahil olmak üzere statik bir kısayolla ilgili bilgileri ekleyin:

   <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
     <shortcut
       android:shortcutId="compose"
       android:enabled="true"
       android:icon="@drawable/compose_icon"
       android:shortcutShortLabel="@string/compose_shortcut_short_label1"
       android:shortcutLongLabel="@string/compose_shortcut_long_label1"
       android:shortcutDisabledMessage="@string/compose_disabled_message1">
       <intent
         android:action="android.intent.action.VIEW"
         android:targetPackage="com.example.myapplication"
         android:targetClass="com.example.myapplication.Main" />
       <!-- If your shortcut is associated with multiple intents, include them
            here. The last intent in the list determines what the user sees when
            they launch this shortcut. -->
       <categories android:name="android.shortcut.conversation" />
       <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
     </shortcut>
     <!-- Specify more shortcuts here. -->
   </shortcuts>
   

Özellik değerlerini özelleştirme

Aşağıdaki listede, statik kısayoldaki farklı özelliklerin açıklamaları yer almaktadır. android:shortcutId ve android:shortcutShortLabel için bir değer sağlayın. Diğer tüm değerler isteğe bağlıdır.

android:shortcutId

Bir ShortcutManager nesnesi üzerinde işlemler gerçekleştirildiğinde kısayolu temsil eden bir dize değişmezi.

Not: Bu özelliğin değerini @string/shortcut_id gibi bir kaynak dizesi olarak ayarlayamazsınız.

android:shortcutShortLabel

Kısayolun amacını açıklayan kısa bir ifade. Mümkün olduğunda bu kısa açıklamayı 10 karakterle sınırlayın.

Daha fazla bilgi için setShortLabel() sayfasına bakın.

Not: Bu özelliğin değeri, kaynak dizesi olmalıdır (ör. @string/shortcut_short_label).

android:shortcutLongLabel

Kısayolun amacını açıklayan uzun bir ifade. Yeterli alan varsa başlatıcı, android:shortcutShortLabel yerine bu değeri gösterir. Mümkün olduğunda bu uzun açıklamayı 25 karakterle sınırlayın.

Daha fazla bilgi için setLongLabel() sayfasına bakın.

Not: Bu özelliğin değeri, kaynak dizesi olmalıdır (ör. @string/shortcut_long_label).

android:shortcutDisabledMessage

Kullanıcı devre dışı bırakılmış bir kısayolu başlatmaya çalıştığında desteklenen bir başlatıcıda görünen mesaj. Mesajda, kısayolun neden devre dışı bırakıldığı kullanıcıya açıklanmalıdır. android:enabled true ise bu özelliğin değeri etkisizdir.

Not: Bu özelliğin değeri, kaynak dizesi olmalıdır (ör. @string/shortcut_disabled_message).

android:enabled

Kullanıcının, desteklenen bir başlatıcıdan kısayolla etkileşimde bulunup bulunamayacağını belirler. android:enabled öğesinin varsayılan değeri true'dir. Bu ayarı false olarak ayarlarsanız kısayolu neden devre dışı bıraktığınızı açıklayan bir android:shortcutDisabledMessage belirleyin. Böyle bir mesaj sağlamanız gerekmediğini düşünüyorsanız kısayolu XML dosyasından tamamen kaldırın.

android:icon

Başlatıcının, kısayolu kullanıcıya gösterirken kullandığı bitmap veya uyarlanabilir simge. Bu değer, bir resmin yolu veya resmi içeren kaynak dosyası olabilir. Performansı ve tutarlılığı artırmak için mümkün olduğunda uyarlanabilir simgeler kullanın.

Not: Kısayol simgeleri renk tonu içeremez.

İç öğeleri yapılandırma

Bir uygulamanın statik kısayollarını listeleyen XML dosyası, her <shortcut> öğesinin içinde aşağıdaki öğeleri destekler. Tanımladığınız her statik kısayol için bir intent iç öğesi eklemeniz gerekir.

intent

Kullanıcı kısayolu seçtiğinde sistemin başlattığı işlem. Bu amaç, android:action özelliğinin değerini sağlamalıdır.

Not: Bu intent öğesi, dize kaynaklarını içeremez.

Tek bir kısayol için birden fazla amaç sağlayabilirsiniz. Ayrıntılar için Birden fazla amaç ve etkinliği yönetme, Amaç ayarlama ve TaskStackBuilder sınıfı referansına bakın.

categories

Uygulamanızın kısayollarının gerçekleştirdiği işlem türleri (ör. yeni sohbet mesajları oluşturma) için gruplandırma sağlar.

Desteklenen kısayol kategorilerinin listesi için ShortcutInfo sınıf referansına bakın.

capability-binding

Kısayolla bağlantılı özelliği bildirir.

Önceki örnekte, kısayol CREATE_MESSAGE için beyan edilen bir özelliğe bağlanır. Bu özellik, yerleşik bir Uygulama İşlemleri amacıdır. Bu yetenek bağlama, kullanıcıların kısayol çağırmak için Google Asistan ile sözlü komutlar kullanmasına olanak tanır.

Dinamik kısayollar oluşturma

Dinamik kısayollar, uygulamanızdaki belirli ve bağlama duyarlı işlemlere bağlantılar sağlar. Bu işlemler, uygulamanızın kullanımları arasında ve uygulamanız çalışırken değişebilir. Dinamik kısayollar, belirli bir kişiyi arama, belirli bir konuma gitme ve kullanıcının son kayıt noktasından bir oyunu yükleme gibi işlemler için kullanılabilir. İleti dizisi açmak için dinamik kısayolları da kullanabilirsiniz.

ShortcutManagerCompat Jetpack kitaplığı, uygulamanızdaki dinamik kısayolları yönetmenize olanak tanıyan ShortcutManager API'si için yardımcı bir kitaplıktır. ShortcutManagerCompat kitaplığını kullanmak ortak metin kodunu azaltır ve kısayollarınızın Android sürümlerinde tutarlı bir şekilde çalışmasını sağlar. Bu kitaplık, dinamik kısayolların Google Kısayolları Entegrasyon Kitaplığı ile Asistan gibi Google platformlarında görünmeye uygun olması için de gereklidir.

ShortcutManagerCompat API, uygulamanızın dinamik kısayollarla aşağıdaki işlemleri gerçekleştirmesine olanak tanır:

• Gönderme ve güncelleme: Dinamik kısayollarınızı yayınlamak ve güncellemek için pushDynamicShortcut() simgesini kullanın. Aynı kimliğe sahip dinamik veya sabitlenmiş kısayollar varsa her değiştirilebilir kısayol güncellenir.
• Kaldırma: removeDynamicShortcuts() kullanarak bir grup dinamik kısayolu kaldırın. removeAllDynamicShortcuts() kullanarak tüm dinamik kısayolları kaldırın.

Kısayollarda işlem yapma hakkında daha fazla bilgi için Kısayolları yönetme ve ShortcutManagerCompat referansına bakın.

Dinamik kısayol oluşturma ve bunu uygulamanızla ilişkilendirme örneğini aşağıda bulabilirsiniz:

val shortcut = ShortcutInfoCompat.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

Google Kısayolları Entegrasyon Kitaplığı'nı ekleme

Google Kısayolları Entegrasyon Kitaplığı, isteğe bağlı bir Jetpack kitaplığıdır. Bu API, başlatıcı ve Google platformları gibi Android platformlarında gösterilebilen dinamik kısayolları göndermenize olanak tanır. Bu kitaplığı kullanarak kullanıcıların, uygulamanızdaki belirli içeriklere hızlıca erişmek veya işlemleri tekrar oynatmak için kısayollarınızı keşfetmesine yardımcı olabilirsiniz.

Bu kitaplıkla gönderilen dinamik kısayollar, cihaz başına uygulanan kısayol sınırlarına tabi değildir. Bu sayede, uygulamanızda ilişkili bir işlemi tamamlayan her kullanıcı için kısayol gönderebilirsiniz. Bu şekilde sık sık kısayol göndermek, Google'ın kullanıcınızın kullanım kalıplarını anlamasına ve onlara bağlama uygun kısayollar önermesine olanak tanır.

Örneğin, Asistan, kullanıcının her sabah koştuğunu fitness takip uygulamanızdan gelen kısayollardan öğrenebilir ve kullanıcı sabah telefonunu aldığında proaktif olarak "koşuya başla" kısayolunu önerebilir.

Google Kısayolları Entegrasyon Kitaplığı, kendi içinde herhangi bir adreslenebilir işlev sunmaz. Bu kitaplığı uygulamanıza eklediğinizde Google platformları, ShortcutManagerCompat kullanarak uygulamanızın gönderdiği kısayolları alabilir.

Bu kitaplığı uygulamanızda kullanmak için aşağıdaki adımları uygulayın:

1. gradle.properties dosyanızı AndroidX kitaplıklarını destekleyecek şekilde güncelleyin:

   android.useAndroidX=true
   # Automatically convert third-party libraries to use AndroidX
   android.enableJetifier=true
   

2. app/build.gradle içinde, Google Kısayolları Entegrasyonu Kitaplığı ve ShortcutManagerCompat için bağımlılıklar ekleyin:

   dependencies {
     implementation "androidx.core:core:1.6.0"
     implementation 'androidx.core:core-google-shortcuts:1.0.0'
     ...
   }
   

Android projenize kitaplık bağımlılıkları eklendiğinde uygulamanız, başlatıcıda ve katılan Google yüzeylerinde gösterilmeye uygun dinamik kısayolları göndermek için ShortcutManagerCompat'daki pushDynamicShortcut() yöntemini kullanabilir.

Not: Google Kısayollar Entegrasyon Kitaplığı'nı kullanarak dinamik kısayolları göndermek için pushDynamicShortcut kullanmanızı öneririz. Uygulamanız kısayolları yayınlamak için başka yöntemler kullanabilir ancak bu yöntemler, maksimum kısayol sınırına ulaşılırsa başarısız olabilir.

Sabitlenmiş kısayollar oluşturma

Android 8.0 (API düzeyi 26) ve sonraki sürümlerde sabitlenmiş kısayollar oluşturabilirsiniz. Sabit ve dinamik kısayolların aksine, sabitlenmiş kısayollar desteklenen başlatıcılarda ayrı simgeler olarak görünür. Şekil 1'de bu iki kısayol türü arasındaki fark gösterilmektedir.

Not: Desteklenen bir başlatıcıya kısayol sabitlemeye çalıştığınızda kullanıcı, kısayolu sabitleme iznini isteyen bir onay iletişim kutusu alır. Kullanıcı, kısayolun sabitlenmesine izin vermezse başlatıcı isteği iptal eder.

Uygulamanızı kullanarak desteklenen bir başlatıcıya kısayol sabitlemek için aşağıdaki adımları tamamlayın:

1. Cihazın varsayılan başlatıcısının, kısayolların uygulama içi sabitlenmesini desteklediğini doğrulamak için isRequestPinShortcutSupported() kullanın.

2. Kısayolun mevcut olup olmamasına bağlı olarak iki yöntemden birini kullanarak ShortcutInfo nesnesi oluşturun:

   1. Kısayol varsa yalnızca mevcut kısayolun kimliğini içeren bir ShortcutInfo nesnesi oluşturun. Sistem, kısayolla ilgili diğer tüm bilgileri otomatik olarak bulup sabitler.
   2. Yeni bir kısayol sabitliyorsanız yeni kısayol için kimlik, amaç ve kısa etiket içeren bir ShortcutInfo nesnesi oluşturun.
   Not: Sistem, sabitlenmiş kısayollarda yedekleme ve geri yükleme işlemlerini otomatik olarak gerçekleştirdiğinden bu kısayolların kimlikleri, diğer cihazlarda anlamlı olmayabilecek yerel olarak oluşturulmuş tanımlayıcılar yerine kararlı, sabit dizeler veya sunucu tarafı tanımlayıcılar içermelidir.

3. requestPinShortcut() numarayı arayarak kısayolu cihazın başlatıcısına sabitleyin. Bu işlem sırasında, yalnızca kısayol başarıyla sabitlendiğinde uygulamanızı bilgilendiren bir PendingIntent nesnesi iletebilirsiniz.

   Not: Kullanıcı, kısayolun başlatıcıya sabitlenmesine izin vermezse uygulamanız geri çağırma almaz.

   Bir kısayol sabitlendikten sonra uygulamanız, updateShortcuts() yöntemini kullanarak içeriklerini güncelleyebilir. Daha fazla bilgi için Kısayolları güncelleme başlıklı makaleyi inceleyin.

Aşağıdaki kod snippet'inde, sabitlenmiş kısayolun nasıl oluşturulacağı gösterilmektedir.

Not: ShortcutManager sınıfının örneklerini, ShortcutManager sınıfıyla getSystemService() çağrısı yaparak elde edin.

val shortcutManager = getSystemService<ShortcutManager>()

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

Not: Android 7.1 (API düzeyi 25) ve önceki sürümlerde çalışan Destek Kitaplığı API'lerine isRequestPinShortcutSupported() ve requestPinShortcut() de göz atın. Destek Kitaplığı, sabitleme işlemini denemek için kullanımdan kaldırılan EXTRA_SHORTCUT_INTENT ekstrasına geri döner.

Özel kısayol etkinliği oluşturma

Şekil 2. Özel uygulama kısayolu iletişim kutusu etkinliği örneği.

Ayrıca, kullanıcıların özel seçenekler ve onay düğmesi içeren kısayollar oluşturmasına yardımcı olan özel bir etkinlik de oluşturabilirsiniz. Şekil 2'de, Gmail uygulamasında bu tür bir etkinliğin örneği gösterilmektedir.

Uygulamanızın manifest dosyasında, etkinliğin <intent-filter> öğesine ACTION_CREATE_SHORTCUT ekleyin. Bu bildirim, kullanıcı kısayol oluşturmaya çalıştığında aşağıdaki davranışı ayarlar:

1. Sistem, uygulamanızın özel etkinliğini başlatır.
2. Kullanıcı, kısayolun seçeneklerini belirler.
3. Kullanıcı onay düğmesini seçer.
4. Uygulamanız, createShortcutResultIntent() yöntemini kullanarak kısayol oluşturuyor. Bu yöntem, uygulamanızın setResult() kullanarak daha önce yürütülen etkinliğe geri ilettiği bir Intent döndürür.
5. Uygulamanız, özelleştirilmiş kısayolu oluşturmak için kullanılan etkinlikte finish() işlevini çağırıyor.

Benzer şekilde, uygulamanız yükleme işleminden sonra veya ilk kez başlatıldığında kullanıcıları ana ekrana sabitlenmiş kısayollar eklemeye yönlendirebilir. Bu yöntem, kullanıcılarınızın normal iş akışlarının bir parçası olarak kısayol oluşturmalarına yardımcı olduğundan etkilidir.

Test kısayolları

Uygulamanızın kısayollarını test etmek için uygulamanızı, kısayolları destekleyen bir başlatıcının bulunduğu cihaza yükleyin. Ardından aşağıdaki işlemleri yapın:

• Uygulamanız için tanımladığınız kısayolları görüntülemek üzere uygulamanızın başlatıcı simgesine dokunup basılı tutun.
• Kısayolu sürükleyerek cihazın başlatıcısına sabitleyin.