shortcuts.xml dosyası oluştur

Uygulama içi işlevselliğinizi ve buna karşılık gelen yerleşik niyetinizi belirledikten sonra (BII) tanımlayarak işlevlerinizin desteklediği BBI'ları beyan edin. shortcuts.xml kaynak dosyasında capability öğesi. BII beyan etme capability, uygulamanızdaki bu anlamsal niyeti desteklediğini gösterir ve Google Asistan kullanılarak amacın sesli sorguyla yerine getirilmesini sağlar.

Asistan, bir kullanıcıdan parametreleri ayıklamak için doğal dil işlemeyi kullanır emin olun. Yerleşik intents referansı, her bir BII'nin etkinleştirildiği alanları listeler. ilişkilendirilmiş bir kullanıcı sorgusundan çıkarma özelliğine sahip. Örneğin, bir kullanıcı uygulamanızda [actions.intent.GET_FOOD_OBSERVATION][] özelliğini "Ok Google, ExampleApp'e geçen Cuma Öğle Yemeği'nde ne yediğimi sor", Asistan kullanıcı isteğinden aşağıdaki BII parametrelerini ayıklar:

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

Asistan, BII parametrelerini şurada tanımlanan sipariş karşılamaya intent iletir: capability. Bir veya daha fazla intent öğesi, kullanıcının BII'yi çağırmak için kullanabileceği farklı yollara uyum sağlar. Örneğin, intent yukarıdaki örneğe bakın. 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."

gibi belirsiz kullanıcı sorguları için

Genel Bakış

Uygulama İşlemleri'ni, uygulamanıza yerleştirilmiş bir shortcuts.xml dosyası kullanarak yapılandırırsınız projenin res/xml dizinini tarayıp shortcuts.xml için bir referans oluşturma uygulama manifestinizde. Uygulama manifestinize shortcuts.xml referansı ekleyin şu adımları uygulayarak:

  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. AndroidManifest.xml dilinde shortcuts.xml için referans ekleyin: Activity içinde amacı olan <meta-data> etiketi MAIN ve LAUNCHER için filtreleri aşağıdaki gibi görürsünüz:

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

Yukarıdaki örnekte xml/shortcuts.xml dosyası için APK'dır. Kısayolları yapılandırmayla ilgili daha fazla bilgi için bkz. Android geliştirici dokümanlarında statik kısayollar oluşturun.

Jetpack kitaplığı androidx.core:core:1.6.0 Derleme hatalarını önlemek için Android projenizde (veya üzeri) gerekir shortcuts.xml ürününde Uygulama İşlemleri özellikleri tanımlanır. Ayrıntılar için bkz. Android Jetpack'i kullanmaya başlama.

Statik kısayollar

capability öğenizi tanımlarken, statik shortcut öğelerinizi Özelliğin işlevselliğini genişletmek için shortcuts.xml. Statik kısayollar Google Play Console'a bir sürüm yüklediğinizde Asistan tarafından beslenir. 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.

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

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

    Bu kısayollar intent, shortLabel ve longLabel özelliklerini içeriyor. proaktif olarak chip olarak önerilmeye ve yerine getirilmeye uygun olmalarını sağlar. Asistan gibi yüzeylerde veya Android'de bir uygulama simgesine uzun basıldığında başlatıcılar. İşlem kısayolu aynı zamanda bir öğe kısayolu olarak da kullanılabilir ve kullanarak bir capability ile ilişkilendirerek <capability-binding> etiketi.

  • Varlık kısayolları. Varlık kısayolları, capability için sesli sorgu karşılama işleminde desteklenen parametre değerlerinin listesini sağlar. Örneğin, exercise.name BII parametresi START_EXERCISE olanağı sunar. Bir kullanıcının söyledikleri bir varlıkla eşleşirse shortcutId kimliği ham kullanıcı sorgu değeri yerine amaca geçirilir.

    Entity kısayolları intent, shortLabel veya longLabel öğelerini tanımlamaz özellikleridir ve bu nedenle proaktif platformlarda önerilmez. Ayrıntılı bilgi için Uygulama işlemleri için satır içi envanter başlıklı makaleyi inceleyin.

Özellik Şeması

Aşağıdaki tabloda capability öğeleri için Uygulama İşlemleri şeması açıklanmaktadır shortcuts.xml içinde. Bir etiket eklenirken etiketin tüm özellikleri gereklidir yalnızca "isteğe bağlı" olarak işaretlenmemiştir.

Kısayollar.xml etiketi İçinde bulunduğu coğrafi alan: Ö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ı)

<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

Özellik şeması açıklaması

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

<capability>

Uygulamanızın desteklediği uygulama işlemi amacını tanımlayan bir capability. Her biri shortcuts.xml dosyanızdaki <capability> öğesi en az bir öğe sağlamalıdır İşlemin gerçekleştirilmesi için <intent>.

Ö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: belirleyecek olan kişidir. 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.

<niyet>

Kullanıcı sorgusunun nasıl olması gerektiğini tanımlayan Android intent öğesi yerine getirilir. Geliştiriciler birden fazla <intent> sağlayabilir bir capability etiketidir. Asistan, kullanıcı sorgusunu tüm gerekli parametrelerin capability içinde yer aldığı ilk <intent> sağlar.

Ö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.exercise.ExerciseActivity"
  • android:targetPackage: Şunun için hedef Etkinlik sınıfını içeren paket: örnek: "com.example.exercise
  • android:data: <url-template>, bu alanın üzerine yazıldı (bu etiket intent içinde tanımlanmışsa).

<url-şablonu>

Cihazda açılacak bir derin bağlantı URI'si oluşturmak için şablon. Şablon, yerleşik amaçla genişletilebilir parametrelerini parametre olarak ayarlayın. Örneğin, örneklerini görmek için URL şablonları hakkındaki Wikipedia makalesi. İlgili içeriği oluşturmak için kullanılan şablon biçimi, RFC6570 URI şablon spesifikasyonuna uyar.

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 Sipariş karşılamadaki URL şablonları.

<extra>

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.

<parametre>

BII parametrelerini intent parametresi değerleriyle eşler. Daha fazla bilgi için bkz. Parametre verileri ve eşleştirme.

Özellikler:

  • android:name: Bu intent ile ilişkilendirilecek BII parametresinin adı parametresinden sonra bir değer girin. Ad, BII parametresinin yaprak düzeyinde alanı olmalıdır ( örnek, 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'ı (ör. text/*). Bu alanı yalnızca özel amaçların 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ılabilir durumdaysa Asistan, kullanıcı sorgusunu sonraki capability için intent tanımlandı.

<shortcut-fulfillment>

Bir için satır içi envanter kısayolunda tanımlanan bir intent belirtilen parametre sipariş karşılama için kullanılır. Ayrıntılı bilgi için Kısayol niyetlerini kullanarak karşılama başlıklı makaleyi inceleyin.

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

Tek bir BII parametresini satır içi envanterle eşleyen isteğe bağlı özellik kısayol yerine getirme. Ayrıntılı bilgi için Kısayol niyetlerini kullanarak karşılama başlıklı makaleyi inceleyin.

Özellik:

  • android:name: Satır içi envanterle ilişkilendirilecek BII parametresinin adı kısayol yerine getirme. Bu ad, BII'nin yaprak düzeyinde bir alanı olmalıdır. parametresi (örneğin, menuItem.name) ekleyebilirsiniz.

<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 bkz. Uygulama İşlemleri'ni Android Dilimleri ile entegre edin.

Kısayol şeması

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

Kısayollar.xml etiketi İçinde bulunduğu coğrafi alan: Ö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 Enum parametresi eşleştirme için geçerlidir.

Kısayol şeması açıklaması

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

<kısayol>

shortcuts.xml içinde tanımlanmış, belirli özelliklere sahip bir Android <shortcut> Google Trendler'i kullanabilirsiniz. shortcutShortLabel için dize değerleri ve shortcutLongLabel alanlarına APK'nın dize kaynakları.

Özellikler:

  • android:shortcutId: Bu kısayolun tanımlayıcısı.
  • android:shortcutShortLabel: Kısa bir kısayolu temsil eden dize kaynağı kelime öbeğini ekleyin. Örneğin, "Çağrı" değerini temsil eden "@string/callDavidShort" Davut.”
  • android:shortcutLongLabel: Uzun bir kısayolu temsil eden dize kaynağı kelime öbeğini ekleyin. Örneğin, "@string/callDavidLong" " Davut'u ara."

<intent>

Bu kısayolla ilişkili Android amacı. 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 öğe şuraya eklendiğinde: shortcut, Assistant kullanarak sesli karşılama için bu işlevi etkinleştirir.

Özellikler:

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

<parametre-bağlama>

shortcut öğesini bir uygulamanın tek bir parametresiyle ilişkilendiren isteğe bağlı özellik İşlemler capability. shortcut için parameter-binding tanımlanırsa kısayolu, bir BII parametresine satır içi envanter varlığı 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: İlişkilendirilecek capability BII parametresinin adı için bu kısayolu kullanın. Örneğin, exercise.name.
  • android:value: entity değeri. Bu, tek bir entity veya bir kaynak listesidir.

<extra>

extra, kısayolun paket verilerini içerir. sameAs, Uygulama İşlemleri shortcut öğeleriyle alakalı tek veridir. sameAs URL'si bir varlığı açık bir şekilde tanımlayan bir referans web sayfası olmalıdır. Bir intent parametresi türü şunun bir alt türüyse enum değeri: schema.org/Enumeration adresine gidin. Parametre alanları için zorunludur. türleri schema.org/Enumeration alt türleri olan (örneğin: MealTypeBreakfast) ekleyebilirsiniz.

Özellikler:

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

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

Intent karşılama seçenekleri

Asistan'ın nasıl çalıştığını açıklamak için bir <capability> içinde intent öğeleri tanımlarsınız Söz konusu özellikle eşleşen kullanıcının sesli komutlarına yanıt verdiğinde veya bunları yerine getirdiğinde. Orada intent öğesinin bir sipariş karşılama hedefini başlatma şeklini yapılandırmanın birkaç yoludur veya uygulamanızda gezinmenin nasıl yapılandırıldığına bağlı olarak.

Aşağıdaki sipariş karşılama 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: Android derin bağlantılarını kullanarak uygulama hedeflerini tanımlamak intent öğesi içinde bir <url-template> etiketi. Bu yöntemi, uygulamanızda gezinme zaten derin bağlantılara dayanıyorsa yararlı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

Varsayılan olarak Asistan, kullanıcı sorgusundan çıkarılan BII parametrelerini hesabınıza gönderir. uygulaması, capability içinde tanımlanan Android intent extra verileri olarak kullanılır.

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

Amaç Ekstralarını kullanma

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

<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 örneğe göre "Ok Google, şuradan bir latte sipariş et: ÖrnekApp"e ayarlanırsa uygulama, bileşeni çağıran bir intent alır: targetPackage, targetClass. Bileşen, key = "exercise", value = "Running".

Uygulamanız, dinamik parametrelerle uygulamaya bağlı URL'leri işleyebiliyorsa Android oluşturmak için intent içinde bir <url-template> tanımlayabilirsiniz derin bağlantılar üzerinden çalışın. Aşağıdaki örnek bir <url-template> tanımlar:

<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 örneğe göre "Ok Google, latte sipariş et exampleApp"ten), uygulama, oluşturulan URL'yi alır: "myapp://start?exercise=Koşu".

BII parametresini URL'nizdeki bir konumla eşlemek için <parameter> etiketinin android:name özelliği. Bu özellik URL şablonundaki android:key değerine karşılık gelir kullanıcının bilgileri ile değiştirin. android:key değeri bulunmalıdır <url-template> ve süslü ayraçlar ({}) ile eklendi.

Numaralı parametre değerlerini eşleştir

Bazı BII parametreleri, sipariş tamamlama amacınıza listelenmiş değerler sağlar (ör. RECORD_FOOD_OBSERVATION BII'nin desteklenen metin değerleri). Örneğin, bu parametrelerin önüne geçerseniz Asistan, kullanıcının sorgusunu ("Kahvaltı") sameAs değeri, numaralandırma şeması URL'siyle eşleşen varlık (https://schema.googleapis.com/MealTypeBreakfast). Sıralamayı ilişkilendirmek için desteklenen bir entity için değerlerine göre bir sameAs ilişkilendirmesi beyan ederseniz shortcut cihazınız. Aşağıdaki örnekte bir için sameAs ilişkilendirmesi gösterilmektedir satır içi varlık kısayolu:

<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

shortcuts.xml uygulamasında aşağıdaki Uygulama İşlemleri özellikleri kullanılabilir.

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

Bazı BII parametrelerinde öğelere yön vermek için kısayollar kullanılabilir shortcuts.xml içinde belirtilen, desteklenen bir dizi öğeye ayıklama işlemi satır içi envanter. Ayrıntılar için Satır içi envanter bölümüne bakın.

Özel amaçlar

Özel amaçlar, aşağıdaki dillerde özellikleri etkinleştirmek için shortcuts.xml dilinde tanımlanabilir: emin olun. Şu açıdan benzer olsa da: işlevi görmek için, özel amaçlar için iki ek shortcuts.xml özellikleri:

  • app:queryPatterns: sorgu kalıplarından nasıl yararlanabileceğinizi öğrenebilirsiniz.

  • 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 amaçlar başlıklı makaleyi inceleyin.