Memperluas aplikasi Android ke Asisten Google dengan Action Aplikasi (Level 2)

Pada codelab Action Aplikasi pertama, Anda telah mempelajari cara memperluas Asisten Google ke sampel aplikasi kebugaran dengan menerapkan intent bawaan (BII) dari kategori BII Kesehatan dan Kebugaran. BII disusun ke dalam beberapa kategori yang mewakili jenis tugas yang sering diminta pengguna untuk dilakukan Asisten.

Dalam codelab ini, Anda akan mempelajari cara menambahkan Action Aplikasi ke aplikasi menggunakan BII dari [Common BII category], yang mewakili tugas aplikasi umum yang dapat dipenuhi oleh hampir semua aplikasi Android.

Codelab ini mencakup konsep tingkat menengah untuk mengembangkan aplikasi dengan Action Aplikasi. Anda harus memiliki pengalaman sebelumnya dalam mengembangkan aplikasi Android, menangani deep link, membuat resource actions.xml, dan menggunakan plugin Alat Uji Action Aplikasi. Developer yang benar-benar baru mengenal Action Aplikasi mungkin ingin memulai dengan codelab sebelumnya.

Yang akan Anda buat

Dalam codelab ini, Anda menambahkan dua BII Umum ke contoh aplikasi Daftar tugas, yang memungkinkan pengguna meminta Asisten untuk:

Tiga layar progresif tempat Asisten Google menampilkan tugas aktif dalam aplikasi.

Yang akan Anda pelajari

  • Bagaimana BII Kategori Umum dapat digunakan untuk memperluas Asisten ke sebagian besar aplikasi Android.
  • Cara menguji BII Umum dengan plugin Alat Uji Action Aplikasi.

Prasyarat

  • Terminal untuk menjalankan perintah shell dengan git terpasang.
  • Rilis stabil terbaru dari Android Studio.
  • Akun Google yang memiliki akses ke Konsol Google Play.
  • Perangkat Android atau emulator dengan akses Internet ke Google Play Store, untuk menguji action Anda.

Dalam codelab ini, Anda menggunakan perangkat Android (fisik atau emulator) untuk menguji action. Jika menggunakan perangkat fisik, pastikan perangkat tersambung ke mesin pengembangan lokal Anda. Anda juga harus login ke aplikasi Google di perangkat (atau emulator), lalu login ke Android Studio, menggunakan akun Google yang sama. Perangkat juga harus menginstal aplikasi Asisten Google.

Codelab ini dimulai dengan contoh aplikasi Daftar tugas untuk Android. Pengguna aplikasi contoh ini dapat menambahkan item daftar tugas, menelusuri item menurut kategori, dan melihat informasi tentang tugas yang diselesaikan.

Mendownload file dasar Anda

Jalankan perintah berikut untuk meng-clone GitHub repository aplikasi contoh:

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

Setelah meng-clone repositori, buka di Android Studio:

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

Untuk melihat versi aplikasi Daftar Tugas yang mewakili codelab yang sudah selesai, clone repo aplikasi contoh, menggunakan tanda --branch master.

Mengubah ID aplikasi Android untuk mengaktifkan pengujian

Nanti dalam codelab ini, Anda menggunakan Alat Uji Action Aplikasi untuk menguji action pada perangkat Android atau emulator. Untuk menjalankannya, alat uji mengharuskan aplikasi Anda diupload ke project di Konsol Google Play terlebih dulu. Untuk menghindari error "Nama paket duplikat" saat mengupload aplikasi ke Konsol Play, ubah applicationId aplikasi contoh menjadi sesuatu yang unik bagi Anda.

Di app/build.gradle, update nilai applicationId "com.example.myapp" ke ID unik, misalnya "com.codelabs.myname". Jika Anda memerlukan bantuan dalam menentukan ID aplikasi, kunjungi halaman referensi Android.

build.gradle

android {
...
    defaultConfig {
        // This ID uniquely identifies your app on the device and in Google Play Store
        applicationId "com.example.myapp"
    ...
    }
}

Setelah mengupdate applicationId, Anda mungkin melihat kotak peringatan berwarna kuning di IDE berlabel "File Gradle telah berubah sejak sinkronisasi project terakhir..." Jika demikian, klik Sinkronkan Sekarang di kotak untuk menghindari masalah yang mungkin terjadi saat mengupload aplikasi ke Konsol Play.

Menguji aplikasi di perangkat Anda

Sebelum membuat lebih banyak perubahan pada aplikasi, sebaiknya Anda mengetahui apa saja yang dapat dilakukan aplikasi contoh. Coba jalankan aplikasi tersebut di emulator:

  • Di Android Studio, pilih Run > Run app atau klik Run di toolbar.
  • Pada dialog Select Deployment Target, pilih perangkat virtual lalu klik OK. Versi OS yang direkomendasikan adalah Android 10 (API level 30) atau lebih tinggi, meskipun Action juga bisa berjalan di perangkat Android 5 (API level 21).

Siapkan dan verifikasi Asisten berfungsi di perangkat Anda dengan menekan lama tombol Layar utama. Anda harus login ke Asisten di perangkat jika belum melakukannya.

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

Animasi yang mendemonstrasikan aplikasi contoh Daftar tugas

Jelajahi aplikasi secara singkat untuk melihat apa yang bisa dilakukannya. Mengetuk ikon Plus akan membuat item tugas baru, dan item menu di kanan atas memungkinkan Anda menelusuri dan memfilter item tugas berdasarkan status penyelesaian.

Mengupload ke Konsol Play

Mengupload aplikasi ke project di Konsol Google Play adalah prasyarat untuk menggunakan Alat Uji Action Aplikasi di Android Studio. Buat aplikasi Anda di Android Studio dan upload ke Konsol Play sebagai draf rilis internal.

Untuk membuat aplikasi Anda di Android Studio, lakukan langkah berikut:

  1. Buka Build > Generate Signed Bundle / APK.
  2. Pilih "Android App Bundle" lalu klik Next.
  3. Masukkan detail untuk menandatangani aplikasi Anda lalu klik Next.
  4. Pilih varian build "prodRelease", lalu klik Finish.

Di Konsol Google Play, upload app bundle yang baru saja Anda buat sebagai aplikasi baru:

  1. Di halaman Semua aplikasi, klik Buat aplikasi.
  2. Beri nama aplikasi yang Anda inginkan dan klik Buat aplikasi. Untuk codelab ini, Anda tidak perlu mengisi informasi aplikasi apa pun setelah aplikasi dibuat.
  3. Dari menu sidebar, buka Pengujian dan temukan halaman Pengujian internal.
  4. Klik Buat rilis baru di halaman Pengujian internal.
  5. Klik Lanjutkan untuk menyetujui Penandatanganan aplikasi oleh Google Play.
  6. Di panel App bundle dan APK, upload file AAB yang Anda buat sebelumnya (kemungkinan ada di direktori app/prod/release). Klik Simpan.

Menginstal plugin uji

Plugin Alat Uji Action Aplikasi memungkinkan Anda menguji Action Aplikasi, untuk satu pengguna, di perangkat pengujian. Jika Anda belum memiliki alat uji, instal dengan mengikuti langkah-langkah berikut:

  1. Buka File > Setelan (Android Studio > Preferensi di MacOS).
  2. Di bagian Plugin, buka Marketplace dan telusuri "Alat pengujian Action Aplikasi". Anda juga dapat mendownload dan menginstal alat pengujian secara manual.
  3. Instal alat tersebut lalu mulai ulang Android Studio.

Pada langkah ini, Anda menerapkan BII Fitur buka aplikasi, yang memungkinkan pengguna melihat tugas yang aktif dan yang sudah selesai, menggunakan Asisten. Untuk melakukannya, perluas deep link yang ada untuk fitur pemfilteran tugas ke Asisten, dengan menentukan BII di actions.xml. Anda menyelesaikan bagian ini dengan menguji action di perangkat.

Sebelum menerapkan BII, verifikasi bahwa deep link yang ada di aplikasi Anda memenuhi perilaku Action Aplikasi yang diidentifikasi.

Untuk menguji deep link dengan alat command-line Android Debug Bridge (adb), ikuti langkah-langkah berikut:

  1. Update aplikasi di perangkat Anda.
  2. Isi daftar tugas dengan item contoh dengan mengetuk tombol refresh yang berada di panel aplikasi tambahan:

Menu tambahan toolbar aplikasi daftar tugas

Jika diberi opsi untuk membuka dengan Google, pilih "Selalu" untuk mengizinkan aplikasi Tugas membuka link dukungan. Anda dapat mengubah preferensi ini nanti di setelan aplikasi.

Di terminal Anda, masukkan setiap perintah adb berikut untuk menguji deep link pemfilteran tugas aplikasi:

Lihat tugas aktif

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/active-tasks"

Lihat tugas yang sudah selesai

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/completed-tasks"

Lihat semua tugas

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/all-tasks"

Perintah di atas membuka fitur tampilan daftar aplikasi, menampilkan tugas yang difilter menurut status penyelesaian yang ditentukan di setiap jalur akhir deep link.

Menambahkan BII

Perluas deep link pemfilteran tugas ke Asisten Google, dengan menentukan BII Fitur buka aplikasi, yang dikonfigurasi untuk membuka link ini di actions.xml.

Tentukan BII dengan mengupdate actions.xml, yang terletak di direktori project contoh app/src/main/res/xml, dengan kode berikut:

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        //TODO: Handle intent parameters

        //TODO: Handle action fulfillment

    </action>
</actions>

Menangani parameter intent menggunakan inventaris inline

Parameter Intent mewakili elemen yang diekstrak dari kueri pengguna. Contohnya, jika pengguna mengucapkan misalnya, "Ok Google, pesan pizza dari ExampleApp", Asisten akan mengekstrak "pizza" ke dalam parameter intent food.item schema.org, dan meneruskan parameter ke action untuk ditangani.

BII Fitur buka aplikasi mendukung satu parameter, feature, yang mewakili fitur aplikasi yang diekstrak dari kueri pengguna. Inventaris inline diperlukan untuk parameter ini, menyediakan Asisten dengan kumpulan nama fitur aplikasi yang didukung agar sesuai dengan nilai parameter.

Untuk menangani parameter intent feature, update actions.xml dengan kode berikut:

actions.xml

<?xml version="1.0" encoding="utf-8"?>

<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        <parameter name="feature">
            <entity-set-reference entitySetId="FeatureEntitySet" />
        </parameter>

        //TODO: Handle action fulfillment

    </action>
</actions>

Dengan kode contoh di atas, Anda menginstruksikan Asisten untuk mencocokkan nilai parameter fitur dengan inventaris inline, FeatureEntitySet, yang ditentukan sebagai entity-set-reference di tag parameter.

Tentukan inventaris inline untuk BII Anda dengan menambahkan entity-set berikut ke actions.xml, di bawah elemen action:

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action>
       ...
    </action>

    <entity-set entitySetId="FeatureEntitySet">
        <entity  url="https://todo.androidappactions.com/completed-tasks"
            name="completed tasks" alternateName="@array/completed_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/active-tasks"
            name="active tasks" alternateName="@array/active_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/all-tasks"
            name="all tasks" alternateName="@array/all_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/statistics"
            name="statistics" alternateName="@array/statistics_synonyms"/>
    </entity-set>
</actions>

Pada kode di atas, Anda menentukan inventaris inline, yang ditampilkan sebagai elemen entity-set yang berisi empat elemen entity. Saat pengguna mengaktifkan BII ini dengan permintaan, Asisten akan mencocokkan nilai parameter feature dengan atribut name dari entity, dengan meneruskan url dari entity yang cocok ke fulfillment Anda.

Contohnya, jika pengguna mengatakan misalnya, "Ok Google, tampilkan tugas yang telah saya selesaikan di ExampleApp," Asisten mencocokkan nilai parameter intent feature, "tugas yang sudah selesai", ke inventaris entity yang sesuai. Asisten akan meneruskan URL terkait, https://todo.androidappactions.com/completed-tasks, ke fulfillment Anda.

Menentukan fulfillment action

Untuk memenuhi action, tentukan elemen fulfillment di actions.xml untuk menangani URL yang diteruskan oleh Asisten. Tambahkan fulfillment ke action Anda menggunakan kode berikut:

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        ... //Parameter definition

        <fulfillment urlTemplate="{@url}"/>
        <fulfillment urlTemplate="https://todo.androidappactions.com/all-tasks"/>

    </action>
   ...
</actions>

Dengan contoh di atas, Anda menentukan dua elemen fulfillment. Yang pertama memicu deep link yang dihasilkan Asisten dari parameter feature, direpresentasikan sebagai placeholder {@url} dalam atribut urlTemplate. fulfillment kedua adalah penggantian yang membuka tampilan tugas, menampilkan daftar tugas yang tidak difilter, untuk situasi saat parameter feature tidak ada, atau jika inventaris inline element yang cocok tidak dapat ditemukan.

Menguji Action Aplikasi Anda

Selama pengembangan dan pengujian, Anda menggunakan Alat Uji Action Aplikasi untuk melihat pratinjau Action Aplikasi dengan Asisten di perangkat pengujian. Anda juga dapat menggunakan alat untuk menyesuaikan parameter intent untuk Action Aplikasi, guna menguji bagaimana action Anda menangani berbagai cara yang mungkin digunakan pengguna untuk meminta Asisten menjalankannya.

Uji action aplikasi Anda dengan alat pengujian dengan mengikuti langkah-langkah berikut:

  1. Hubungkan perangkat pengujian Android fisik Anda, atau mulai emulator Android
  2. Buka Tools > App Actions > App Actions Test Tool. Anda mungkin diminta untuk login ke Android Studio. Gunakan akun yang sama yang digunakan sebelumnya dengan Konsol Google Play.
  3. Di kolom Invocation Name, masukkan "Daftar Tugas".
  4. Jika bahasa Asisten Anda bukan "Bahasa Inggris" (en), masukkan bahasa yang cocok dengan bahasa Asisten di kolom Lokal.
  5. Klik Create Preview.
  6. Menggunakan menu drop-down Konfigurasi, pilih intent actions.intent.OPEN_APP_FEATURE.
  7. Di kotak fitur, perbarui nilai "Histori" default dengan "Tugas selesai".
  8. Klik Run.

Sebagai alternatif, Anda dapat menggunakan nama panggilan langsung di aplikasi Asisten pada perangkat untuk mencoba Action Aplikasi. Misalnya, Anda bisa mengucapkan "Ok Google, tampilkan tugas yang sudah selesai di Daftar Tugas".

BII Get thing memperluas fungsi penelusuran dalam aplikasi ke Asisten Google. Pada langkah ini, Anda menerapkan dan menguji BII Get thing, yang memungkinkan pengguna menelusuri tugas tertentu dalam aplikasi contoh.

Aplikasi contoh memiliki deep link yang sudah ada untuk fungsi penelusuran dalam aplikasi. Sebelum menerapkan BII Anda, gunakan adb untuk memverifikasi bahwa deep link ini memenuhi perilaku Action Aplikasi yang diidentifikasi.

Uji deep link penelusuran dengan perintah adb berikut:

# GET_THING deep link: in-app search
adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/search?q=milk"

Perintah di atas memicu deep link yang memuat aktivitas daftar item yang difilter ke item yang berisi kueri penelusuran, "rumah".

Menambahkan BII

Selama Action Aplikasi terkait penelusuran, Asisten mengekstrak istilah penelusuran dari kueri pengguna ke parameter intent thing.name. Asisten kemudian membuat URL untuk fulfillment dengan memetakan parameter ke dalam template URL yang Anda tentukan di elemen fulfillment.

Untuk menentukan BII Get thing di aplikasi Anda, update actions.xml dengan action baru ini:

Actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
   <action intentName="actions.intent.OPEN_APP_FEATURE">...</action>

   <action intentName="actions.intent.GET_THING">

        <parameter-mapping
                intentParameter="thing.name"
                urlParameter="q"/>

        <fulfillment urlTemplate="https://todo.androidappactions.com/search?q={q}">
        </fulfillment>

   </action>

   ...
</actions>

Pada contoh di atas, elemen parameter-mapping menetapkan parameter intent thing.name ke nilai "q" dari atribut urlParameter elemen fulfillment. Asisten kemudian membuat deep link dengan memetakan nilai urlParameter ke placeholder "{q}" di fulfillment urlTemplate.

Menguji Action Aplikasi Anda

Untuk menguji penelusuran dalam aplikasi untuk aplikasi Anda dari Asisten, ikuti langkah-langkah berikut:

  1. Hubungkan perangkat pengujian Android fisik Anda, atau mulai emulator Android
  2. Buka Tools > App Actions > App Actions Test Tool.
  3. Klik Update Preview.
  4. Menggunakan menu drop-down Konfigurasi, pilih intent actions.intent.GET_THING. Ubah nilai "nama" dari "sepatu lari" menjadi "susu".
  5. Klik Run.

Dalam pengujian ini, BII Get Thing menggunakan atribut name untuk menelusuri tugas yang berisi "rumah" dalam aplikasi. Seperti Action Aplikasi sebelumnya, Anda dapat menguji action menggunakan alat uji, atau cukup ucapkan "Ok Google, telusuri campuran kue di Daftar Tugas", atau frasa penelusuran lainnya, di perangkat uji.

Selamat!

Kini Anda memiliki kemampuan untuk mengaktifkan hampir semua aplikasi Android agar berfungsi dengan Asisten Google, menggunakan BII umum.

Yang telah kita bahas

Dalam codelab ini, Anda telah mempelajari:

  • Cara mengizinkan pengguna mempelajari fitur aplikasi tertentu secara mendalam, menggunakan Asisten.
  • Cara pengguna dapat mengakses penelusuran dalam aplikasi, dari Asisten.
  • Cara menguji BII umum menggunakan Alat Uji Action Aplikasi.

Langkah berikutnya

Dari sini, Anda dapat mencoba menyempurnakan lebih lanjut aplikasi Daftar Tugas. Untuk mereferensikan project yang sudah selesai, lihat –master cabang repo di GitHub.

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

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

Ikuti kami di Twitter @ActionsOnGoogle untuk mengikuti terus pengumuman terbaru kami, dan kirim tweet ke #AoGDevs untuk membagikan yang telah Anda buat.

Survei masukan

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