1. Genel Bakış
Uygulama İşlemleri ile Google Asistan'ı kullanarak doğrudan uygulama özelliklerine geçebilir ve sesinizi kullanarak görevleri tamamlayabilirsiniz. Bir Android geliştiricisi olarak, Uygulama İşlemleri eklemek için özellik öğeleri uyguluyorsunuz. Özellikler, kullanıcının sesli isteklerini hangi uygulama özelliklerinin desteklediğini ve bu isteklerin nasıl karşılanacağını Asistan'a bildirir.
Bu codelab'de, Uygulama İşlemleri ile uygulama geliştirme hakkında yeni başlayanlar için kavramlar ele alınmaktadır. Bu codelab'i uygulamak için daha önce Android uygulamaları ve Android amaçları geliştirme konusunda deneyiminiz olmalıdır. Android'de yeniyseniz Android geliştiricileriyle ilgili temel bilgiler için kod laboratuvarlarından birini tercih edebilirsiniz.
Neler oluşturacaksınız?
Bu codelab'de, örnek bir fitness Android uygulamasına iki yerleşik uygulama işlemi (BII) ekleyeceksiniz. Böylece, kullanıcılar seslerini kullanarak egzersiz zamanlayıcısı başlatıp durdurabilir.
Neler öğreneceksiniz?
Asistan'ı bir Android uygulamasını da kapsayacak şekilde genişletmek için Sağlık ve Fitness kategorisindeki BBI'leri nasıl kullanacağınızı öğreneceksiniz. Ayrıca, BBI'lerinizi test etmek amacıyla Android Studio için Google Asistan eklentisini kullanmayı da öğreneceksiniz.
Ön koşullar
Devam etmeden önce ortamınızda aşağıdaki araçların bulunduğundan emin olun:
- git yüklü kabuk komutlarını çalıştırmak için kullanılan bir terminal.
- Android Studio'nun en son sürümüne sahip olmalısınız.
- [Google Play Console][]'a erişimi olan bir Google Hesabı[]
- Play Store'a internet erişimi olan fiziksel veya sanal bir Android cihaz.
Devam etmeden önce, Android Studio'da ve test cihazınızdaki Google uygulamasında aynı Google Hesabı'nın oturum açtığından emin olun.
2. İşleyiş şeklini anlayın
Uygulama İşlemleri, Google Asistan'dan kullanıcıları Android uygulamanıza bağlar. İşleyiş şekli nasıldır?
Kullanıcı, uygulamanızı kullanarak Asistan'dan bir görev gerçekleştirmesini istediğinde, Asistan kullanıcının sorgusunu uygulamanızın shortcuts.xml
XML kaynağında tanımlanan bir Uygulama İşlemleri capability
ile eşleştirir.
Şekil 1. Asistan'ın, Uygulama İşlemleri sesli sorgusunu nasıl işlediğini gösteren bir akış şeması.
Her özellik öğesi şunları tanımlar:
- Amaç: Özelliği tetiklemesi gereken Uygulama İşlemleri sesli amacı.
- Bir veya daha fazla sipariş karşılama: Asistan'ın uygulamayı başlatmak ve kullanıcının sesli isteğini yerine getirmek için oluşturduğu amaçları veya derin bağlantıları. Sipariş karşılama tanımları, kullanıcı sorgusundan hangi parametrelerin beklendiğini ve bu parametrelerin lansman talimatlarına nasıl kodlanması gerektiğini belirtir.
Niyetler
Natural Language Understanding'te (NLU) amaç, benzer anlamlara sahip kullanıcı ifadeleri grubudur. Google tarafından pek çok "yerleşik" amaca göre (BII'ler), uygulama işlemleri ile kullanılabilen çok çeşitli istek türlerini kapsar. Örneğin, Asistan "Pizza siparişi ver" veya "tatlı menüsünü göster" ifadelerini ORDER_MENU_ITEM
BII ile ilişkilendirecek şekilde eğitilmiştir. Uygulama İşlemleri ile bu BBI'lerden yararlanarak yaygın olarak yapılan sesli istekleri hızlıca uygulama işlevselliğine genişletebilirsiniz.
İstek karşılama
Bir kullanıcı isteği shortcuts.xml
ürününde bir Uygulama İşlemini tetiklediğinde Android etkinliğinizin gelen Android amacını veya derin bağlantıyı algılayıp işlemesi ve kullanıcıya istediği işlevi sağlaması gerekir. Sonuçta Asistan'ın kullanıcının sorgusuna yanıt olarak uygulamanızı çağırdığı, ses odaklı bir kullanıcı deneyimi elde edilir.
3. Geliştirme ortamınızı hazırlama
Bu codelab'de, Android için Fitness örnek uygulaması kullanılır. Bu uygulama, kullanıcıların egzersiz zamanlayıcısı başlatıp durdurmasına ve egzersiz rutinleriyle ilgili istatistikleri görüntülemesine olanak tanır.
Temel dosyalarınızı indirme
Bu codelab'in temel dosyalarını almak için aşağıdaki komutu çalıştırarak GitHub deposunu klonlayın:
git clone --branch codelab-start https://github.com/actions-on-google/appactions-fitness-kotlin.git
Kod deposunu klonladıktan sonra Android Studio'da açın:
- Android Studio'ya hoş geldiniz iletişim kutusunda Projeyi içe aktar'ı tıklayın.
- Depoyu klonladığınız klasörü bulup seçin.
Android uygulama kimliğini güncelleme
Uygulamanın uygulama kimliğini güncellemek, test cihazınızda uygulamayı benzersiz bir şekilde tanımlar ve "Yinelenen paket adı"nı önler hatası oluşur. Uygulama kimliğini güncellemek için app/build.gradle
dosyasını açın:
android {
...
defaultConfig {
applicationId "com.MYUNIQUENAME.android.fitactions"
...
}
}
Değiştir: "MYUNIQUENAME" applicationId
alanına bunu benzersiz bir şekilde ekleyebilirsiniz.
Cihazınızda uygulamayı deneyin
Uygulamanın kodunda başka değişiklikler yapmadan önce, örnek uygulamanın neler yapabileceği hakkında bilgi edinmeniz faydalı olacaktır. Uygulamayı geliştirme ortamınızda test etmek için şu adımları uygulayın:
- Sanal veya fiziksel Android test cihazınız açılıyor.
- Asistan uygulamasının çalıştığı doğrulanıyor.
- Android Studio'yu kullanarak cihazınızda örnek uygulamayı dağıtma ve çalıştırma
Uygulamanızı test etmek için şu adımları uygulayın:
- Android Studio'da Çalıştır'ı > Uygulamayı çalıştırın veya araç çubuğunda Çalıştır'ı tıklayın.
- Sanal cihaz kullanıyorsanız Select Deployment Target (Dağıtım Hedefi Seçin) iletişim kutusunda bir sanal cihaz seçip OK'i (Tamam) tıklayın. Önerilen işletim sistemi sürümü Android 8 (API düzeyi 26) veya sonraki sürümlerdir, ancak İşlemler Android 5 (API düzeyi 21) sürümüne kadar olan cihazlarda çalışır.
- Uygulamayı açtıktan sonra ana sayfa düğmesine uzun basarak Asistan'ı kurun ve çalıştığını doğrulayın. Henüz oturum açmadıysanız Asistan'da oturum açın.
- Uygulamayı yeniden açın.
Şekil 2. Egzersiz istatistiklerini gösteren Fit İşlemleri örnek uygulaması.
Özelliklerini görmek için uygulamayı kısaca keşfedin. Çalıştır simgesine dokunduğunda bir egzersiz zamanlayıcısı başlar, X simgesine dokunduğunda zamanlayıcı durur. Bunlar, Uygulama İşlemleri ile sesli kontrol için etkinleştireceğiniz görevlerdir.
Google Asistan eklentisini yükleme
Google Asistan eklentisi, Uygulama İşlemlerinizi bir test cihazında test etmenize olanak tanır. Uygulamayı Android Studio'ya eklemek için şu adımları uygulayın:
- Dosya > Ayarlar (MacOS'te Android Studio > Tercihler).
- Eklentiler bölümünde Marketplace'e gidin ve "Google Asistan" araması yapın.
- Aracı yükleyin ve Android Studio'yu yeniden başlatın.
4. Alıştırma Başlatma BII özelliğini ekleme
actions.intent.START_EXERCISE
BII, kullanıcıların seslerini kullanarak bir uygulama açıp antrenman başlatmalarına olanak tanır. Bu adımda, bu BII için kullanıcıların Asistan'dan Fitness uygulamasında koşu başlatmasını istemesine olanak tanıyan bir özellik uygularsınız.
Yeteneği tanımlayın
Asistan, aşağıdaki adımları izleyerek sesli komutları işlemek için shortcuts.xml
içinde tanımlanan capability
öğelerini kullanır:
- Asistan, kullanıcının sesli sorgusunu uygulamanızın özelliklerinde tanımlanan bir BII ile eşleştirir.
- Asistan, sorgudaki değerleri BII parametrelerine çıkarır. Her parametre, oluşturulmuş bir
Intent
öğesine ekli birBundle
öğesine eklenir. - Asistan, uygulamayı başlatmak için
Intent
öğesini kullanarak uygulamanın paket halinde sunulan parametrelere erişmesine izin verir.
START_EXERCISE
BII, exercise.name
BII parametresini destekler. Bu parametreyi, kullanıcıların uygulamada izlenecek egzersiz türünü belirtmesine izin vermek için kullanacaksınız.
app/src/main/res/xml
örnek proje dizininde bulunan shortcuts.xml
öğesine bu capability
öğesini ekleyerek START_EXERCISE
BII'sini uygulamanıza ekleyin:
<!-- shortcuts.xml -->
<capability android:name="actions.intent.START_EXERCISE">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
android:targetClass="com.devrel.android.fitactions.FitMainActivity">
<parameter
android:name="exercise.name"
android:key="exerciseType"/>
</intent>
</capability>
PUT_YOUR_APPLICATION_ID_HERE
değerini, önceki adımda tanımladığınız benzersiz applicationId
ile değiştirin.
Önceki örnek XML:
START_EXERCISE
BII için özellik tanımlar.- Asistan'ın uygulamayı başlatmak için oluşturduğu Android
intent
'i belirtir:targetPackage
vetargetClass
özellikleri, alma etkinliğini belirtir.parameter
özelliği,exercise.name
BII parametresini etkinlik tarafından alınanBundle
ekstralarındakiexerciseType
ile eşler.
BII parametrelerini satır içi envanterle yönetme
BII parametreleri, Asistan kullanıcı sorgusundan çıkarılan öğeleri temsil eder. Örneğin, bir kullanıcı "Ok Google, ExampleApp'te koşu başlat" dediğinde Asistan, "koşu" ifadesini ayıklar exercise.name
schema.org BII parametresine ekleyin. Bazı BII'ler için Asistan'a, BII parametrelerini uygulamanız tarafından beklenen bir tanımlayıcı grubuyla eşleştirmesi talimatını verebilirsiniz.
Bunu, satır içi envanter öğelerini BII parametresine bağlayarak yaparsınız. Satır içi envanter; "koşu", "yürüyüş" ve "jog" gibi desteklenen BII parametre değerleri ile bunlara karşılık gelen EXERCISE_RUN
gibi kısayol kimliklerini ifade eder. Bu envanter bağlaması, Asistan'ın sipariş karşılama etkinliğinize ham sorgu değeri yerine eşleşen parametreler için kısayol kimliğini iletmesini sağlar.
exercise.name
gibi bazı BII parametrelerinin çalışması için satır içi envanter gerekir. Bu parametreyi işlemek için shortcuts.xml
için aşağıdaki envanter shortcut
öğelerini ekleyin:
<!-- shortcuts.xml -->
<shortcuts>
<shortcut
android:shortcutId="running"
android:shortcutShortLabel="@string/activity_running">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/runningSynonyms"/>
</capability-binding>
</shortcut>
<shortcut
android:shortcutId="walking"
android:shortcutShortLabel="@string/activity_walking">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/walkingSynonyms"/>
</capability-binding>
</shortcut>
<shortcut
android:shortcutId="cycling"
android:shortcutShortLabel="@string/activity_cycling">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/cyclingSynonyms"/>
</capability-binding>
</shortcut>
<capability> ... </capability>
</shortcuts>
Önceki kodda, uygulamanın desteklediği egzersiz türleri için bir satır içi envanteri temsil eden üç kısayol tanımladınız: koşu, yürüyüş ve bisiklet. Her kısayol aşağıdaki yollarla bu özelliğe bağlıdır:
- Her
capability-binding
öğesininandroid:key
özelliği, özellik için tanımlanan aynıSTART_EXCERCISE
BII'yi belirtir. exercise.name
BII parametresine giden her kısayol tuşununparameter-binding
öğesi.
Satır içi envanter eş anlamlıları ekleme
Önceki envanter kısayollarında bulunan parameter-binding
öğesinin android:value
özellikleri, her bir envanter öğesinin eş anlamlılar dizisi kaynağına başvurur. Eş anlamlılar "koşu", "jog" ve "sprint" gibi bir öğe türünün varyasyonlarını sağlar aynı shortcutId
anlamına gelir. Projenin array.xml
kaynağına aşağıdaki eş anlamlı girişlerini ekleyin:
<!-- array.xml -->
<array name="runningSynonyms">
<item>Run</item>
<item>Jog</item>
<item>Jogging</item>
<item>Sprint</item>
</array>
<array name="walkingSynonyms">
<item>Walk</item>
<item>Hike</item>
<item>Hiking</item>
</array>
<array name="cyclingSynonyms">
<item>Biking</item>
<item>Riding</item>
<item>Pedaling</item>
</array>
Gelen Android amaçlarını yerine getirin
Android amaçları, Android'in başka bir uygulamadan işlem istemek için kullandığı mesajlaşma nesneleridir. Asistan, kullanıcıların tetiklenen özellikteki yapılandırma ayrıntılarından bir amaç oluşturarak sesli sorgular. START_EXERCISE
özelliği için amaçları yerine getirmek üzere FitMainActivity
hedef sınıfını, gelen intent ve BII parametrelerini işleyecek şekilde güncelleyin.
İlk olarak, Intent.handleIntent
işlevini aşağıdaki kodla değiştirin:
//FitMainActivity.kt
private fun Intent.handleIntent() {
when (action) {
// When the BII is matched, Intent.Action_VIEW will be used
Intent.ACTION_VIEW -> handleIntent(data)
// Otherwise start the app as you would normally do.
else -> showDefaultView()
}
}
Ardından, aşağıdaki kodu kullanarak sınıfa yeni bir handleIntent
işlevi ekleyin:
//FitMainActivity.kt
/**
* Use extras provided by the intent to handle the different BIIs
*/
private fun handleIntent(data: Uri?) {
// path is normally used to indicate which view should be displayed
// i.e https://fit-actions.firebaseapp.com/start?exerciseType="Running" -> path = "start"
var actionHandled = true
val startExercise = intent?.extras?.getString(START_EXERCISE)
// Add stopExercise variable here
if (startExercise != null){
val type = FitActivity.Type.find(startExercise)
val arguments = Bundle().apply {
putSerializable(FitTrackingFragment.PARAM_TYPE, type)
}
updateView(FitTrackingFragment::class.java, arguments)
} // Add conditional for stopExercise
else{
// path is not supported or invalid, start normal flow.
showDefaultView()
// Unknown or invalid action
actionHandled = false
}
notifyActionSuccess(actionHandled)
}
Önceki Intent.handleIntent
işlevinde, ACTION_VIEW
tetiklendiğinde uygulama işlemi amaç verileri handleIntent
işlevine aktarılır. START_EXERCISE
amacında yer alan BII parametrelerine intent?.extras?.getString(START_EXERCISE)
üzerinden erişilir. İşlevin geri kalanı, seçilen startExercise
fitness türünü göstermek için FitTrackingFragment
öğesini günceller.
Uygulama İşleminizi test etme
Uygulama İşlemleri geliştirme sırasında, İşlemlerinizi bir test cihazında önizlemek için Google Asistan eklentisini kullanırsınız. Eklentiyi, bir işlemin intent parametresi değerlerini ayarlayarak uygulamanızın, kullanıcının uygulamanız için Asistan isteğini ifade edebileceği çeşitli yöntemleri nasıl işlediğini test etmek için de kullanabilirsiniz.
Uygulama İşleminizi eklenti ile test etmek için aşağıdaki adımları izleyin:
- Uygulamanızı Android Studio'da Çalıştır'ı seçerek çalıştırın > Uygulamayı Çalıştırın'ı veya üstteki araç çubuğunda bulunan Çalıştır simgesini tıklayın.
- Araçlar'a gidin > Uygulama İşlemleri > Google Asistan > Uygulama İşlemleri Test Aracı.
- Önizleme Oluştur'u tıklayın. Sizden istenirse Uygulama İşlemleri politikalarını ve hizmet şartlarını inceleyip kabul edin.
actions.intent.START_EXERCISE
yerleşik amacını seçin.- egzersiz kutusunda varsayılan koşu değerini bırakın.
- Run App Action'ı (Uygulama İşlemini Çalıştır) tıklayın. Asistan'ın, uygulamanın egzersiz zamanlayıcısına derin bağlantı verdiğini ve zamanlayıcının koşu türünde bir antrenmana başladığını doğrulayın.
İlk Uygulama İşlemlerinizi START_EXERCISE
BII ile gerçekleştirdiniz. Tebrikler! Daha sonra, kullanıcıların uygulamanızda koşu antrenmanını durdurmalarına izin vereceğiz.
5. Durdurma Alıştırması BII özelliğini ekleme
actions.intent.STOP_EXERCISE
BII, kullanıcıların "Ok Google, ExampleApp'te koşumu durdur" gibi sorular sorarak antrenman oturumunu durdurmasına olanak tanır. shortcuts.xml
öğesine ikinci bir capability
ekleyerek bu BBI'yi Fitness uygulamasında uygulayın:
<!-- shortcuts.xml -->
<capability android:name="actions.intent.STOP_EXERCISE">
<intent
android:action="android.intent.action.VIEW"
android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
android:targetClass="com.devrel.android.fitactions.FitMainActivity">
<!-- Eg. name = "Running" -->
<parameter
android:name="exercise.name"
android:key="stopExercise"/>
</intent>
</capability>
PUT_YOUR_APPLICATION_ID_HERE
yerine benzersiz applicationId
girin.
BII parametrelerini satır içi envanterle yönetme
Bu BII, START_EXERCISE
BII ile aynı exercise.name
parametresini destekler. Bu sayede, kullanıcılar hangi aktif antrenmanı sonlandırmak istediklerini belirtebilir. Bunu etkinleştirmek için shortcuts.xml
hedefine ikinci bir envanter kısayol öğeleri grubu ekleyin:
<!-- shortcuts.xml -->
<shortcut
android:shortcutId="running"
android:shortcutShortLabel="@string/activity_running">
<capability-binding android:key="actions.intent.STOP_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/runningSynonyms"/>
</capability-binding>
</shortcut>
<shortcut
android:shortcutId="walking"
android:shortcutShortLabel="@string/activity_walking">
<capability-binding android:key="actions.intent.STOP_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/walkingSynonyms"/>
</capability-binding>
</shortcut>
<shortcut
android:shortcutId="cycling"
android:shortcutShortLabel="@string/activity_cycling">
<capability-binding android:key="actions.intent.STOP_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/cyclingSynonyms"/>
</capability-binding>
</shortcut>
Gelen Android amaçlarını yerine getirin
FitMainActivity
sınıfını güncelleyerek uygulamanın gelen STOP_EXERCISE
Android intent'lerini işleyebilmesini sağlayın. Öncelikle, STOP_EXERCISE
intent verilerini tutmak için handleIntent
işlevine bir değişken ekleyin:
// FitMainActivity.kt
private fun handleIntent(data: Uri?) {
val stopExercise = intent?.extras?.getString(STOP_EXERCISE)
//...
}
Ardından handleIntent
işlevinin koşullu mantığını, STOP_EXERCISE
niyetini işleyecek şekilde güncelleyin:
// FitMainActivity.kt
private fun handleIntent(data: Uri?) {
//...
if (startExercise != null){
val type = FitActivity.Type.find(startExercise)
val arguments = Bundle().apply {
putSerializable(FitTrackingFragment.PARAM_TYPE, type)
}
updateView(FitTrackingFragment::class.java, arguments)
} // Add conditional for stopExercise
<strong>
} else if(stopExercise != null){
// Stop the tracking service if any and return to home screen.
stopService(Intent(this, FitTrackingService::class.java))
updateView(FitStatsFragment::class.java)
}
</strong>
//...
}
Önceki kodda, gelen Android amacındaki STOP_EXERCISE
BII'yi kontrol etmek için handleIntent
işlevini güncellediniz. Bulunduğunda işlev, etkin zamanlayıcıyı durdurur ve kullanıcıyı ana ekrana döndürür.
Uygulama İşleminizi test etme
Aşağıdaki adımları uygulayarak Google Asistan eklentisini kullanarak Uygulama İşleminizi test edin:
- Uygulamanızı Android Studio'da Çalıştır'ı seçerek çalıştırın > Uygulamayı Çalıştırın'ı veya üstteki araç çubuğunda bulunan Çalıştır simgesini tıklayın.
- Uygulamada yeni bir "koşu" başlatın bir egzersizdir.
- Eklentiyi Android Studio'da açın: Araçlar > Uygulama İşlemleri > Google Asistan > Uygulama İşlemleri Test Aracı.
- Önizleme Oluştur'u tıklayın.
actions.intent.STOP_EXERCISE
yerleşik amacını seçin.- egzersiz kutusunda varsayılan koşu değerini bırakın.
- Run App Action'ı (Uygulama İşlemini Çalıştır) tıklayın. Asistan'ın antrenmanı durdurup sizi ana ekrana döndürdüğünü doğrulayın.
6. Sonraki adımlar
Tebrikler!
Artık Asistan'ın yerleşik amaçlarını kullanarak Android uygulamalarını sesle nasıl etkinleştireceğinizi biliyorsunuz. Bu codelab'de şunları öğrendiniz:
- Kullanıcıların Asistan'ı kullanarak belirli uygulama özelliklerini ayrıntılı olarak incelemesini sağlama.
- Satır içi envanter nasıl kullanılır?
- Google Asistan eklentisini kullanarak BBI'leri test etme.
Sırada ne var?
Buradan, Fitness uygulamanızda daha fazla ayrıntılandırma deneyebilirsiniz. Bitmiş projeye referans vermek için GitHub'da ana dala bakın.
Aşağıda, Uygulama İşlemleri ile bu uygulamanın kapsamını genişletme hakkında daha fazla bilgi için bazı öneriler verilmiştir:
- Diğer Uygulama İşlemleri codelab'lerimize göz atın.
- Uygulamalarınızı Asistan'a genişletmek için daha fazla BBI'yi keşfetmek isterseniz Uygulama İşlemleri yerleşik intentler referansını ziyaret edin.
Actions on Google yolculuğunuza devam etmek için aşağıdaki kaynakları inceleyin:
- developers.google.com/assistant: Actions on Google için resmi belge sitesi.
- Uygulama İşlemleri örnek dizini: Uygulama İşlemleri özelliklerini keşfetmek için örnek uygulamalar ve kod.
- Actions on Google GitHub deposu: Örnek kod ve kitaplıklar.
- r/GoogleAssistantDev: Google Asistan ile çalışan geliştiriciler için resmi Reddit topluluğu.
En son duyurularımızı kaçırmamak için bizi @ActionsOnGoogle Twitter'da takip edin ve oluşturduğunuz içerikleri paylaşmak için #appactions adresine tweet atın.
Geri bildirim anketi
Son olarak, bu codelab'deki deneyiminiz hakkında geri bildirimde bulunmak için lütfen bu anketi doldurun.