shortcuts.xml dosyası oluştur

Uygulama içi işlevinizi ve uygulamanız için kullanacağınız ilgili yerleşik niyeti (BII) belirledikten sonra, shortcuts.xml kaynak dosyasında bir capability öğesi tanımlayarak işlevinizin desteklediği BII'leri beyan edin. Bir BII'yi capability olarak tanımlamak, uygulamanızda bu semantik niyet için desteği kaydeder ve Google Asistan'ı kullanarak niyetin sesli sorgu yerine getirilmesini sağlar.

Asistan, kullanıcı sorgusundan parametreleri ayıklamak için doğal dil işleme özelliğini kullanır. Yerleşik intent referansı, her BII'nin ilişkili bir kullanıcı sorgusundan ayıklayabileceği alanları listeler. Örneğin, bir kullanıcı "Ok Google, ExampleApp'e geçen Cuma öğle yemeğinde ne yediğimi sor" diyerek uygulamanızda [actions.intent.GET_FOOD_OBSERVATION][] özelliğini tetiklerse Asistan, kullanıcı isteğinden aşağıdaki BII parametrelerini ayırır:

• foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
• foodObservation.startTime = "2024-09-06T00:00:00"
• foodObservation.endTime = "2024-09-06T23:59:59"

Asistan, BII parametrelerini capability içinde tanımlanan intent yerine getirme işlemine iletir. Bir kullanıcının BII'yi çağırabileceği farklı yöntemleri karşılamak için bir özellikte bir veya daha fazla intent öğesi tanımlanabilir. Örneğin, yukarıdaki örnekte her iki BII parametresini de gerektiren bir karşılama öğesi intent tanımlayabilirsiniz. Ardından, belirli bir gündeki tüm öğünleri bildiren tek bir BII parametresi (foodObservation.forMeal) gerektiren ikinci bir intent tanımlayabilirsiniz. Örneğin, "Ok Google, ExampleApp'e öğle yemeğinde ne yediğimi sor."

Genel Bakış

Uygulama işlemlerini, uygulama projenizin res/xml dizinine yerleştirilen bir shortcuts.xml dosyasını kullanarak yapılandırır ve ardından uygulama manifestinizde shortcuts.xml dosyasına referans oluşturursunuz. Aşağıdaki adımları uygulayarak uygulama manifest dosyanıza shortcuts.xml referansı ekleyin:

1. Uygulamanızın manifest dosyasında (AndroidManifest.xml), intent filtreleri android.intent.action.MAIN işlemine ve android.intent.category.LAUNCHER kategorisine ayarlanmış bir etkinlik bulun.

2. Activity içinde hem MAIN hem de LAUNCHER için intent filtreleri içeren bir <meta-data> etiketi kullanarak AndroidManifest.xml'te shortcuts.xml'e referans ekleyin. Bunu aşağıdaki gibi yapın:

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

Yukarıdaki örnekte, APK'daki xml/shortcuts.xml dosyası için bir XML kaynağı tanımlanmaktadır. Kısayolları yapılandırma hakkında daha fazla bilgi için Android geliştirici dokümanlarındaki Statik kısayollar oluşturma bölümüne bakın.

shortcuts.xml'te uygulama işlemleri özelliklerini tanımlarken derleme hatalarını önlemek için Android projenizde Jetpack kitaplığı androidx.core:core:1.6.0 (veya daha yeni bir sürüm) gereklidir. Ayrıntılar için Android Jetpack'i kullanmaya başlama başlıklı makaleyi inceleyin.

Statik kısayollar

capability'ünüzü tanımlarken, özelliğin işlevini genişletmek için shortcuts.xml içinde statik shortcut öğeleri tanımlayabilirsiniz. Statik kısayollar, Google Play Console'a bir sürüm yüklediğinizde Asistan tarafından alınır. Statik kısayollar yalnızca yeni sürümler oluşturarak oluşturulup güncellenebildiğinden, uygulamanızdaki yaygın etkinlikleri ve içerikleri öne çıkarmak için en kullanışlı yöntemdir.

Statik kısayollarla aşağıdaki uygulama işlemleri işlevini etkinleştirebilirsiniz:

• Özellik kısayolları. Önceden tanımlanmış intent parametre değerleri içeren capability örneğini başlatan kısayollar oluşturun. Örneğin, fitness uygulamanızda START_EXERCISE BII özelliğini çağıran bir "Koşu başlat" uygulama kısayolu tanımlayabilirsiniz.

  Bu kısayollar intent, shortLabel ve longLabel özelliklerini içerir. Bu sayede, Asistan gibi proaktif yüzeylerde veya Android başlatıcılarda bir uygulama simgesine uzun basıldığında çip olarak önerilip yerine getirilebilirler. İşlem kısayolu, <capability-binding> etiketi kullanılarak bir capability ile ilişkilendirilerek aşağıda ayrıntılı olarak açıklanan bir öğe kısayolu olarak da kullanılabilir.

• Öğe kısayolları. Varlık kısayolları, capability için sesli sorgu karşılama işleminde desteklenen parametre değerlerinin listesini sağlar. Örneğin, START_EXERCISE yeteneğinin exercise.name BII parametresine bağlı egzersiz türlerinin ("yürüyüş", "koşu" vb.) listesini içeren bir öğe kısayolu. Bir kullanıcı ifadesi bir öğeyle eşleşirse ham kullanıcı sorgu değeri yerine shortcutId kimliği intent'e iletilir.

  Entity kısayolları intent, shortLabel veya longLabel özelliklerini tanımlamaz. Bu nedenle, proaktif yüzeylerde önerilmez. Ayrıntılı bilgi için Uygulama işlemleri için satır içi envanter başlıklı makaleyi inceleyin.

Yetenek şeması

Aşağıdaki tabloda, shortcuts.xml içindeki capability öğeleri için Uygulama İşlemleri şeması açıklanmaktadır. Bir etiket eklenirken "isteğe bağlı" olarak işaretlenmediği sürece tüm özellikleri zorunludur.

Yetenek şeması açıklaması

Bu bölümde, capability şema öğeleri açıklanmaktadır.

<capability>

Uygulamanızın desteklediği uygulama işlemi intent'ini tanımlayan bir capability. shortcuts.xml dosyanızdaki her <capability> öğesi, işlemin yerine getirilmesini sağlamak için en az bir <intent> sağlamalıdır.

Özellikler:

• android:name: Yerleşik intent Action kimliği (örneğin, [actions.intent.GET_FOOD_OBSERVATION][]). Desteklenen yerleşik intent'lerin listesi için yerleşik intent referansı bölümüne bakın.
• app:queryPatterns: Bu intent için kullanıcıdan beklenen sorguların bulunduğu bir dize dizisi kaynağı. BIIs, kullanıcıların gerçekleştirmeye çalıştıkları görevleri veya aradıkları bilgileri ifade etmelerinin yaygın yollarının modellerini zaten içerdiğinden bu özellik yalnızca özel intent'ler için geçerlidir.

<intent>

Bir kullanıcı sorgusunun uygulama içi işlevler kullanılarak nasıl karşılanması gerektiğini tanımlayan Android intent öğesi. Geliştiriciler, bir capability içinde birden fazla <intent> etiketi sağlayabilir. Asistan, gerekli tüm parametrelerin sağlandığı bir capability içindeki ilk <intent> öğesini kullanarak kullanıcı sorgusunu yerine getirmeye çalışır.

Özellikler:

• android:action: Action türündeki intent. Varsayılan olarak ACTION_VIEW değerine ayarlanır.
• android:targetClass: Hedef etkinlik sınıfı, örneğin: "com.example.exercise.ExerciseActivity"
• android:targetPackage: Hedef Activity sınıfını içeren paket. Örneğin: "com.example.exercise
• android:data: Bu alanın üzerine, intent içinde tanımlanmışsa <url-template> etiketi yazılır.

<url-template>

Cihazda açılacak bir derin bağlantı URI'si oluşturmak için şablon. Şablon için gerekli tüm parametreler mevcutsa şablon, yerleşik intent parametreleriyle genişletilebilir. HTTP URL şablonu örnekleri için URL şablonlarıyla ilgili Wikipedia makalesine bakın. Şablon biçimi, RFC6570 URI şablonu spesifikasyonuna uygundur.

Aşağıda, URL şablonu değerlerine ilişkin bazı örnekler verilmiştir:

URL şablonlarını yapılandırma hakkında daha fazla bilgi için Teslimattaki URL şablonları başlıklı makaleyi inceleyin.

<extra>

Bir intent için ek verileri tanımlar. Uygulama işlemleri için bu alan yalnızca capability için [ön planda uygulama çağırma] özelliğini etkinleştirmek amacıyla kullanılır.

<parameter>

BII parametresini intent parametre değerleriyle eşler. Daha fazla bilgi için Parametre verileri ve eşleştirme başlıklı makaleyi inceleyin.

Özellikler:

• android:name: Bu intent parametreyle ilişkilendirilecek BII parametresinin adı. Ad, BII parametresinin yaprak düzeyinde bir alanı olmalıdır (ör. foodObservation.aboutFood.name).
• android:key: BII parametre değerinin geliştirici tarafından tanımlanan anahtarı. Örneğin, message.recipient.name BII parametresi için contact_name değerini tanımlayabilirsiniz.
• android:mimeType: Parametrenin mimeType değeri (ör. text/*). Bu alan yalnızca özel intent parametreleri için gereklidir.
• android:required: Bu intent'in yerine getirilmek üzere kullanılması için kullanıcı sorgusunun bu parametreyi içermesi gerekip gerekmediğini belirtir. Parametre kullanılamıyorsa Asistan, capability için tanımlanan bir sonraki intent'yi kullanarak kullanıcı sorgusunu yerine getirmeye çalışır.

<shortcut-fulfillment>

Belirli bir parametre için satır içi envanter kısayolunda tanımlanan bir intent'ün, yerine getirme için kullanılacağını belirtir. Ayrıntılar için Kısayol intent'lerini kullanarak sipariş tamamlama başlıklı makaleyi inceleyin.

<parameter> (<shortcut-fulfillment> için)

Tek bir BII parametresini satır içi envanter kısayolu karşılama ile eşleyen isteğe bağlı özellik. Ayrıntılar için Kısayol intent'lerini kullanarak sipariş tamamlama başlıklı makaleyi inceleyin.

Özellik:

• android:name: Satır içi envanter kısayoluyla ilişkilendirilecek BII parametresinin adı. Ad, BII parametresinin yaprak düzeyinde bir alanı olmalıdır (ör. menuItem.name).

<slice>

Asistan'ın, bu capability ile eşleşen bir sorgunun sonucunu Android dilimi olarak yerleştirmesine olanak tanır. Ayrıntılar için Uygulama işlemlerini Android Slice'lerle entegre etme başlıklı makaleyi inceleyin.

Kısayol şeması

Aşağıdaki tabloda, uygulama işlemleri işlevini etkinleştirmek için kullanılan shortcut öğelerinin özellikleri açıklanmaktadır. Bir etiket eklenirken "isteğe bağlı" olarak işaretlenmemişse tüm özellikleri zorunludur.

Kısayol şeması açıklaması

Bu bölümde, shortcut şema öğeleri açıklanmaktadır.

<shortcut>

shortcuts.xml içinde, uygulama işlemleriyle alakalı belirli özelliklerle tanımlanmış bir Android <shortcut>. shortcutShortLabel ve shortcutLongLabel alanlarının dize değerlerine APK'nın dize kaynakları aracılığıyla başvurulur.

Özellikler:

• android:shortcutId: Bu kısayolun tanımlayıcısıdır.
• android:shortcutShortLabel: Kısa bir kısayol ifadesi temsil eden dize kaynağı. Örneğin, "David'i ara" değerini temsil eden "@string/callDavidShort".
• android:shortcutLongLabel: Uzun bir kısayol ifadesi temsil eden dize kaynağı. Örneğin, "Davut'a sesli arama yap" değerini temsil eden "@string/callDavidLong".

<intent>

Bu kısayolla ilişkili Android intent'i. Bu intent, kullanıcı ses veya dokunma kullanarak bu kısayolu başlattığında yürütülür.

shortcut intent özellikleri, capability intent özellikleriyle aynıdır.

<capability-binding>

Bir shortcut'ü bir Uygulama İşlemleri capability ile ilişkilendirir. Bu öğeyi bir shortcut öğesine eklemek, Assistant kullanılarak sesli yerine getirme işleminin yapılmasını sağlar.

Özellikler:

• android:key: shortcut öğesinin bağlı olduğu capability öğesinin android:name özelliği. Örneğin, actions.intent.START_EXERCISE.

<parameter-binding>

Bir shortcut öğesini bir AppActions capability öğesinin tek bir parametresiyle ilişkilendiren isteğe bağlı özellik. Bir shortcut için parameter-binding tanımlanırsa kısayol, BII parametresine satır içi envanter öğesi sağlamak için kullanılabilir. Daha fazla bilgi için Uygulama işlemleri için satır içi envanter başlıklı makaleyi inceleyin.

Özellikler:

• android:key: Bu kısayolun ilişkilendirileceği capability BII parametresinin adı. Örneğin, exercise.name.
• android:value: entity değeri. Bu, tek bir entity veya kaynak listesi olabilir.

<extra>

extra, kısayolun paket verilerini içerir. sameAs, uygulama işlemleri shortcut öğeleriyle alakalı tek veridir. sameAs URL'si, varlığı açık bir şekilde tanımlayan bir referans web sayfasını ifade eder. Intent parametresi türü schema.org/Enumeration alt türüyse ve yalnızca bu durumda bir enum değeri belirtmek için kullanılır. Türleri schema.org/Enumeration alt türleri olan parametre alanları için gereklidir (örneğin: MealTypeBreakfast).

Özellikler:

• android:key: Uygulama işlemleri için desteklenen değer: sameAs
• android:value: sameAs URL değeri

Daha fazla bilgi için Listelenen parametre değerlerini eşleştirme bölümüne bakın.

Intent karşılama seçenekleri

Asistan'ın, bu özellikle eşleşen kullanıcı sesli komutlarına nasıl yanıt verdiğini veya bu komutları nasıl yerine getirdiğini belirtmek için bir <capability> içinde intent öğeleri tanımlarsınız. Uygulama gezinmenizin yapısına bağlı olarak, intent'ün uygulamanızda bir sipariş tamamlama hedefini nasıl başlatacağını yapılandırmanın birkaç yolu vardır.

Aşağıdaki sipariş tamamlama seçenekleri kullanılabilir:

• Açık intent'ler: intent için targetClass ve targetPackage özelliklerini tanımlayarak belirli bir uygulama bileşenini başlatın. Bu, önerilen uygulama işlemi yerine getirme yöntemidir.

• Derin bağlantılar: intent öğesinde bir <url-template> etiketi tanımlayarak Android derin bağlantılarını kullanarak uygulama hedeflerini başlatın. Bu yöntem, uygulama gezinmeniz zaten derin bağlantılara dayanıyorsa kullanışlıdır.

• Intent verileri: intent android:data özelliğinde bir fulfillment URI sağlayabilirsiniz. Bu etiket intent içinde de tanımlanmışsa bu alanın üzerine <url-template> verileri yazılır.

Parametre verileri ve eşleştirme

Asistan, varsayılan olarak kullanıcı sorgusundan ayıklanan BII parametrelerini capability içinde tanımlanan Android intent extra verileri olarak uygulamanıza gönderir.

Alternatif olarak, capability içinde dinamik parametreler için yer tutucuları içeren bir <url-template> etiketi de tanımlayabilirsiniz. Bu şablon, uygulama bağlantıları URL'si, özel şema veya intent tabanlı URL kullanarak Android etkinliklerinizden biriyle eşlenir.

Amaç ekstralarını kullanma

Aşağıdaki örnekte, capability karşılaması için tanımlanmış açık bir intent gösterilmektedir:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Yukarıdaki örnekte, "Ok Google, koşu antrenmanımı başlat" gibi bir kullanıcı sorgusu için uygulama, targetPackage, targetClass bileşenini çağıran bir intent alır. Bileşen, key = "exercise", value = "Running" ile bir Ekstra alır.

Android derin bağlantıları için URL şablonu kullanma

Uygulamanız, dinamik parametrelerle uygulamaya bağlı URL'leri zaten işleyebiliyorsa sipariş tamamlama için Android derin bağlantıları oluşturmak üzere intent içinde bir <url-template> tanımlayabilirsiniz. Aşağıdaki örnekte bir <url-template> tanımlanmaktadır:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

Yukarıdaki örnekte, "Ok Google, koşu antrenmanımı başlat" gibi bir kullanıcı sorgusu için uygulama, oluşturulan URL'yi alır: "uygulamam://start?exercise=Running".

BII parametresini URL'nizdeki bir konumla eşlemek için <parameter> etiketinin android:name özelliğini kullanırsınız. Bu özellik, URL şablonundaki android:key değerine karşılık gelir. Bu değeri, kullanıcıdan gelen bilgilerle değiştirmek istersiniz. android:key değeri, <url-template> içinde yer almalı ve kıvrık ayraçlar ({}) içine alınmalıdır.

Listelenen parametre değerlerini eşleştirme

Bazı BII parametreleri, sipariş tamamlama amacınıza listelenmiş değerler sağlar (ör. RECORD_FOOD_OBSERVATION BII'nin desteklenen metin değerleri). Bu parametreler için Asistan, kullanıcının sorgusunu ("Kahvaltı") sameAs değeri enum şeması URL'siyle (https://schema.googleapis.com/MealTypeBreakfast) eşleşen bir öğeyle eşleştirir. Desteklenen bir entity için enum değerlerini ilişkilendirmek üzere shortcut öğeniz içinde bir sameAs ilişkisi tanımlarsınız. Aşağıdaki örnekte, satır içi öğe kısayolu için bir sameAs ilişkisi gösterilmektedir:

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

Yukarıdaki örnekte, RECORD_FOOD_OBSERVATION özelliği "kahvaltı" yemek türü için bir eşleşme tetiklerse intent karşılama ile birlikte aşağıdaki ek gönderilir:

• key = "for_meal"
• value = "meal_breakfast"

Özellikler

Aşağıdaki Uygulama İşlemleri özellikleri shortcuts.xml'te kullanılabilir.

Uygulama İşlemleri için satır içi envanter

Bazı BII parametreleri için, varlık çıkarma işlemini shortcuts.xml içinde belirtilen ve satır içi envanter olarak bilinen bir dizi desteklenen öğeye yönlendirmek üzere kısayollar kullanılabilir. Ayrıntılı bilgi için Satır içi envanter başlıklı makaleyi inceleyin.

Özel amaçlar

Uygulamanızda mevcut BIIs ile eşleşmeyen özellikleri sesli olarak etkinleştirmek için shortcuts.xml'te özel intent'ler tanımlanabilir. BII tanımına işlevsel olarak benzer olsa da özel intent'ler shortcuts.xml içinde iki ek özellik gerektirir:

• app:queryPatterns: Özel amaç için farklı sorgu kalıplarını açıklayan dizi kaynağı.

• android:mimeType: Özel amacın parametre türü. Bu alan, parametre türünün bilindiği BI'ler için gerekli değildir. Özel intent parametreleri için desteklenen bir semantik tür belirtilmelidir.

Daha fazla bilgi için Özel intent'ler başlıklı makaleyi inceleyin.