shortcuts.xml dosyası oluştur

Uygulama içi işlevinizi ve uygulanacak ilgili yerleşik amacı (BII) belirledikten sonra, shortcuts.xml kaynak dosyasında bir capability öğesi tanımlayarak işlevinizin desteklediği BBI'leri bildirin. BII'yi capability olarak tanımlamak, uygulamanızdaki bu anlamsal amaca yönelik desteği kaydeder ve amacın Google Asistan kullanılarak sesli sorgu yerine getirilmesini sağlar.

Asistan, kullanıcı sorgusundan parametreleri çıkarmak için doğal dil işlemeyi kullanır. Yerleşik intents referansı, her BII'nin ilişkili bir kullanıcı sorgusundan ayıklayabileceği alanları listeler. Örneğin, bir kullanıcı "Ok Google, Ornek Uygulama'da Ornek Cafe'den pizza sipariş edin" diyerek uygulamanızdaki actions.intent.ORDER_MENU_ITEM özelliğini çağırırsa Asistan, aşağıdaki BII parametrelerini kullanıcı isteğinden çıkarır:

  • menuItem.name = "pizza"
  • menuItem.inMenuSection.inMenu.forRestaurant.name = "ExampleCafe"

Asistan, BII parametrelerini capability içinde tanımlanan intent istek karşılamaya iletir. Kullanıcının BII'yi çağırabileceği farklı yöntemlere uygun bir şekilde bir veya daha fazla intent öğesi tanımlanabilir. Örneğin, yukarıdaki örnekte her iki BII parametresini gerektiren bir karşılama intent tanımlayabilirsiniz. Daha sonra, kullanıcı "Ok Google, ExampleApp'te pizza sipariş et" gibi daha basit bir istekte bulunursa tek bir BII parametresi (menuItem.name) gerektiren ikinci bir amaç tanımlayabilirsiniz.

gibi belirsiz kullanıcı sorguları için bile işlemlerin başarılı olmasını sağlayarak kullanıcı deneyimini iyileştirir.

Genel bakış

Uygulama İşlemleri'ni, uygulama projenizin res/xml dizinine yerleştirilen bir shortcuts.xml dosyası kullanarak ve daha sonra uygulama manifestinizde shortcuts.xml referansı oluşturarak yapılandırırsınız. Aşağıdaki adımları uygulayarak uygulama manifestinizde shortcuts.xml için bir referans ekleyin:

  1. Uygulamanızın manifest dosyasında (AndroidManifest.xml), amaç 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 olan bir <meta-data> etiketi kullanarak AndroidManifest.xml içinde shortcuts.xml öğesine aşağıdaki şekilde bir referans ekleyin:

    <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ırmayla ilgili daha fazla ayrıntı için Android geliştirici dokümanındaki Statik kısayollar oluşturma bölümüne bakın.

shortcuts.xml ürününde Uygulama İşlemleri özelliklerini tanımlarken derleme hatalarını önlemek için Android projenizde Jetpack kitaplığı androidx.core:core:1.6.0 (veya üzeri) gerekir. Ayrıntılı bilgi için Android Jetpack'i kullanmaya başlama başlıklı makaleye bakın.

Statik kısayollar

capability özelliğini tanımlarken, işlevin işlevselliğini genişletmek için shortcuts.xml içinde statik shortcut öğeleri tanımlayabilirsiniz. Google Play Console'a bir sürüm yüklediğinizde Asistan tarafından statik kısayollar kullanılır. Statik kısayollar, yalnızca yeni sürümler oluşturarak oluşturulabildiğinden ve güncellenebileceğinden, en çok uygulamanızdaki ortak etkinlikleri ve içeriği vurgulamak için yararlıdır.

Statik kısayollarla aşağıdaki Uygulama İşlemleri işlevlerini etkinleştirebilirsiniz:

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

    Bu kısayollar intent, shortLabel ve longLabel özellikleri içerdiğinden, Asistan gibi proaktif yüzeylerde veya Android başlatıcılarda uygulama simgesine uzun basıldığında önerilmeye ve çip olarak yerine getirilmeye uygun hale gelir. İşlem kısayolu, aşağıda açıklandığı gibi, <capability-binding> etiketi kullanıp capability ile ilişkilendirerek varlık kısayolu işlevi de görebilir.

  • Varlık kısayolları. Varlık kısayolları, bir capability öğesinin sesli sorgu karşılaması için desteklenen parametre değerlerinin listesini sağlar. Örneğin, START_EXERCISE yeteneğinin exercise.name BII parametresine bağlı bir egzersiz türleri listesi ("yürüyüş", "koşu" vb.) içeren bir varlık kısayolu. Bir kullanıcının sözü bir varlıkla eşleşirse shortcutId kimliği, ham kullanıcı sorgusu değeri yerine amaca iletilir.

    Entity kısayolları intent, shortLabel veya longLabel özelliklerini tanımlamadığından proaktif yüzeylerde bu nedenle önerilmez. Ayrıntılar için Uygulama İşlemleri için satır içi envanter bölümüne bakın.

Özellikler Şeması

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

Shortcuts.xml etiketi Bulunduğu yer Özellikler
<capability> <shortcuts>

android:name

app:queryPatterns (yalnızca özel amaçlar için geçerlidir)

<intent> <capability>

android:action (isteğe bağlı)

android:targetClass (isteğe bağlı)

android:targetPackage (isteğe bağlı)

android:data (isteğe bağlı)

<url-template> <intent>

android:value

<extra> <intent>

android:key

android:value

Yalnızca ön plan uygulama çağrısı için geçerlidir

<parameter> <intent>

android:name

android:key

android:mimeType (yalnızca özel amaçlar için geçerlidir)

android:required (isteğe bağlı)

app:shortcutMatchRequired (isteğe bağlı)

<data> <parameter> android:pathPattern (yalnızca web envanteri için geçerlidir)
<shortcut-fulfillment> <capability> Yalnızca satır içi envanter için geçerlidir
<parameter> <shortcut-fulfillment> android:name
<slice> <capability>

Yalnızca Android Dilimleri için geçerlidir

Özellikler şeması açıklaması

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

<özellik>

Uygulamanızın desteklediği Uygulama İşlemi amacını tanımlayan bir capability. shortcuts.xml dosyanızdaki her <capability> öğesi, işlemin yerine getirilmesi için en az bir <intent> sağlamalıdır.

Özellikler:

  • android:name: Yerleşik amaç İşlem Kimliği (örneğin, actions.intent.CREATE_TAXI_RESERVATION). Desteklenen yerleşik amaçların listesi için yerleşik amaç referansına bakın.
  • app:queryPatterns: Bu amaç için kullanıcıdan beklenen sorguların dize dizisi kaynağı. BIS'ler, kullanıcıların yapmaya çalıştıkları görevleri veya aradıkları bilgileri ifade etme yöntemlerinin yaygın modellerini içerdiğinden, bu özellik yalnızca özel amaçlar için geçerlidir.

<niyet>

Kullanıcı sorgusunun uygulama içi işlev 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 karşılamaya çalışır.

Özellikler:

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

<url-şablonu>

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

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

Şablon Değerler Genişletilmiş değer
https://example.com/test{?foo,bar} "foo": "123"

"bar": "456"

https://example.com/test?foo=123&bar=456
https://example.com/test?utm_campaign=appactions{&foo,bar} "foo": "123"

"bar": "456"

https://example.com/test?utm_campaign=appactions&foo=123&bar=456
https://example.com/test?utm_campaign=appactions{#foo} "foo": "123" https://example.com/test?utm_campaign=appactions#foo=123
myapp://example/{foo} "foo": "123" myapp://example/123

URL şablonlarını yapılandırma hakkında daha fazla bilgi için Karşılamadaki URL şablonları bölümüne bakın.

<extra>

intent için ekstra veri tanımlar. Uygulama İşlemleri'nde bu alan yalnızca bir capability için ön plan uygulama çağrısını etkinleştirmek amacıyla kullanılır.

<parametre>

Amaç parametresi değerlerine bir BII parametresini eşler. Daha fazla bilgi için Parametre verileri ve eşleştirme bölümünü inceleyin.

Özellikler:

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

<veriler>

Web envanterini parameter ile ilişkilendirir.

Özellik:

  • android:pathPattern: Web-envanter kullanılarak döndürülecek entity URL için URL kalıbı. Bu özellik iki joker karakteri destekler:

    • *: Yıldız işareti, hemen öncesindeki karakterin sıfır veya daha fazla tekrarından oluşan bir diziyle eşleşir.

    • .*: Ardından yıldız işareti gelen bir nokta, sıfır veya daha fazla karakterden oluşan herhangi bir diziyle eşleşir.

    • Çıkış karakterleri yalnızca * ve \ için gereklidir. Bunlar için sırasıyla \\* ve \\\\ olarak çıkış yapabilirsiniz.

<shortcut-fulfillment>

Belirli bir parametre için satır içi envanter kısayolunda tanımlanan bir intent öğesinin istek karşılama için kullanılacağını belirtir. Ayrıntılar için Kısayol amaçları kullanarak istek karşılama bölümüne bakın.

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

Satır içi envanter kısayolu yerine tek bir BII parametresini eşleyen isteğe bağlı özellik. Ayrıntılar için Kısayol amaçları kullanarak istek karşılama bölümüne bakın.

Özellik:

  • android:name: Satır içi envanter kısayollarının karşılanmasıyla ilişkilendirilecek BII parametresinin adı. Ad, BII parametresinin yaprak düzeyinde bir alanı olmalıdır (örneğin, menuItem.name).

<dilim>

Asistan'ın bu capability ile eşleşen bir sorgunun sonucunu Android Dilimi olarak yerleştirmesini sağlar. Ayrıntılar için Uygulama İşlemlerini Android Dilimleriyle Entegre Etme bölümüne bakın.

Kısayol şeması

Aşağıdaki tabloda, Uygulama İşlemleri işlevini etkinleştirmek için kullanılan shortcut öğelerinin özellikleri açıklanmaktadır. Bir etiket eklerken, "isteğe bağlı" olarak işaretlenmediği sürece etiketin tüm özellikleri gereklidir.

Shortcuts.xml etiketi Bulunduğu yer Özellikler
<shortcut> <shortcuts>

android:shortcutId

android:shortcutShortLabel

android:shortcutLongLabel (isteğe bağlı)

android:icon (isteğe bağlı)

<intent> <shortcut>

android:action

android:targetClass (isteğe bağlı)

android:targetPackage (isteğe bağlı)

android:data (isteğe bağlı)

<capability-binding> <shortcut>

android:key

<parameter-binding> <capability-binding>

android:key (isteğe bağlı)

android:value

<extra> <shortcut>

android:name (isteğe bağlı)

android:value

Yalnızca Sıralama parametresi eşleşmesi için geçerlidir.

Kısayol şeması açıklaması

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

<kısayol>

Uygulama İşlemleri ile alakalı belirli özelliklere sahip, shortcuts.xml politikasında 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ı.
  • android:shortcutShortLabel: Kısa bir kısayol ifadesini temsil eden dize kaynağı. Örneğin, "Cemal'i ara" değerini temsil eden "@string/callDavidShort".
  • android:shortcutLongLabel: Uzun bir kısayol ifadesini temsil eden dize kaynağı. Örneğin, "Davut'a sesli arama yap" değerini temsil eden "@string/callDavidLong".

<niyet>

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

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

<özellik-bağlama>

shortcut öğesini, uygulama işlemleri capability ile ilişkilendirir. Bu öğe bir shortcut öğesine eklendiğinde Assistant kullanılarak sesli istek karşılama sağlanır.

Özellikler:

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

<parametre bağlama>

Bir shortcut öğesini bir Uygulama İşlemleri capability öğesinin tek bir parametresiyle ilişkilendiren isteğe bağlı özellik. shortcut için bir parameter-binding tanımlanırsa kısayol, bir BII parametresine satır içi envanter varlığı sağlamak için kullanılabilir. Daha fazla bilgiyi Uygulama İşlemleri için satır içi envanter bölümünde bulabilirsiniz.

Özellikler:

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

<extra>

Kısayol için extra paket verileri. sameAs, Uygulama İşlemleri shortcut öğeleriyle ilgili tek veridir. sameAs URL'si, varlığı açık bir şekilde tanımlayan bir referans web sayfasını ifade eder. Yalnızca intent parametresi türü schema.org/Enumeration alt türüyse bir numaralandırma 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 İşlemleri için desteklenen değer: sameAs
  • android:value: sameAs URL değeri

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

Amaç yerine getirme seçenekleri

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

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

  • Açık amaçlar: intent için targetClass ve targetPackage özelliklerini tanımlayarak belirli bir uygulama bileşenini başlatın. Uygulama İşlemleri karşılama yöntemi önerilen seçenektir.

  • Derin bağlantılar: intent öğesi içinde bir <url-template> etiketi tanımlayarak Android derin bağlantılarını kullanarak uygulama hedeflerini başlatın. Uygulamada gezinme süreciniz halihazırda derin bağlantılara dayanıyorsa bu yöntem yararlıdır.

  • Amaç verileri: intent android:data özelliğinde bir karşılama URI'si sağlayabilirsiniz. Söz konusu etiket intent içinde de tanımlanmışsa <url-template> verileri bu alanın üzerine yazılır.

tanımlamanız gerekmez.

Parametre verileri ve eşleştirme

Varsayılan olarak Asistan, kullanıcı sorgusundan çıkarılan BII parametrelerini uygulamanıza capability içinde tanımlanan extra Android intent verisi olarak gönderir.

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

Amaç Ekstraları'nı kullanma

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

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

Yukarıdaki örneğe göre, "Ok Google, ÖrnekUygulama'dan latte sipariş et" gibi bir kullanıcı sorgusu için uygulama, bu bileşeni çağıran bir intent alır: targetPackage, targetClass. Bileşen, key = ”menu”, value = ”latte” ile bir Ekstra alır.

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

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent>
    <url-template android:value="myapp://order{?menu}" />
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

Yukarıdaki örneğe göre, "Ok Google, ExampleApp'ten latte sipariş et" gibi bir kullanıcı sorgusu için uygulama, oluşturulan URL'yi alır: "myapp://order?menu=latte".

BII parametresini URL'nizdeki bir konuma eşlemek için <parameter> etiketinin android:name özelliğini kullanın. Bu özellik, URL şablonundaki, kullanıcıdan alınan bilgilerle değiştirmek istediğiniz android:key değerine karşılık gelir. android:key değeri <url-template> içinde mevcut olmalı ve süslü ayraçlar ({}) içine alınmalıdır.

Numaralanmış parametre değerlerini eşleştirin

Bazı BII parametreleri, istek karşılama amacınıza numaralanmış değerler sağlar (ör. RECORD_FOOD_OBSERVATION BII'nin desteklenen metin değerleri). Asistan, bu parametreler için kullanıcının sorgusunu ("Kahvaltı") sameAs değeri enum şema URL'si (https://schema.googleapis.com/MealTypeBreakfast) ile eşleşen bir varlıkla eşleştirir. Desteklenen bir entity için enum değerlerini ilişkilendirmek üzere shortcut dosyanızda sameAs ilişkilendirmesi tanımlarsınız. Aşağıdaki örnekte, satır içi varlık kısayolu için bir sameAs ilişkilendirmesi 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şmeyi tetiklerse intent karşılamasıyla birlikte aşağıdaki Ekstra gönderilir:

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

Özellikler

shortcuts.xml sürümünde aşağıdaki Uygulama İşlemleri özellikleri kullanılabilir.

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

Bazı BII parametrelerinde, varlık çıkarmayı shortcuts.xml politikasında belirtilen ve satır içi envanter olarak bilinen desteklenen bir grup öğeye yönlendirmek için kısayollar kullanılabilir. Ayrıntılar için Satır içi envanter bölümüne bakın.

Uygulama İşlemleri için web envanteri

Bazı BBI'lerde istek karşılama için URL oluşturma yöntemi olarak web envanterini kullanabilirsiniz. Web envanteri, Uygulama İşlemi karşılama URL'lerini keşfetmek için web sitenizi kullanır. Bu özellik, web'de güçlü bir şekilde görünürseniz ve uygulama içi derin bağlantılarınız herkese açık web içeriğine göre düzenlendiğinde faydalı olur.

Ayrıntılar için Web envanteri konusuna bakın.

Özel amaçlar

Özel amaçlar, uygulamanızda kullanılabilen BII'lerle eşleşmeyen özellikleri sesli olarak etkinleştirmek için shortcuts.xml içinde tanımlanabilir. İşlevsellik açısından BII tanımına benzer olsa da özel amaçlar için shortcuts.xml ürününde iki ek özellik gerekir:

  • app:queryPatterns: Özel bir amaç için farklı sorgu kalıpları bildiren dizi kaynağı.

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

Daha ayrıntılı bilgi için Özel amaçlar bölümüne bakın.