Memperluas aplikasi Android ke Asisten Google dengan Action Aplikasi

1. Ringkasan

Dengan Action Aplikasi, Anda dapat menggunakan Asisten Google untuk langsung meluncurkan fitur aplikasi dan menyelesaikan tugas menggunakan suara Anda. Sebagai developer Android, Anda menerapkan elemen kemampuan untuk menambahkan Action Aplikasi. Kemampuan akan memberi tahu Asisten fitur aplikasi mana yang mendukung permintaan suara pengguna, dan bagaimana Anda ingin permintaan tersebut terpenuhi.

Codelab ini menjelaskan konsep tingkat pemula untuk pengembangan dengan Action Aplikasi. Anda harus memiliki pengalaman sebelumnya dalam mengembangkan aplikasi Android dan intent Android untuk mengikuti codelab ini. Jika Anda baru menggunakan Android, sebaiknya mulai dengan salah satu codelab untuk dasar-dasar developer Android.

Yang akan Anda buat

Dalam codelab ini, Anda akan menambahkan dua intent bawaan (BII) Action Aplikasi ke aplikasi contoh kebugaran Android, yang memungkinkan pengguna memulai dan menghentikan timer olahraga menggunakan suara mereka.

Yang akan Anda pelajari

Anda akan mempelajari cara menggunakan BII dari kategori Kesehatan dan Kebugaran untuk memperluas Asisten ke aplikasi Android. Anda juga akan mempelajari cara menggunakan plugin Asisten Google untuk Android Studio agar dapat menguji BII Anda.

Prasyarat

Sebelum melanjutkan, pastikan Anda memiliki alat berikut di lingkungan Anda:

• Terminal untuk menjalankan perintah shell dengan git terinstal.
• Versi terbaru Android Studio.
• Akun Google dengan akses ke [Konsol Google Play][].
• Perangkat Android fisik atau virtual dengan akses Internet ke Play Store.

Sebelum melanjutkan, pastikan akun Google yang sama sudah login ke Android Studio dan aplikasi Google di perangkat pengujian.

2. Memahami cara kerjanya

Action Aplikasi menghubungkan pengguna dari Asisten Google ke aplikasi Android Anda. Bagaimana cara kerjanya?

Saat pengguna meminta Asisten untuk melakukan tugas menggunakan aplikasi Anda, Asisten akan mencocokkan kueri mereka dengan Action Aplikasi capability yang ditentukan dalam resource XML shortcuts.xml aplikasi Anda.

Istilah penting: Elemen kemampuan adalah template yang Anda tentukan di shortcuts.xml untuk mendeklarasikan jenis tindakan yang dapat dilakukan pengguna untuk meluncurkan aplikasi Anda, dan langsung menuju tugas tertentu. Untuk mengetahui detailnya, lihat dokumentasi Android untuk kemampuan.

Gambar 1. Diagram alur menunjukkan cara Asisten memproses kueri suara Action Aplikasi.

Setiap elemen kemampuan menentukan:

• Intent: Intent suara Action Aplikasi yang akan memicu kemampuan.
• Satu atau beberapa fulfillment: Intent Android atau deep link yang dihasilkan Asisten untuk meluncurkan aplikasi dan memenuhi permintaan suara pengguna. Definisi fulfillment akan menentukan parameter yang diharapkan dari kueri pengguna, dan bagaimana parameter tersebut harus dienkode ke dalam petunjuk peluncuran.

Intent

Menurut Natural Language Understanding (NLU), intent adalah sekelompok frasa pengguna yang memiliki arti serupa. Google telah membuat banyak intent "bawaan" (BII) yang mencakup berbagai jenis permintaan yang tersedia dengan Action Aplikasi. Misalnya, Asisten dilatih untuk mengaitkan frasa "Pesan pizza" atau "tampilkan menu hidangan penutup" dengan BII ORDER_MENU_ITEM. Dengan Action Aplikasi, Anda dapat memanfaatkan BII ini untuk dengan cepat memperluas permintaan suara umum ke fungsi aplikasi.

Fulfillment

Saat permintaan pengguna memicu Action Aplikasi di shortcuts.xml, aktivitas Android Anda kemudian harus mendeteksi dan menangani deep link atau intent Android yang masuk dan menyediakan fungsi yang diinginkan kepada pengguna. Hasilnya adalah pengalaman pengguna yang berbasis suara tempat Asisten memanggil aplikasi Anda sebagai respons atas kueri pengguna.

3. Menyiapkan lingkungan pengembangan

Codelab ini menggunakan aplikasi contoh Kebugaran untuk Android. Aplikasi ini memungkinkan pengguna memulai dan menghentikan timer olahraga, dan melihat statistik tentang rutinitas olahraga mereka.

Mendownload file dasar

Untuk mendapatkan file dasar bagi codelab ini, jalankan perintah berikut untuk meng-clone repositori GitHub:

git clone --branch codelab-start https://github.com/actions-on-google/appactions-fitness-kotlin.git

Setelah meng-clone repositori, buka di Android Studio:

1. Dalam dialog Welcome to Android Studio, klik Import project.
2. Cari dan pilih folder tempat Anda meng-clone repo.

Catatan: Perintah git clone di atas memeriksa cabang codelab-start repo, yang merupakan titik awal untuk codelab ini. Untuk melompat ke depan dan melihat aplikasi setelah petunjuk codelab selesai, lihat cabang utama repo.

Memperbarui ID aplikasi Android

Memperbarui ID aplikasi akan mengidentifikasi aplikasi di perangkat pengujian Anda secara unik dan menghindari error "Nama paket duplikat" jika aplikasi diupload ke Konsol Play. Untuk memperbarui ID aplikasi, buka app/build.gradle:

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

Ganti "MYUNIQUENAME" di kolom applicationId menjadi sesuatu yang unik bagi Anda.

Catatan: Setelah memperbarui applicationId, peringatan ini akan muncul di Android Studio: "Gradle files have changed since last project sync..." Di kotak peringatan ini, klik Sync Now untuk menghindari masalah yang mungkin terjadi saat mengupload aplikasi.

Mencoba aplikasi di perangkat Anda

Sebelum membuat perubahan lebih lanjut pada kode aplikasi, ada baiknya Anda mengetahui apa yang dapat dilakukan oleh aplikasi contoh. Menguji aplikasi di lingkungan pengembangan Anda melibatkan langkah-langkah berikut:

1. Membuka perangkat pengujian Android virtual atau fisik.
2. Memverifikasi apakah aplikasi Asisten berfungsi.
3. Menggunakan Android Studio untuk men-deploy dan menjalankan aplikasi contoh di perangkat Anda.

Ikuti langkah-langkah berikut untuk menguji aplikasi:

1. Di Android Studio, pilih Run > Run app atau klik Run di toolbar.
2. Jika menggunakan perangkat virtual, dalam dialog Select Deployment Target, pilih perangkat virtual dan klik OK. Versi OS yang direkomendasikan adalah Android 8 (API level 26) atau lebih tinggi, meskipun Action dapat berjalan di perangkat Android 5 (API level 21).
3. Setelah membuka aplikasi, tekan lama tombol Home untuk menyiapkan Asisten dan memastikannya berfungsi. Login ke Asisten jika Anda belum melakukannya.
4. Buka kembali aplikasi.

Catatan: Untuk informasi selengkapnya tentang perangkat virtual, lihat Membuat dan mengelola perangkat virtual.

Gambar 2. Aplikasi contoh Fit Actions yang menampilkan statistik olahraga.

Jelajahi aplikasi secara singkat untuk melihat apa yang dapat dilakukannya. Mengetuk ikon Lari akan memulai timer olahraga, dan mengetuk ikon X akan menghentikan timer. Tugas inilah yang akan Anda aktifkan untuk kontrol suara dengan Action Aplikasi.

Menginstal plugin Asisten Google

Plugin Asisten Google memungkinkan Anda menguji Action Aplikasi di perangkat pengujian. Ikuti langkah-langkah berikut untuk menambahkannya ke Android Studio:

1. Buka File > Settings (Android Studio > Preferences di MacOS).
2. Di bagian Plugin, buka Marketplace dan telusuri "Google Assistant".
3. Instal alat tersebut, lalu mulai ulang Android Studio.

Catatan: Plugin pengujian mengirimkan informasi ke Asisten melalui aplikasi Google di perangkat Android Anda. Perangkat pengujian memerlukan akses ke Play Store untuk memperbarui aplikasi Google sebelum Action Aplikasi dapat berfungsi dengan baik.

4. Menambahkan kemampuan BII Mulai Olahraga

BII actions.intent.START_EXERCISE memungkinkan pengguna membuka aplikasi dan memulai olahraga menggunakan suara mereka. Pada langkah ini, Anda akan menerapkan kemampuan untuk BII ini, yang memungkinkan pengguna meminta Asisten untuk memulai sesi lari di aplikasi Kebugaran.

Menentukan kemampuan

Asisten menggunakan elemen capability yang ditentukan di shortcuts.xml untuk memproses suara perintah suara dengan langkah-langkah berikut:

1. Asisten mencocokkan kueri suara pengguna dengan BII yang ditentukan dalam kemampuan aplikasi Anda.
2. Asisten mengekstrak nilai dari kueri ke parameter BII. Setiap parameter ditambahkan ke Bundle yang dilampirkan ke Intent yang dihasilkan.
3. Asisten menggunakan Intent untuk meluncurkan aplikasi, sehingga memberi aplikasi akses ke parameter paket.

BII START_EXERCISE mendukung parameter BII exercise.name. Anda akan menggunakan parameter ini untuk mengizinkan pengguna menentukan jenis olahraga yang akan dilacak di aplikasi.

Tambahkan BII START_EXERCISE ke aplikasi Anda dengan menambahkan capability ini ke shortcuts.xml, yang ada di direktori project contoh app/src/main/res/xml:

<!-- 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>

Ganti PUT_YOUR_APPLICATION_ID_HERE dengan applicationId unik yang Anda tentukan di langkah sebelumnya.

Contoh XML sebelumnya:

• Mendeklarasikan kemampuan untuk BII START_EXERCISE.
• Menentukan intent Android yang dihasilkan Asisten untuk meluncurkan aplikasi:
  • Atribut targetPackage dan targetClass menentukan aktivitas penerimaan.
  • Atribut parameter memetakan parameter BII exercise.name ke exerciseType dalam tambahan Bundle yang diterima oleh aktivitas.

Menangani parameter BII dengan inventaris inline

Parameter BII mewakili elemen yang diekstrak dari kueri pengguna Asisten. Misalnya, saat pengguna mengucapkan, "Ok Google, mulai sesi lari di ExampleApp", Asisten mengekstrak "lari" ke parameter BII schema.org exercise.name. Untuk beberapa BII, Anda dapat menginstruksikan Asisten untuk mencocokkan parameter BII dengan kumpulan ID yang diharapkan oleh aplikasi Anda.

Anda melakukannya dengan mengikat elemen inventaris inline ke parameter BII. Inventaris inline adalah kumpulan nilai parameter BII yang didukung, seperti "run", "hike", dan "jog", dan ID pintasannya yang sesuai, seperti EXERCISE_RUN. Dengan pengikatan inventaris ini, Asisten dapat meneruskan ID pintasan untuk parameter yang cocok, dan bukan nilai kueri mentah, ke aktivitas fulfillment Anda.

Beberapa parameter BII, seperti exercise.name, memerlukan inventaris inline agar dapat berfungsi. Untuk menangani parameter ini, tambahkan elemen shortcut inventaris berikut ke shortcuts.xml:

<!-- 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>

Dalam kode sebelumnya, Anda menentukan tiga pintasan yang mewakili inventaris inline untuk jenis olahraga yang didukung aplikasi: berlari, berjalan, dan bersepeda. Setiap pintasan terikat pada kemampuan dengan cara berikut:

• Setiap atribut android:key dari elemen capability-binding mengacu pada BII START_EXCERCISE yang sama yang ditentukan untuk kemampuan.
• Elemen parameter-binding dari setiap kunci pintasan mengarah ke parameter BII exercise.name.

Catatan: Setelah menyelesaikan langkah ini, Android Studio dapat memberikan peringatan kepada Anda bahwa simbol untuk nilai sinonim tidak dapat di-resolve. Anda me-resolve hal ini dengan menyelesaikan langkah berikutnya.

Menambahkan sinonim inventaris inline

Atribut android:value dari elemen parameter-binding di pintasan inventaris sebelumnya merujuk ke resource array sinonim untuk setiap elemen inventaris. Sinonim memungkinkan variasi jenis elemen, seperti "run", "jog", dan "sprint" untuk merujuk ke shortcutId yang sama. Tambahkan entri sinonim berikut ke resource array.xml project:

<!-- 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>

Memenuhi intent Android yang masuk

Intent Android adalah objek pesan yang digunakan Android untuk meminta tindakan dari aplikasi lain. Asisten memenuhi kueri suara pengguna dengan menghasilkan intent dari detail konfigurasi dalam kemampuan yang dipicu. Agar dapat memenuhi intent untuk kemampuan START_EXERCISE, perbarui class target FitMainActivity untuk menangani parameter intent yang masuk dan BII.

Pertama, ganti fungsi Intent.handleIntent dengan kode berikut:

//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()
  }
}

Selanjutnya, tambahkan fungsi handleIntent baru ke class dengan kode berikut:

//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)
}

Pada fungsi Intent.handleIntent sebelumnya, saat ACTION_VIEW dipicu, data intent Action Aplikasi diteruskan ke fungsi handleIntent. Parameter BII yang dipaketkan dalam intent START_EXERCISE diakses melalui intent?.extras?.getString(START_EXERCISE). Fungsi lainnya akan memperbarui FitTrackingFragment untuk menampilkan jenis kebugaran startExercise yang dipilih.

Menguji Action Aplikasi Anda

Selama pengembangan Action Aplikasi, Anda menggunakan plugin Asisten Google untuk melihat pratinjau Action di perangkat pengujian. Anda juga dapat menggunakan plugin untuk menyesuaikan nilai parameter intent Action untuk menguji bagaimana aplikasi Anda menangani berbagai cara yang mungkin digunakan pengguna saat mengajukan permintaan kepada Asisten untuk aplikasi Anda.

Untuk menguji Action Aplikasi Anda dengan plugin, ikuti langkah-langkah berikut:

1. Jalankan aplikasi Anda di Android Studio dengan memilih Run > Run app atau mengklik ikon Run di toolbar bagian atas.
2. Buka Tools > App Actions > Google Assistant > App Actions Test Tool.
3. Klik Create Preview. Jika diminta, tinjau dan setujui kebijakan dan persyaratan layanan Action Aplikasi.
4. Pilih intent bawaan actions.intent.START_EXERCISE.
5. Di kotak exercise, biarkan nilai running menjadi default.
6. Klik Run App Action. Verifikasi bahwa Asisten membuat deep link ke timer olahraga aplikasi, dan bahwa timer telah memulai olahraga jenis lari.

Tips: Periksa panduan pemecahan masalah jika Anda mengalami masalah saat menjalankan alat pengujian.

Anda telah menerapkan Action Aplikasi pertama dengan BII START_EXERCISE. Selamat! Selanjutnya, kami akan menyediakan opsi kepada pengguna untuk menghentikan olahraga berlari di aplikasi Anda.

5. Menambahkan kemampuan BII Berhenti Olahraga

BII actions.intent.STOP_EXERCISE memungkinkan pengguna menghentikan sesi olahraga dengan meminta hal-hal seperti, "Ok Google, hentikan sesi lari saya di ExampleApp". Terapkan BII ini di aplikasi Kebugaran dengan menambahkan capability kedua ke shortcuts.xml:

<!-- 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>

Ganti PUT_YOUR_APPLICATION_ID_HERE dengan applicationId unik Anda.

Menangani parameter BII dengan inventaris inline

BII ini mendukung parameter exercise.name yang sama dengan BII START_EXERCISE, sehingga memungkinkan pengguna menentukan olahraga aktif yang ingin diakhiri. Untuk mengaktifkan opsi ini, tambahkan kumpulan elemen pintasan inventaris kedua ke shortcuts.xml:

<!-- 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>

Memenuhi intent Android yang masuk

Buat aplikasi agar dapat menangani intent Android STOP_EXERCISE yang masuk dengan memperbarui class FitMainActivity. Pertama, tambahkan variabel ke fungsi handleIntent untuk menyimpan data intent STOP_EXERCISE:

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  val stopExercise = intent?.extras?.getString(STOP_EXERCISE)
  //...
}

Selanjutnya, perbarui logika kondisional fungsi handleIntent untuk menangani intent STOP_EXERCISE:

// 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>
  //...
}

Pada kode sebelumnya, Anda telah memperbarui fungsi handleIntent untuk memeriksa BII STOP_EXERCISE dalam intent Android yang masuk. Jika ditemukan, fungsi tersebut akan menghentikan timer aktif dan mengembalikan pengguna ke layar utama.

Menguji Action Aplikasi Anda

Uji Action Aplikasi Anda menggunakan plugin Asisten Google dengan mengikuti langkah-langkah berikut:

1. Jalankan aplikasi Anda di Android Studio dengan memilih Run > Run app atau mengklik ikon Run di toolbar bagian atas.
2. Di aplikasi, mulai olahraga "running" baru.
3. Buka plugin di Android Studio: buka Tools > App Actions > Google Assistant > App Actions Test Tool.
4. Klik Create Preview.
5. Pilih intent bawaan actions.intent.STOP_EXERCISE.
6. Di kotak exercise, biarkan nilai running menjadi default.
7. Klik Run App Action. Verifikasi bahwa Asisten menghentikan olahraga dan mengembalikan Anda ke layar utama.

Tips: Periksa panduan pemecahan masalah jika Anda mengalami masalah saat menjalankan alat pengujian.

6. Langkah berikutnya

Selamat!

Anda kini sudah memahami cara mengaktifkan aplikasi Android dengan suara menggunakan intent bawaan di Asisten. Dalam codelab ini, Anda telah mempelajari:

• Cara mengizinkan pengguna mempelajari fitur aplikasi tertentu secara mendalam menggunakan Asisten.
• Cara menggunakan inventaris inline.
• Cara menguji BII menggunakan plugin Asisten Google.

Langkah berikutnya

Dari sini, Anda dapat terus mencoba mengoptimalkan aplikasi kebugaran. Untuk mereferensikan project yang sudah selesai, lihat cabang utama di GitHub.

Berikut beberapa saran untuk mempelajari lebih lanjut cara memperluas aplikasi ini dengan Action Aplikasi:

• Lihat codelab Action Aplikasi kami yang lain.
• Buka referensi intent bawaan Action Aplikasi guna menemukan lebih banyak BII untuk memperluas aplikasi Anda ke Asisten.

Untuk melanjutkan perjalanan Actions on Google Anda, pelajari referensi berikut:

• developers.google.com/assistant: Situs dokumentasi resmi untuk Actions on Google.
• Indeks contoh Action Aplikasi: Aplikasi contoh dan kode untuk menjelajahi kemampuan Action Aplikasi.
• Repo GitHub Actions on Google: Kode contoh dan library.
• r/GoogleAssistantDev: Komunitas Reddit resmi untuk developer yang bekerja dengan Asisten Google.

Ikuti kami di Twitter @ActionsOnGoogle untuk terus memantau pengumuman terbaru kami, dan kirim tweet dengan tagar #appactions untuk membagikan karya yang telah Anda buat.

Survei masukan

Terakhir, isi survei ini untuk memberikan masukan tentang pengalaman Anda dengan codelab ini.