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.
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:
Uygulamanızın manifest dosyasında (
AndroidManifest.xml
), amaç filtreleriandroid.intent.action.MAIN
işlemine veandroid.intent.category.LAUNCHER
kategorisine ayarlanmış bir etkinlik bulun.Activity
içinde hemMAIN
hem deLAUNCHER
için intent filtreleri olan bir<meta-data>
etiketi kullanarakAndroidManifest.xml
içindeshortcuts.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çerencapability
örneğinizin başlatılmasını sağlayan kısayollar oluşturun. Örneğin, fitness uygulamanızdaSTART_EXERCISE
BII özelliğini çağıran "Koşu başlat" uygulama kısayolu tanımlayabilirsiniz.Bu kısayollar
intent
,shortLabel
velongLabel
ö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ıpcapability
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ğininexercise.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şirseshortcutId
kimliği, ham kullanıcı sorgusu değeri yerine amaca iletilir.Entity
kısayollarıintent
,shortLabel
veyalongLabel
ö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> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
Yalnızca ön plan uygulama çağrısı için geçerlidir |
<parameter> |
<intent> |
|
<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 olarakACTION_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>
etiketiintent
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"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
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
: Buintent
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çincontact_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ış sonrakiintent
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ülecekentity
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> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
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
: Bushortcut
öğesinin bağlı olduğucapability
öğesininandroid: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ğicapability
BII parametresinin adı. Örneğin,foodObservation.aboutFood.name
.android:value
:entity
değeri. Bu, tek birentity
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çintargetClass
vetargetPackage
ö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 etiketintent
içinde de tanımlanmışsa<url-template>
verileri bu alanın üzerine yazılır.
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.
Android derin bağlantıları için URL şablonu kullanma
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.