Kısayol oluşturma

Kısayollar, kullanıcıların uygulamanızın bölümlerine hızlı bir şekilde 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ğlantı veren uygulamalar için en uygun seçenektir. Çoğu başlatıcı aynı anda yalnızca dört kısayol 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, uygulamalardaki bağlama duyarlı 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ı her seviyeyi 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 özellik, kullanıcının özel bir işlem (ör. web sitesine tek adımda gitme) yapmasına olanak tanıdığı için faydalıdır. Bu işlem, tarayıcının varsayılan bir örneğini kullanmaktan daha hızlıdır.

Statik kısayollar oluşturma

Statik kısayollar, uygulamanızdaki genel işlemlere bağlantılar sağlar ve 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 gönderilen mesajları görüntüleme, alarm ayarlama ve kullanıcının o günkü egzersiz etkinliğini gösterme gibi seçenekler uygundur.

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 dosyaya 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 activity-alias içinde 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 uygulamada 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>
   shortcuts.xml

Ö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 girin. 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, kaynak dizesi olarak ayarlayamazsınız. Örneğin, @string/shortcut_id.

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() başlıklı makaleyi inceleyin.

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() başlıklı makaleyi inceleyin.

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 değeri 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şime girip giremeyeceğini belirler. android:enabled politikasının varsayılan değeri true'dır. 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ç belirleme 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ğlıdır. Bu, uygulama işlemleri yerleşik niyetidir. 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 bağlama duyarlı belirli 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 durumlarda kullanılabilir. Bir görüşmeyi 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, standart kodu 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 yüzeylerinde 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ını inceleyin.

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)
ShortcutsSnippets.kt

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

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ız, kullanıcılar uygulamanızda ilişkili bir işlemi her tamamladığında kısayol gönderebilir. Bu şekilde sık sık kısayol göndermek, Google'ın kullanıcınızın kullanım alışkanlıkları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ı, uygulamanızın ShortcutManagerCompat kullanarak gönderdiği kısayolları kullanabilir.

Bu kitaplığı uygulamanızda kullanmak için ShortcutManagerCompat ve Google Kısayolları Entegrasyon Kitaplığı'nın bağımlılıklarını app/build.gradle veya app/build.gradle.kts dosyanıza ekleyin:

Not: Bu kitaplıkların en son sürümleri için AndroidX Core releases sayfasına bakın.

Kotlin

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

Modern

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

Android projenize eklenen kitaplık bağımlılıkları sayesinde uygulamanız, başlatıcıda ve katılan Google yüzeylerinde gösterilmeye uygun dinamik kısayolları göndermek için ShortcutManagerCompat'taki 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. Kimlik, amaç ve kısayol için kısa bir etiket içeren ShortcutInfoCompat nesnesi oluşturun. Kısayol varsa mevcut kısayolun kimliğini kullanın. Sistem, kısayolla ilgili diğer tüm bilgileri otomatik olarak bulup sabitler.

   Not: ShortcutInfoCompat.Builder, kısa bir etiket ve amaç gerektirir. Ayrıca, mevcut bir kısayolun kimliğini kullandığınızda da bu gereklilik geçerlidir. Bunları ayarlamazsanız build(), IllegalArgumentException hatası verir.
   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()'ı 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:

if (ShortcutManagerCompat.isRequestPinShortcutSupported(context)) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfoCompat.Builder(context, "my-shortcut")
        .setShortLabel("Website")
        .setIntent(
            Intent(
                Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")
            )
        )
        .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 =
        ShortcutManagerCompat.createShortcutResultIntent(context, 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 */ PendingIntent.FLAG_IMMUTABLE
    )

    ShortcutManagerCompat.requestPinShortcut(
        context,
        pinShortcutInfo,
        successCallback.intentSender
    )
}
ShortcutsSnippets.kt

Not: Android 7.1 (API düzeyi 25) ve önceki sürümlerde, ShortcutManagerCompat, sabitleme işlemini denemek için kullanımdan kaldırılmış 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ısayol için seçenekleri 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şturmasına yardımcı olduğu için etkilidir.

Kısayolları test etme

Uygulamanızın kısayollarını test etmek için uygulamanızı, kısayolları destekleyen bir başlatıcıya sahip 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.