Kısayol oluşturma

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

Kısayollarla içerik sunma şekliniz, kullanım alanınıza ve kısayol bağlamının uygulama odaklı mı yoksa kullanıcı odaklı mı olduğuna bağlıdır. Statik kısayolun bağlamı değişmezken dinamik kısayolun bağlamı sürekli değişir. Ancak her iki durumda da bağlamı uygulamanız yönetir. Kullanıcının, uygulamanızın kendisine nasıl içerik sunacağını seçtiği durumlarda (ör. sabitlenmiş bir kısayol ile) 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şimde bulunduğu süre boyunca tutarlı bir yapı kullanarak içeriğe bağlantı veren uygulamalar için idealdir. Çoğu başlatıcı aynı anda yalnızca dört kısayol gösterdiğinden statik kısayollar, kullanıcının takvimini veya e-postasını belirli bir şekilde görüntülemek istemesi gibi rutin bir görevi tutarlı bir şekilde gerçekleştirmek için kullanışlıdır.
• Dinamik kısayollar, uygulamalarda 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şlatma sırasında mevcut seviyesinden başlamasına olanak tanıyan bir oyun geliştirirseniz kısayolu sık sık güncellemeniz gerekir. Dinamik kısayol kullanmak, kullanıcı her seviye atladığında kısayolu güncellemenize olanak tanır.
• 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 özel bir işlem gerçekleştirmesine (ör. web sitesine tek adımda gitme) olanak tanıdığı için faydalıdır ve tarayıcının varsayılan ö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 iyi seçenekler arasında gönderilen mesajları görüntüleme, alarm ayarlama ve kullanıcının gün içindeki egzersiz etkinliğini görüntüleme yer alır.

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

1. Uygulamanızın AndroidManifest.xml dosyasında, intent filtreleri android.intent.action.MAIN işlemine 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>
   

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ığı intent'ler dahil olmak üzere statik 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

Özel ö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şlem yaptığında kısayolu temsil eden dize değişmezi.

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.

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ünse bu uzun açıklamayı 25 karakterle sınırlayın.

Daha fazla bilgi için setLongLabel() başlıklı makaleyi inceleyin.

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ğerinin bir etkisi olmaz.

android:enabled

Kullanıcının, desteklenen bir başlatıcıdan kısayolla etkileşimde bulunup bulunamayacağını belirler. android:enabled politikasının varsayılan değeri true olarak ayarlanır. false olarak ayarlarsanız kısayolu neden devre dışı bıraktığınızı açıklayan bir android:shortcutDisabledMessage ayarlayın. Böyle bir mesaj vermeniz 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ığı bit eşlem 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.

İç öğ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 intent, android:action özelliği için bir değer sağlamalıdır.

Tek bir kısayol için birden fazla intent sağlayabilirsiniz. Ayrıntılar için Birden fazla intent ve etkinliği yönetme, Intent 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 bir 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 tanımlanan bir özelliğe bağlıdır. Bu özellik, Uygulama İşlemleri'nin yerleşik bir intent'idir. Bu özellik bağlama, kullanıcıların bir kısayolu ç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ın iyi kullanım alanları arasında belirli bir kişiyi arama, belirli bir konuma gitme ve kullanıcının son kayıt noktasından bir oyun yükleme yer alır. 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 bir yardımcıdır. ShortcutManagerCompat kitaplığını kullanmak, ortak metin kodunu azaltır ve kısayollarınızın Android sürümleri arasında tutarlı bir şekilde çalışmasını sağlar. Bu kitaplık, dinamik kısayolların Google Kısayolları Entegrasyon Kitaplığı ile Google yüzeylerinde (ör. Asistan) görünmeye uygun olması için de gereklidir.

ShortcutManagerCompat API, uygulamanızın dinamik kısayollarla aşağıdaki işlemleri yapmasına olanak tanır:

• Aktarma ve güncelleme: Dinamik kısayollarınızı yayınlamak ve güncellemek için pushDynamicShortcut() 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 dinamik kısayol grubunu kaldırın. removeAllDynamicShortcuts() kullanarak tüm dinamik kısayolları kaldırın.

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

Aşağıda, dinamik kısayol oluşturma ve bunu uygulamanızla ilişkilendirme örneği verilmiştir:

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

Google Kısayolları Entegrasyon Kitaplığı, isteğe bağlı bir Jetpack kitaplığıdır. Başlatıcı gibi Android platformlarında ve Google platformlarında gösterilebilecek dinamik kısayollar eklemenize olanak tanır. Bu kitaplığı kullanmak, 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ı olur.

Bu kitaplıkla gönderilen dinamik kısayollar, cihaz bazında uygulanan kısayol sınırlarına tabi değildir. Bu sayede uygulamanız, kullanıcı uygulamanızda ilişkili bir işlemi her tamamladığında bir kısayol gönderebilir. Sık sık kısayol göndermek, Google'ın kullanıcılarınızın kullanım alışkanlıklarını anlamasını ve onlara bağlamsal olarak alakalı kısayollar önermesini sağlar.

Örneğin Asistan, fitness takip uygulamanızdan gönderilen kısayollardan bir kullanıcının genellikle her sabah koştuğunu öğrenebilir ve kullanıcı sabah telefonunu eline aldığında proaktif olarak "koşu başlat" kısayolunu önerebilir.

Google Shortcuts Integration Library, kendi başına adreslenebilir bir işlev sunmaz. Bu kitaplığı uygulamanıza eklediğinizde Google platformları, uygulamanızın ShortcutManagerCompat kullanarak gönderdiği kısayolları alabilir.

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

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

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ılımcı Google yüzeylerinde gösterilmeye uygun dinamik kısayolları aktarmak için ShortcutManagerCompat sınıfındaki pushDynamicShortcut() yöntemini kullanabilir.

Sabitlenmiş kısayollar oluşturma

Android 8.0 (API düzeyi 26) ve sonraki sürümlerde sabitlenmiş kısayollar oluşturabilirsiniz. Statik 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.

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 sabitlemesini desteklediğini doğrulamak için isRequestPinShortcutSupported() kullanın.

2. Kimlik, intent ve kısayol için kısa bir etiket içeren bir ShortcutInfoCompat nesnesi oluşturun. Kısayol mevcutsa mevcut kısayolun kimliğini kullanın. Sistem, kısayolla ilgili diğer tüm bilgileri otomatik olarak bulur ve sabitler.

3. requestPinShortcut() yöntemini çağırarak 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.

   Bir kısayol sabitlendikten sonra uygulamanız, updateShortcuts() yöntemini kullanarak içeriğini 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

Özel kısayol etkinliği oluşturma

Ayrıca, kullanıcıların kısayol oluşturmasına yardımcı olan, özel seçenekler ve onay düğmesi içeren ö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 beyan, 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 seçeneklerini belirler.
3. Kullanıcı onay düğmesini seçer.
4. Uygulamanız, kısayolu createShortcutResultIntent() yöntemini kullanarak oluşturur. 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() yöntemini çağırır.

Benzer şekilde, uygulamanız kullanıcılardan yükleme işleminden sonra veya uygulama ilk kez başlatıldığında ana ekrana sabitlenmiş kısayollar eklemelerini isteyebilir. 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 bir 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 için uygulamanızın başlatıcı simgesine dokunup basılı tutun.
• Bir kısayolu cihazın başlatıcısına sabitlemek için sürükleyin.