Uygulama İşlemleri ile Android uygulamalarını Google Asistan'a genişletme

1. Genel Bakış

Uygulama İşlemleri ile Google Asistan'ı kullanarak doğrudan uygulama özelliklerine gidebilir ve görevleri sesinizi kullanarak tamamlayabilirsiniz. Android geliştiricisi olarak, uygulama işlemleri eklemek için yetenek öğelerini uygularsınız. Özellikler, Asistan'ın hangi uygulama özelliklerinin kullanıcı sesli isteklerini desteklediğini ve bu isteklerin nasıl yerine getirilmesini istediğinizi bilmesini sağlar.

Bu codelab'de, uygulama işlemleriyle geliştirme yapmaya yeni başlayanlar için temel kavramlar ele alınmaktadır. Bu codelab'i takip etmek için Android uygulamaları geliştirme ve Android amaçları konusunda deneyimli olmanız gerekir. Android'e yeni başladıysanız Android geliştirici temelleri ile ilgili bir codelab ile başlamak isteyebilirsiniz.

Ne oluşturacaksınız?

Bu codelab'de, örnek bir fitness Android uygulamasına iki yerleşik uygulama işlemi amacı (BII) ekleyerek kullanıcıların seslerini kullanarak egzersiz zamanlayıcısını başlatıp durdurmalarını sağlayacaksınız.

Neler öğreneceksiniz?

Asistan'ı bir Android uygulamasına genişletmek için Sağlık ve Fitness kategorisindeki BII'leri nasıl kullanacağınızı öğreneceksiniz. Ayrıca BII'lerinizi test etmek için Android Studio'daki 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ü olan kabuk komutlarını çalıştırmak için bir terminal.
  • Android Studio'nun en son sürümü.
  • [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, test cihazınızdaki Google uygulamasında ve Android Studio'da aynı Google Hesabı ile oturum açtığınızdan emin olun.

2. İşleyiş şeklini anlama

Uygulama İşlemleri, Google Asistan'daki kullanıcıları Android uygulamanıza bağlar. Nasıl çalışırlar?

Bir kullanıcı Asistan'dan uygulamanızı kullanarak bir görev gerçekleştirmesini istediğinde Asistan, sorgusunu uygulamanızın shortcuts.xml XML kaynağında tanımlanan bir uygulama işlemine capability eşleştirir.

Google Asistan'ın bir uygulama işlemleri sesli sorgusunu nasıl işlediğini gösteren akış şeması

Şekil 1. Asistan'ın, Uygulama İşlemleri sesli sorgularını nasıl işlediğini gösteren bir akış şeması.

Her bir özellik öğesi şunları tanımlar:

  • Bir amaç: Özelliği tetikleyecek uygulama işlemleri sesli amacı.
  • Bir veya daha fazla karşılama: Asistan'ın uygulamayı başlatmak ve kullanıcının sesli isteğini karşılamak için oluşturduğu Android amaçları veya derin bağlantılar. Doldurma tanımları, kullanıcı sorgusundan hangi parametrelerin beklendiğini ve bu parametrelerin başlatma talimatlarına nasıl kodlanması gerektiğini belirtir.

Niyetler

Doğal Dil Anlama (NLU) alanında amaç, benzer anlamlar taşıyan bir grup kullanıcı ifadesidir. Google, Uygulama İşlemleri ile çok çeşitli istek türlerini kapsayan düzinelerce "yerleşik" amaç (BII) sunar. Örneğin, Asistan, "Pizza sipariş et" veya "Tatlı menüsünü göster" ifadelerini ORDER_MENU_ITEM BII'siyle ilişkilendirecek şekilde eğitilmiştir. Uygulama İşlemleri ile bu BII'lerden yararlanarak yaygın sesli istekleri uygulama işlevselliğine hızlıca genişletebilirsiniz.

İstek karşılama

Bir kullanıcı isteği shortcuts.xml'da bir uygulama işlemini tetiklediğinde Android etkinliğiniz gelen Android amacını veya derin bağlantıyı algılayıp işlemeli ve kullanıcıya istediği işlevi sağlamalıdır. Sonuç olarak, Asistan'ın kullanıcının sorgusuna yanıt olarak uygulamanızı çağırdığı, sesle kontrol edilen 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ını 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

Depoyu klonladıktan sonra Android Studio'da açın:

  1. Welcome to Android Studio (Android Studio'ya Hoş Geldiniz) iletişim kutusunda Import project'i (Projeyi içe aktar) tıklayın.
  2. Depoyu klonladığınız klasörü bulup seçin.

Android uygulama kimliğini güncelleme

Uygulamanın uygulama kimliğini güncellemek, uygulamayı test cihazınızda benzersiz bir şekilde tanımlar ve uygulama Play Console'a yüklenirse "Paket adı yineleniyor" hatasını önler. Uygulama kimliğini güncellemek için app/build.gradle uygulamasını açın:

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

applicationId alanındaki "MYUNIQUENAME" ifadesini size özel benzersiz bir ifadeyle değiştirin.

Uygulamayı cihazınızda deneme

Uygulamanın kodunda başka değişiklikler yapmadan önce örnek uygulamanın neler yapabileceği hakkında fikir edinmek faydalı olur. Uygulamayı geliştirme ortamınızda test etmek için şu adımları uygulayın:

  1. Sanal veya fiziksel Android test cihazınızı açma
  2. Asistan uygulamasının çalıştığını doğrulama
  3. Örnek uygulamayı cihazınıza dağıtmak ve cihazınızda çalıştırmak için Android Studio'yu kullanma.

Uygulamanızı test etmek için aşağıdaki adımları uygulayın:

  1. Android Studio'da Run (Çalıştır) > Run app (Uygulamayı çalıştır) seçeneğini belirleyin veya araç çubuğunda Run'ı (Çalıştır) acabcb8f8634af20.png tıklayın.
  2. Sanal cihaz kullanıyorsanız Select Deployment Target (Dağıtım Hedefi Seç) iletişim kutusunda bir sanal cihaz seçip OK'u (Tamam) tıklayın. Android 8 (API düzeyi 26) veya sonraki sürümler önerilen işletim sistemi sürümü olsa da işlemler Android 5 (API düzeyi 21) gibi eski sürümlerde de çalışır.
  3. Uygulamayı açtıktan sonra Asistan'ı kurmak ve çalıştığını doğrulamak için ana sayfa düğmesine uzun basın. Henüz yapmadıysanız Asistan'da oturum açın.
  4. Uygulamayı yeniden açın.

Fit İşlemler uygulaması açık olan telefonda egzersiz istatistikleri gösteriliyor.

Şekil 2. Egzersiz istatistiklerini gösteren Fit İşlemleri örnek uygulaması.

Uygulamanın neler yapabileceğini görmek için uygulamayı kısaca inceleyin. Çalıştır simgesine dokunarak egzersiz zamanlayıcısını başlatabilir, X simgesine dokunarak da zamanlayıcıyı durdurabilirsiniz. Bunlar, uygulama işlemleriyle sesli kontrol için etkinleştireceğiniz görevlerdir.

Google Asistan eklentisini yükleme

Google Asistan eklentisi, uygulama işlemlerinizi test cihazında test etmenize olanak tanır. Kitaplığı Android Studio'ya eklemek için aşağıdaki adımları uygulayın:

  1. Dosya > Ayarlar'a (MacOS'te Android Studio > Tercihler) gidin.
  2. Eklentiler bölümünde Pazar Yeri'ne gidin ve "Google Asistan"ı arayın.
  3. Aracı yükleyin ve Android Studio'yu yeniden başlatın.

4. Start Exercise BII özelliğini ekleyin

actions.intent.START_EXERCISE BII, kullanıcıların seslerini kullanarak bir uygulamayı açıp antrenmana başlamasına olanak tanır. Bu adımda, kullanıcıların Asistan'dan Fitness uygulamasında koşu başlatmasını istemesine olanak tanıyan bir özelliği bu BII için uygularsınız.

Özelliği tanımlama

Asistan, sesli komutları işlemek için shortcuts.xml içinde tanımlanan capability öğelerini aşağıdaki adımlarla kullanır:

  1. Asistan, kullanıcının sesli sorgusunu uygulamanızın özelliklerinde tanımlanan bir BII ile eşleştirir.
  2. Asistan, sorgudaki değerleri BII parametrelerine ayıklar. Her parametre, oluşturulan bir Intent öğesine eklenen bir Bundle öğesine eklenir.
  3. Asistan, uygulamayı başlatmak için Intent kullanır ve uygulamaya paketlenmiş parametrelere erişim izni verir.

START_EXERCISE BII, exercise.name BII parametresini destekler. Kullanıcıların uygulamada izlenecek egzersiz türünü belirtmesine izin vermek için bu parametreyi kullanırsınız.

START_EXERCISE BII'yi uygulamanıza eklemek için app/src/main/res/xml örnek proje dizinindeki shortcuts.xml'e şu capability öğesini 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 kısmını, önceki adımda tanımladığınız benzersiz applicationId ile değiştirin.

Yukarıdaki örnek XML:

  • START_EXERCISE BII için bir özellik bildirir.
  • Asistan'ın uygulamayı başlatmak için oluşturduğu Android intent'ı belirtir:
    • targetPackage ve targetClass özellikleri, alıcı etkinliği belirtir.
    • parameter özelliği, exercise.name BII parametresini etkinliğin aldığı Bundle ekstralarındaki exerciseType ile eşler.

Satır içi envanterle BII parametrelerini işleme

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, exercise.name schema.org BII parametresine "koşu" değerini çıkarır. Bazı BII'ler için Asistan'a, BII parametrelerini uygulamanızın beklediği bir tanımlayıcı grubuyla eşleştirmesini söyleyebilirsiniz.

Bu işlemi, satır içi envanter öğelerini BII parametresine bağlayarak yapabilirsiniz. Satır içi envanter, "koşu", "doğa yürüyüşü" ve "jogging" gibi desteklenen BII parametre değerleri ve bunların karşılık gelen kısayol kimliklerinden (ör. EXERCISE_RUN) oluşan bir settir. Bu envanter bağlama işlemi, Asistan'ın ham sorgu değeri yerine eşleşen parametreler için kısayol kimliğini karşılama etkinliğinize 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 shortcut öğelerini shortcuts.xml öğesine 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 desteklenen egzersiz türleri (koşu, yürüyüş ve bisiklet) için satır içi envanteri temsil eden üç kısayol tanımladınız. Her kısayol, aşağıdaki şekillerde özelliğe bağlıdır:

  • Her capability-binding öğesinin android:key özelliği, yetenek için tanımlanan aynı START_EXCERCISE BII'yi ifade eder.
  • Her kısayol tuşunun parameter-binding öğesi, exercise.name BII parametresine karşılık gelir.

Satır içi envanter eş anlamlıları ekleme

Önceki envanter kısayollarındaki parameter-binding öğesinin android:value özellikleri, her envanter öğesi için eş anlamlı kelimelerin bulunduğu bir dizi kaynağını ifade eder. Eş anlamlılar, "koşmak", "tempolu yürüyüş" ve "sürat koşusu" gibi bir öğe türünün varyasyonlarının aynı shortcutId'ya atıfta bulunmasını sağlar. Aşağıdaki eş anlamlı girişlerini projenin array.xml kaynağına 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ı karşılama

Android intent'leri, Android'in başka bir uygulamadan işlem isteğinde bulunmak için kullandığı mesajlaşma nesneleridir. Asistan, tetiklenen yetenekteki yapılandırma ayrıntılarından bir intent oluşturarak kullanıcıların sesli sorgularını karşılar. START_EXERCISE özelliğine yönelik amaçları yerine getirmek için FitMainActivity hedef sınıfını gelen amaç 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)
}

Yukarıdaki Intent.handleIntent işlevinde, ACTION_VIEW tetiklendiğinde uygulama işlemi amaç verileri handleIntent işlevine iletilir. START_EXERCISE amacında paketlenmiş 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 değerini günceller.

Uygulama İşleminizi test etme

Uygulama İşlemleri geliştirme sürecinde, İşlemlerinizi bir test cihazında önizlemek için Google Asistan eklentisini kullanırsınız. Ayrıca, eklentiyi kullanarak bir İşlemin amaç parametre değerlerini ayarlayabilir ve 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 edebilirsiniz.

Uygulama İşleminizi eklentiyle test etmek için aşağıdaki adımları uygulayın:

  1. Run (Çalıştır) > Run App (Uygulamayı Çalıştır) seçeneğini belirleyerek veya üst araç çubuğundaki Run (Çalıştır) simgesini tıklayarak uygulamanızı Android Studio'da çalıştırın.
  2. Araçlar > Uygulama İşlemleri > Google Asistan > Uygulama İşlemleri Test Aracı'na gidin.
  3. Önizleme Oluştur'u tıklayın. İstenirse Uygulama İşlemleri politikalarını ve hizmet şartlarını inceleyip kabul edin.
  4. actions.intent.START_EXERCISE yerleşik amacını seçin.
  5. Egzersiz kutusunda varsayılan koşu değerini bırakın.
  6. Uygulama İşlemini Çalıştır'ı tıklayın. Asistan'ın, uygulamanın egzersiz zamanlayıcısına derin bağlantı oluşturduğunu ve zamanlayıcının koşu türünde bir antrenmana başladığını doğrulayın.

START_EXERCISE BII ile ilk uygulama işlemlerinizi uyguladınız. Tebrikler! Ardından, kullanıcıların uygulamanızda devam eden bir antrenmanı durdurabilmesini sağlayacağız.

5. Egzersizi Durdur BII özelliğini ekleme

actions.intent.STOP_EXERCISE BII, kullanıcıların "Ok Google, ExampleApp'te koşumu durdur." gibi şeyler söyleyerek egzersiz seansını durdurmasına olanak tanır. shortcuts.xml öğesine ikinci bir capability ekleyerek bu BII'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 değerinizi girin.

Satır içi envanterle BII parametrelerini işleme

Bu BII, START_EXERCISE BII ile aynı exercise.name parametresini destekler. Böylece kullanıcılar, hangi etkin antrenmanı sonlandırmak istediklerini belirtebilir. Bu özelliği etkinleştirmek için shortcuts.xml öğesine ikinci bir envanter kısayolu öğesi 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ı karşılama

FitMainActivity sınıfını güncelleyerek uygulamanın gelen STOP_EXERCISE Android amaçlarını işlemesini sağlayın. İlk olarak, STOP_EXERCISE amaç 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 amaçlarını 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 intent'inde STOP_EXERCISE BII'nin olup olmadığını kontrol etmek için handleIntent işlevini güncellediniz. Bulunursa 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 işleminizi test edin:

  1. Run (Çalıştır) > Run App (Uygulamayı Çalıştır) seçeneğini belirleyerek veya üst araç çubuğundaki Run (Çalıştır) simgesini tıklayarak uygulamanızı Android Studio'da çalıştırın.
  2. Uygulamada yeni bir "koşu" egzersizi başlatın.
  3. Eklentiyi Android Studio'da açın: Tools (Araçlar) > App Actions (Uygulama İşlemleri) > Google Assistant > App Actions Test Tool'a (Uygulama İşlemleri Test Aracı) gidin.
  4. Önizleme Oluştur'u tıklayın.
  5. actions.intent.STOP_EXERCISE yerleşik amacını seçin.
  6. Egzersiz kutusunda varsayılan koşu değerini bırakın.
  7. 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ına sesli erişim özelliğini nasıl ekleyeceğinizi biliyorsunuz. Bu codelab'de şunları öğrendiniz:

  • Kullanıcıların Asistan'ı kullanarak belirli uygulama özelliklerine ayrıntılı bir şekilde göz atmasına izin verme
  • Satır içi envanter nasıl kullanılır?
  • Google Asistan eklentisini kullanarak BII'leri test etme

Sırada ne var?

Buradan Fitness uygulamanızda daha fazla iyileştirme yapmayı deneyebilirsiniz. Tamamlanmış projeye referans vermek için GitHub'daki ana dalı inceleyin.

Bu uygulamayı Uygulama İşlemleri ile genişletme hakkında daha fazla bilgi edinmek için aşağıdaki önerilerden yararlanabilirsiniz:

Actions on Google yolculuğunuza devam etmek için aşağıdaki kaynakları inceleyin:

En son duyurularımızdan haberdar olmak için Twitter'da @ActionsOnGoogle hesabını takip edin ve geliştirdiklerinizi paylaşmak için #appactions etiketini kullanarak tweet atın.

Geri bildirim anketi

Son olarak, bu codelab ile ilgili deneyiminizi paylaşmak için lütfen bu anketi doldurun.