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

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.

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

Ş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:

  1. Android Studio'ya hoş geldiniz iletişim kutusunda 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, 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:

  1. Sanal veya fiziksel Android test cihazınız açılıyor.
  2. Asistan uygulamasının çalıştığı doğrulanıyor.
  3. 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:

  1. Android Studio'da Çalıştır'ı > Uygulamayı çalıştırın veya araç çubuğunda Çalıştıracabcb8f8634af20.png tıklayın.
  2. 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.
  3. 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.
  4. Uygulamayı yeniden açın.

Fit Actions uygulaması açık olan ve egzersiz istatistiklerini gösteren telefon.

Ş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:

  1. Dosya > Ayarlar (MacOS'te Android Studio > Tercihler).
  2. Eklentiler bölümünde Marketplace'e gidin ve "Google Asistan" araması yapın.
  3. 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:

  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 çıkarır. Her parametre, oluşturulmuş bir Intent öğesine ekli bir Bundle öğesine eklenir.
  3. 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 ve targetClass özellikleri, alma etkinliğini belirtir.
    • parameter özelliği, exercise.name BII parametresini etkinlik tarafından alınan Bundle ekstralarındaki exerciseType 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 öğesinin android:key özelliği, özellik için tanımlanan aynı START_EXCERCISE BII'yi belirtir.
  • exercise.name BII parametresine giden her kısayol tuşunun parameter-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:

  1. 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.
  2. Araçlar'a gidin > Uygulama İşlemleri > Google Asistan > Uygulama İşlemleri Test Aracı.
  3. Önizleme Oluştur'u tıklayın. Sizden istenirse 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. 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:

  1. 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.
  2. Uygulamada yeni bir "koşu" başlatın bir egzersizdir.
  3. Eklentiyi Android Studio'da açın: Araçlar > Uygulama İşlemleri > Google Asistan > Uygulama İşlemleri Test Aracı.
  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. 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:

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

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.