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:
Uygulamanızın manifest dosyasında (
AndroidManifest.xml
), intent 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 içeren bir<meta-data>
etiketi kullanarakAndroidManifest.xml
'teshortcuts.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çerencapability
örneğini başlatan kısayollar oluşturun. Örneğin, fitness uygulamanızdaSTART_EXERCISE
BII özelliğini çağıran bir "Koşu başlat" uygulama kısayolu tanımlayabilirsiniz.Bu kısayollar
intent
,shortLabel
velongLabel
ö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 bircapability
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ğininexercise.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 yerineshortcutId
kimliği intent'e iletilir.Entity
kısayollarıintent
,shortLabel
veyalongLabel
ö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.
Shortcuts.xml etiketi | İçerdiği | Özellikler |
---|---|---|
<capability> |
<shortcuts> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
Yalnızca ön planda uygulama çağırma için geçerlidir. |
<parameter> |
<intent> |
|
<shortcut-fulfillment> |
<capability> |
Yalnızca satır içi envanter için geçerlidir. |
<parameter> |
<shortcut-fulfillment> |
android:name |
<slice> |
<capability> |
Yalnızca Android Slices için geçerlidir |
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 olarakACTION_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:
Ş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 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
: Buintent
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çincontact_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 sonrakiintent
'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.
Shortcuts.xml etiketi | İçerdiği | Özellikler |
---|---|---|
<shortcut> |
<shortcuts> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
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.
<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ğucapability
öğesininandroid: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ğicapability
BII parametresinin adı. Örneğin,exercise.name
.android:value
:entity
değeri. Bu, tek birentity
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çintargetClass
vetargetPackage
ö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 etiketintent
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.