Membuat Action Canvas Interaktif untuk Asisten Google dengan Action Builder
Tentang codelab ini
1. Ringkasan
Actions on Google adalah sebuah platform developer yang memungkinkan Anda membuat software untuk memperluas fungsi Asisten Google, asisten pribadi virtual Google, di lebih dari 1 miliar perangkat, termasuk smart speaker, ponsel, mobil, TV, headphone, dan lainnya. Pengguna berinteraksi dengan Asisten Google melalui percakapan untuk menyelesaikan berbagai hal, seperti membeli bahan makanan atau memesan transportasi online (untuk melihat daftar lengkap opsi yang saat ini bisa dilakukan, buka direktori Action). Sebagai developer, Anda dapat menggunakan Actions on Google untuk dengan mudah membuat dan mengelola pengalaman percakapan yang menyenangkan dan berguna antara pengguna dan layanan fulfillment pihak ketiga Anda sendiri.
Codelab ini adalah modul lanjutan dan ditujukan bagi pembaca yang sudah memiliki pengalaman dalam membuat Action untuk Asisten Google. Jika Anda tidak memiliki pengalaman pengembangan sebelumnya dengan Actions on Google, kami sangat menyarankan Anda untuk membiasakan diri dengan platform ini dengan mengikuti codelab pengantar kami ( Level 1 dan Level 2 ). Modul-modul ini akan memberikan panduan tentang serangkaian fitur yang dapat membantu Anda memperluas fungsi Action dan meningkatkan jumlah audiens.
Di codelab ini, Anda akan menggunakan Canvas Interaktif, sebuah framework yang dibuat di Asisten Google, untuk menambahkan game layar penuh ke Action Percakapan. Game ini adalah sebuah aplikasi web interaktif yang dikirim Asisten sebagai respons kepada pengguna dalam percakapan. Selanjutnya, pengguna dapat memainkan game melalui input suara atau teks di layar smart dan perangkat seluler Android.
Anda tidak akan membuat keseluruhan gamenya sendiri, melainkan hanya akan men-deploy game yang sebagian telah selesai, yang disebut Snow Pal dan menambahkan logika game sambil mengikuti codelab ini. Snow Pal adalah variasi dari game tradisional Hangman (isi huruf untuk tebak kata); game ini memberikan sejumlah ruang kosong yang membentuk sebuah kata, dan Anda menebak huruf yang menurut Anda mungkin ada dalam kata tersebut. Setiap salah menebak, Snow Pal akan meleleh sedikit demi sedikit. Anda akan memenangkan game jika dapat mengetahui kata yang dimaksud sebelum Snow Pal meleleh sepenuhnya.
Gambar 1. Game Snow Pal yang sudah selesai sebagian.
Yang akan Anda buat
Di codelab ini, Anda akan membuat Action yang menggunakan Canvas Interaktif. Action Anda akan memiliki fitur berikut:
- Game kata layar penuh yang dapat dimainkan pengguna dengan suara
- Tombol yang dapat ditekan pengguna untuk memulai game
- Tombol yang dapat ditekan pengguna untuk bermain game lagi
Setelah menyelesaikan codelab ini, Action lengkap Anda akan memiliki alur percakapan berikut:
Asisten: Welcome to Snow Pal! Would you like to start playing the game?
Pengguna: Yes
Asisten: Try guessing a letter in the word or guessing the word.
Pengguna: I guess the letter E
Asisten: Let's see if your guess is there...E is right. Right on! Good guess.
Pengguna terus menebak huruf, atau menebak kata tersembunyi itu sendiri, sampai game berakhir.
Yang akan Anda pelajari
- Cara membuat dan men-deploy Action Canvas Interaktif
- Cara memperbarui game kata berdasarkan input suara dan sentuh pengguna
- Cara meneruskan data ke aplikasi web menggunakan beberapa metode
- Cara men-debug Action Canvas Interaktif
Yang akan Anda butuhkan
Prasyarat untuk codelab ini meliputi yang berikut:
- Browser web, seperti Chrome
- IDE/editor teks pilihan Anda
- NodeJS, npm, dan git yang sudah diinstal di komputer Anda
Pemahaman tentang JavaScript (ES6) sangat disarankan untuk membantu Anda memahami kode yang digunakan dalam codelab ini.
Opsional: Dapatkan kode contoh lengkap
Di codelab ini, Anda akan mengembangkan sampel dari versi yang belum selesai. Kalau mau, Anda juga dapat memperoleh sampel yang sudah selesai dari repositori GitHub.
2. Pengantar Canvas Interaktif
Canvas Interaktif adalah sebuah framework yang dibuat di atas Asisten Google, yang memungkinkan Anda menambahkan visual dan animasi layar penuh ke Action Percakapan.
Action yang menggunakan Canvas Interaktif cara kerjanya mirip dengan Action Percakapan biasa. Namun, Action Canvas Interaktif memiliki kemampuan tambahan untuk mengirim respons ke perangkat yang membuka aplikasi web layar penuh.
Pengguna memberikan input ke aplikasi web melalui suara atau sentuhan sampai percakapan selesai.
Gambar 2. Action yang dibuat dengan Canvas Interaktif.
Di codelab ini, project Anda dibagi menjadi tiga bagian utama berikut:
- Aplikasi web: File aplikasi web berisi kode untuk visual dan animasi aplikasi web Anda, serta logika untuk memperbarui aplikasi web berdasarkan input pengguna.
- Action Percakapan: Action Percakapan berisi logika percakapan Anda, yang mengenali, memproses, dan menanggapi input pengguna.
- Webhook: Webhook menangani logika game. Untuk codelab ini, Anda dapat menganggap webhook sebagai server game.
Di setiap bagian codelab ini, Anda akan mengubah aplikasi web, Action Percakapan, dan webhook untuk menambahkan fungsionalitas ke Action Canvas Interaktif Anda.
Sebagai gambaran, Action Percakapan, webhook, dan aplikasi web di Action Snow Pal bekerja dengan cara berikut:
- Action Percakapan meminta pengguna untuk menebak huruf dalam kata atau menebak seluruh kata.
- Pengguna akan mengatakan "I guess the letter i" ("Saya tebak hurufnya i") ke aplikasi web Snow Pal di layar smart.
- Input pengguna diarahkan ke Action Percakapan Anda, yang ditetapkan dalam project Action Builder dan/atau project Actions SDK Anda.
- Action Percakapan memproses input pengguna dan, tergantung input tersebut, akan memicu logika di webhook yang akan memperbarui aplikasi web, atau mengirim metadata untuk memperbarui aplikasi web secara langsung.
- Aplikasi web diperbarui untuk menampilkan di mana huruf muncul dalam kata tersebut, dan pengguna diminta untuk menebak lagi.
Anda akan mempelajari lebih lanjut tentang cara kerja Canvas Interaktif di bagian Memahami Infrastruktur Canvas Interaktif. Setelah kini mengetahui dasar-dasarnya, Anda dapat mulai menyiapkan lingkungan untuk codelab ini.
3. Penyiapan
Memeriksa setelan izin Google Anda
Untuk menguji Action yang Anda buat di codelab ini, Anda perlu mengaktifkan izin yang diperlukan sehingga simulator Konsol Actions dapat mengakses Action Anda. Untuk mengaktifkan izin, ikuti langkah-langkah berikut:
- Buka halaman Kontrol Aktivitas.
- Login dengan akun Google Anda, jika diperlukan.
- Aktifkan izin berikut:
- Aktivitas Web & Aplikasi
- Di bagian Aktivitas Web & Aplikasi, centang kotak di samping Sertakan histori Chrome dan aktivitas dari situs, aplikasi, dan perangkat yang menggunakan layanan Google.
Menginstal antarmuka command line gaction
Di codelab ini, Anda menggunakan alat antarmuka command line (CLI) gaction untuk menyinkronkan project Action antara Konsol Actions dan sistem file lokal Anda.
Untuk menginstal CLI gaction, ikuti petunjuk di bagian Menginstal Alat Command Line Gaction.
Menginstal antarmuka command line Firebase
Dengan Antarmuka Command Line (CLI) Firebase, Anda dapat men-deploy project Action ke Cloud Functions dan menghosting aplikasi web Anda.
Codelab ini menggunakan npm untuk menginstal Firebase CLI. Pastikan Anda menginstal npm, yang biasanya disertai dengan Node.js.
Untuk menginstal atau mengupgrade CLI, buka terminal dan jalankan perintah npm
berikut:
npm install -g firebase-tools
Untuk memastikan bahwa CLI telah diinstal dengan benar, jalankan perintah berikut:
firebase --version
Pastikan versi Firebase CLI adalah 8 atau lebih tinggi, sehingga memiliki semua fitur terbaru yang diperlukan untuk Cloud Functions. Jika tidak, jalankan npm install -g firebase-tools
untuk melakukan upgrade.
Untuk login ke Firebase, jalankan perintah berikut:
firebase login
Saat login ke Firebase, pastikan Anda menggunakan akun Google yang sama dengan yang digunakan untuk membuat project Action Anda.
Melakukan cloning repositori
Di bagian ini, Anda akan meng-clone file yang diperlukan untuk codelab ini. Untuk mendapatkan file ini, ikuti langkah berikut:
- Buka terminal, lalu ubah ke direktori tempat Anda biasanya menyimpan project coding. Jika tidak punya, ubah ke direktori beranda Anda.
- Untuk meng-clone repositori ini, jalankan perintah berikut di terminal Anda:
git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs
Buka direktori start/
. Repositori ini berisi direktori penting berikut yang akan Anda kerjakan:
public/
- Direktori ini berisi kode HTML, CSS, dan JavaScript untuk aplikasi web Anda.sdk/custom/
- Direktori ini berisi logika Action Percakapan (scene, intent, dan tipe).sdk/webhooks/
- Direktori ini adalah webhook Anda dan berisi logika game.
Gambar 3. Struktur kode direktori start
.
4. Menyiapkan project Action
Di bagian ini, Anda akan membuat dan mengonfigurasi project Action, mengirimkan kode dari repositori yang di-clone ke Konsol Actions dengan CLI gaction, serta men-deploy aplikasi web dan webhook Anda.
Membuat project Action
Project Action Anda adalah container untuk Action Anda. Untuk membuat project Action di codelab ini, ikuti langkah-langkah berikut:
- Buka Konsol Actions.
- Klik New project.
- Ketikkan Project name, misalnya
canvas-codelab
. Nama ini untuk referensi internal Anda. Nanti Anda dapat menetapkan nama eksternal untuk project Anda.
- Klik Create project.
- Di layar What kind of Action do you want to build?, pilih kartu Game.
- Klik Next.
- Pilih kartu Blank project, lalu klik Start building.
Menyimpan Project ID untuk Action Anda
Project ID adalah ID unik untuk Action Anda. Anda memerlukan Project ID untuk beberapa langkah dalam codelab ini.
Untuk mengambil Project ID, ikuti langkah berikut:
- Di Konsol Actions, klik tiga titik vertikal di kanan atas.
- Klik Project settings.
- Salin Project ID.
Mengaitkan akun penagihan
Untuk men-deploy fulfillment Anda nanti dalam codelab ini menggunakan Cloud Functions, Anda harus mengaitkan akun penagihan dengan project Anda di Google Cloud. Jika sudah memiliki akun penagihan, Anda dapat mengabaikan langkah-langkah berikut.
Untuk mengaitkan akun penagihan dengan project Anda, ikuti langkah-langkah berikut:
- Buka halaman penagihan Google Cloud Platform.
- Klik Tambahkan akun penagihan.
- Masukkan informasi pembayaran Anda dan klik Mulai uji coba gratis saya atau Kirim dan aktifkan penagihan.
- Klik tab Project Saya di bagian atas halaman.
- Klik tiga titik pada Action di samping project Action untuk codelab ini.
- Klik Ubah penagihan.
- Di menu drop-down, pilih akun penagihan yang sudah Anda konfigurasi. Klik Tetapkan akun.
Agar tidak dikenai biaya lebih, ikuti langkah-langkah di bagian "Membersihkan project" pada halaman "Langkah berikutnya" di akhir codelab ini.
Men-deploy aplikasi web
Di bagian ini, Anda akan men-deploy aplikasi web (game Snow Pal) menggunakan Firebase CLI. Setelah men-deploy, Anda dapat memperoleh URL untuk aplikasi web dan melihat tampilan game di browser.
Untuk men-deploy aplikasi web, ikuti langkah-langkah berikut:
- Di terminal, buka direktori
start/
. - Jalankan perintah berikut, ganti
{PROJECT_ID}
dengan project ID Anda:
firebase deploy --project {PROJECT_ID} --only hosting
Setelah beberapa menit, Anda akan melihat "Deploy complete!", yang menunjukkan bahwa Anda telah berhasil men-deploy aplikasi web Snow Pal ke Firebase.
Untuk melihat game Snow Pal di browser, ikuti langkah berikut:
- Dapatkan URL Hosting yang disediakan di output terminal Anda. URL tersebut seharusnya dalam format berikut:
https://{PROJECT_ID}.web.app
- Tempelkan URL di browser. Anda akan melihat layar awal game Snow Pal dengan tombol
Start Game
:
Menambahkan URL aplikasi web dan project ID ke project Action
Selanjutnya, tambahkan URL aplikasi web dan project ID Anda ke file actions.intent.MAIN.yaml
. Menambahkan URL aplikasi web memungkinkan Action Percakapan mengetahui URL mana data akan dikirimkan, sementara menambahkan project ID di settings.yaml
memungkinkan Anda mengirim file yang didownload ke project yang tepat di Konsol Actions.
Untuk menambahkan URL aplikasi web dan project ID, ikuti langkah-langkah berikut:
- Buka file
start/sdk/custom/global/actions.intent.MAIN.yaml
di editor teks. - Di kolom
url
, ganti string placeholder dengan URL aplikasi web Anda. - Buka file
start/sdk/settings/settings.yaml
di editor teks. - Di kolom
projectId
, ganti string placeholder dengan project ID Anda.
Mengirim project ke Konsol Actions
Untuk memperbarui Konsol Actions dengan project lokal, Anda harus mengirim project Action ke Konsol Actions. Untuk melakukannya, ikuti langkah-langkah berikut:
- Ubah ke direktori
sdk
:
cd sdk/
- Untuk menyalin konfigurasi sistem file lokal ke Konsol Actions, jalankan perintah berikut:
gactions push
Men-deploy webhook
Saat tadi menjalankan gactions push
, Anda mengimpor kode webhook awal ke Konsol Actions. Untuk codelab ini, Anda bisa mengedit kode webhook Anda dari dalam Konsol Actions. Pada tahap ini, Anda dapat men-deploy webhook dari konsol Actions.
Untuk men-deploy webhook, ikuti langkah-langkah berikut:
- Di Konsol Actions, klik Develop di navigasi.
- Klik tab Webhook di navigasi.
- Klik Deploy Fulfillment.
Butuh waktu beberapa menit untuk Cloud Functions melakukan penyediaan (provisioning) dan menerapkan fulfillment Anda. Anda akan melihat pesan Cloud Function deployment in progress... di atas editor kode. Jika kode berhasil di-deploy, pesan akan berubah menjadi Your Cloud Function deployment is up to date.
Menguji di simulator
Sampai di sini, Action Anda telah ditautkan ke aplikasi web. Anda dapat menggunakan simulator Konsol Actions untuk memastikan bahwa aplikasi web muncul saat Anda memanggil Action.
Untuk menguji Action Anda, ikuti langkah-langkah berikut:
- Di menu navigasi Konsol Actions, klik Test.
- Ketik
Talk to Snow Pal sample
di kolom Input, lalu tekanEnter
. - Ketik
Yes
di kolom Input dan tekanEnter
. Atau, klik tombol Start Game di bagian tengah layar.
Anda belum mengonfigurasi logika untuk menebak huruf atau menebak kata, jadi jika Anda menebak kata atau huruf, Anda akan menerima respons, "...Incorrect. Keep on trying! It looks like we need to add more functionality to have this work properly" ("Salah. Teruslah mencoba! Sepertinya kami perlu menyempurnakan fungsionalitas game ini").
5. Memahami infrastruktur Canvas Interaktif
Untuk project ini, fungsionalitas tersebut dibagi menjadi tiga komponen utama: Action Percakapan, aplikasi web, dan webhook. Perhatikan bahwa ini adalah satu model untuk Anda menyiapkan Action, dan diatur seperti ini untuk memperjelas fungsionalitas inti Canvas Interaktif.
Bagian berikutnya memberikan penjelasan lebih lengkap tentang bagaimana Action Percakapan, webhook, dan aplikasi web bekerja bersama, serta elemen penting Canvas Interaktif lainnya.
Action Percakapan
Komponen Action Percakapan dari Action Anda menangani hal berikut: mengenali input pengguna, memprosesnya, dan mengirimkannya ke scene yang sesuai. Dan di sana, respons kepada pengguna akan dibuat. Misalnya, jika pengguna mengatakan "I guess the letter e" ("Saya tebak hurufnya e") di game Snow Pal, Action Percakapan Anda mengekstrak huruf tersebut sebagai sebuah parameter intent dan meneruskannya ke logika game yang sesuai, yang menentukan apakah tebakan tersebut benar, lalu memperbarui aplikasi web berdasarkan informasi tersebut. Anda dapat melihat dan mengubah logika percakapan ini di Action Builder, yaitu sebuah IDE berbasis web di Konsol Actions. Screenshot berikut menunjukkan bagian dari Action Percakapan dalam Action Builder:
Gambar 4. Visualisasi Main invocation
di Action Builder.
Screenshot ini menampilkan Main invocation
untuk Action Anda, yang dicocokkan dengan pengguna saat mereka mengucapkan frasa seperti "Okay Google, talk to Snow Pal Sample" ("Ok Google, bicara dengan contoh Snow Pal"). Saat pengguna memanggil Action Anda, Main invocation
akan mengirim perintah dengan respons canvas
, yang berisi URL aplikasi web Anda.
Respons canvas
pertama dalam Action Anda harus menyertakan URL aplikasi web. Respons ini memberi tahu Asisten untuk merender aplikasi web pada alamat tersebut di perangkat pengguna. Respons canvas
tambahan di Action Builder dapat menyertakan kolom, send_state_data_to_canvas_app
, yang disetel ke true
. Kolom ini mengirimkan nama intent dan segala nilai parameter ke aplikasi web saat intent tersebut cocok, dan aplikasi web akan diperbarui berdasarkan data ini dari input pengguna.
Webhook
Untuk codelab ini, webhook berisi logika game (Anda dapat menganggap webhook seperti sebuah server game). Logika game mencakup elemen-elemen seperti menentukan apakah tebakan pengguna benar atau salah, atau apakah pengguna menang atau kalah, dan membuat respons berdasarkan hasilnya. Anda dapat mengubah webhook di Action Builder.
Ketika Action Anda perlu menjalankan logika game, Action Builder akan melakukan panggilan ke webhook. Misalnya, intent guess
di scene Game
melakukan panggilan webhook ke pengendali guess
, yang kemudian menjalankan logika untuk menentukan apakah tebakan pengguna benar atau tidak. Webhook dapat menyertakan respons Canvas
dalam pengendali, yang dipetakan ke file aplikasi web dan memperbarui web dengan tepat.
Aplikasi web
Gambar 5. Representasi visual dari interaksi antara Action Percakapan, webhook, dan aplikasi web di sebuah Action Canvas Interaktif.
File aplikasi web berisi kode untuk visual dan animasi aplikasi web Anda, serta logika untuk memperbarui aplikasi web berdasarkan input pengguna. Anda dapat memodifikasi file aplikasi web di editor teks dan men-deploy perubahan ini menggunakan Firebase CLI.
Melakukan komunikasi antara Action Percakapan dan aplikasi web
Anda perlu mengaktifkan komunikasi antara Action Percakapan dan aplikasi web Anda, sehingga aplikasi web dapat diperbarui berdasarkan input pengguna. Misalnya, jika pengguna mengatakan "I guess the letter f" ("Saya tebak hurufnya f"),
Action Percakapan perlu memberikan huruf "f" pada aplikasi web agar aplikasi web bisa melakukan perubahan yang sesuai. Untuk meneruskan input pengguna dari Action Percakapan ke aplikasi web, Anda harus memuat di Interactive Canvas API.
Skrip untuk API ini disertakan dalam /public/index.html
, yang merupakan file HTML utama untuk game Snow Pal. File ini menentukan bagaimana UI Anda terlihat dan dimuat dalam beberapa skrip:
index.html
<!-- Load Assistant Interactive Canvas API -->
<script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>
Untuk memperbarui aplikasi web berdasarkan input pengguna, Anda juga harus mendaftarkan dan mengonfigurasi callback di file aplikasi web Anda. Callback memungkinkan aplikasi web Anda menanggapi informasi atau permintaan dari Action Percakapan.
Di /public/js/action.js
, ada sebuah class yang telah dikonfigurasi bernama Action
untuk mendeklarasikan dan mendaftarkan callback. Class Action
adalah wrapper Interactive Canvas API. Saat aplikasi web dibuat dengan fungsi create()
di scene.js
, instance Action
baru akan dibuat dan setCallbacks()
akan dipanggil, seperti yang ditampilkan dalam cuplikan berikut:
scene.js
// Set assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register assistant action callbacks.
this.assistant.setCallbacks();
Fungsi setCallbacks()
ditentukan di class Action
, /public/js/action.js
. Fungsi ini mendeklarasikan callback dan mendaftarkannya ke Interactive Canvas API saat game dibuat:
setCallbacks() {
// Declare the Interactive Canvas action callbacks.
const callbacks = {
onUpdate: (data) => {
...
// Called by the Interactive Canvas web app once web app has loaded to
// register callbacks.
this.canvas.ready(callbacks);
}
Fungsi setCallbacks()
mendeklarasikan callback onUpdate()
, yang dipanggil setiap kali Anda mengirim respons Canvas
.
Bagian berikutnya menjelaskan cara mengonfigurasi kode spesifik project ini untuk meneruskan data dari Action Percakapan ke aplikasi web.
Memperbarui aplikasi web berdasarkan input pengguna
Di codelab ini, Anda menggunakan peta perintah untuk memperbarui aplikasi web berdasarkan input pengguna. Misalnya, saat intent start_game
dicocokkan di scene Welcome
, respons canvas
yang disertakan dalam pesan akan dikirim ke aplikasi web. onUpdate()
mengurai metadata dari respons canvas
dan memanggil perintah START_GAME
, yang kemudian memanggil fungsi start()
di scene.js
dan memperbarui aplikasi web untuk memulai sesi game baru.
Fungsi start()
di scene.js
juga memanggil fungsi updateCanvasState()
, yang menggunakan metode setCanvasState()
untuk menambahkan data status yang dapat diakses webhook Anda.
Metode updateCanvasState()
dipanggil di akhir setiap perintah (Anda akan menambahkan perintah ini di sepanjang codelab ini) dan memperbarui status aplikasi web. Setiap kali updateCanvasState()
dipanggil, nilai untuk displayedWord
dan incorrectGuesses
diperbarui berdasarkan status saat ini:
scene.js
...
updateCanvasState() {
window.interactiveCanvas.setCanvasState({
correctWord: this.word.text,
displayedWord: this.word.displayText.text,
incorrectGuesses: this.incorrectGuesses,
});
Status yang telah diperbarui akan tersedia untuk percakapan berikutnya. Anda dapat mengakses status ini di webhook melalui conv.context.canvas.state
, seperti yang ditampilkan dalam cuplikan kode berikut:
index.js
...
let displayedWord = conv.context.canvas.state.displayedWord;
...
6. Menambahkan fungsi menebak
Di bagian ini, Anda akan menambahkan fungsi guess
ke Action Anda, yang memungkinkan pengguna menebak huruf, atau kata itu sendiri.
Action Percakapan
Di bagian Menguji di Simulator, Anda menerima respons yang menyertakan, "It looks like we need to add more functionality to have this work properly" ("Sepertinya kami perlu menyempurnakan fungsionalitas game ini"). Sekarang, Anda dapat menghapus pesan tersebut di Konsol Actions sehingga Anda hanya memanggil webhook (di scene Game
, intent guess
sudah dikonfigurasi untuk melakukan panggilan webhook saat intent dicocokkan).
Untuk menghapus pesan statis saat intent guess
dicocokkan, ikuti langkah berikut:
- Di Konsol Actions, klik Scenes di navigasi.
- Klik Game untuk membuka scene
Game
. - Klik When guess is matched di bagian Custom intent handling. Hapus Send prompts untuk menghapus pesan.
- Klik Save.
Webhook
Di bagian ini, Anda akan memperbarui webhook dengan logika yang memetakan tebakan yang benar atau salah ke logika dalam file aplikasi web, yang kemudian memperbarui aplikasi web berdasarkan informasi yang didapat. Pengendali intent guess
sudah dikonfigurasikan di webhook, sehingga Anda hanya perlu menambahkan respons Canvas
ke intent ini untuk memicu logika yang memperbarui aplikasi web.
Untuk memperbarui webhook, ikuti langkah-langkah berikut:
- Di Konsol Actions, klik Webhook di navigasi.
- Tambahkan kode berikut ke
index.js
di bagian pengendaliguess
:
index.js (Bagian A):
// Add SECTION A `conv.add(new Canvas({` content here
conv.add(new Canvas({
data: {
command: 'CORRECT_ANSWER',
displayedWord: displayedWord
},
}));
index.js (Bagian B):
// Add SECTION B `conv.add(new Canvas({` content here
conv.add(new Canvas({
data: {
command: 'INCORRECT_ANSWER',
},
}));
- Klik Save Fulfillment.
- Klik Deploy Fulfillment. Saat deployment selesai, pesan berikut akan muncul di atas editor Anda Your Cloud Function deployment is up to date.
Aplikasi web
Anda kini dapat mengonfigurasi aplikasi web untuk menangani perintah CORRECT_ANSWER
dan INCORRECT_ANSWER
.
- Buka
public/js/action.js
di editor teks Anda. - Perbarui aplikasi web untuk menangani perintah
CORRECT_ANSWER
danINCORRECT_ANSWER
:
action.js (Bagian C):
// Add SECTION C `CORRECT_ANSWER: (params) => {` content here
CORRECT_ANSWER: (params) => {
this.gameScene.correctAnswer(params);
},
INCORRECT_ANSWER: (params) => {
this.gameScene.incorrectAnswer();
},
- Jalankan perintah berikut untuk memperbarui aplikasi web:
firebase deploy --project {PROJECT_ID} --only hosting
Menguji Action Anda di simulator
Sampai di sini, Action Anda dapat mengenali apakah tebakan benar atau salah dan memperbarui aplikasi web sesuai informasi yang didapat.
Untuk menguji Action Anda, ikuti langkah-langkah berikut:
- Di menu navigasi, klik Test.
- Ketik
Talk to Snow Pal sample
di kolom Input, lalu tekanEnter
. - Ketik Yes di kolom Input dan tekan
Enter
. Atau, klik tombol Yes. - Ketik huruf yang ingin Anda tebak di kolom input dan tekan
Enter
.
Memahami kode
Di bagian sebelumnya, Anda menambahkan kode yang memungkinkan pengguna menebak huruf dalam game Anda, dan membuat tebakan tersebut terefleksi pada katanya, atau pada si Snow Pal. Sebagai gambaran, Anda membuat panggilan webhook di Action Builder saat intent guess
dicocokkan, yang kemudian meneruskan data ke aplikasi web Anda untuk memperbaruinya dengan sesuai. Misalnya, jika pengguna menebak huruf dalam game Snow Pal yang memang ada dalam katanya, aplikasi web akan diperbarui untuk menampilkan huruf pada posisi yang benar.
Untuk Action yang menggunakan Canvas Interaktif, umumnya data diteruskan dari webhook ke aplikasi web melalui alur seperti ini:
- Input pengguna cocok dengan intent yang menyertakan respons
Canvas
. - Action Percakapan atau webhook mengirim respons
Canvas
, yang memicu callbackonUpdate()
. - Callback
onUpdate()
memetakan ke logika kustom yang memperbarui aplikasi web.
Khususnya untuk project ini, kode bekerja dengan cara berikut:
- Saat pengguna cocok dengan intent
guess
, Action Builder mengekstrak huruf dari input pengguna sebagai parameter. - Action Builder memanggil pengendali
guess
di webhook Anda, yang berisi logika untuk menentukan apakah huruf yang ditebak pengguna muncul di kata. - Pengendali
guess
berisi dua responsCanvas
— satu dijalankan saat huruf benar, dan satu lagi dijalankan saat huruf salah. Setiap responsCanvas
akan meneruskan data yang sesuai (perintahCORRECT_ANSWER
atauINCORRECT_ANSWER
) ke aplikasi web. - Data yang terdapat dalam kolom
data
dari responsCanvas
diteruskan ke metodeonUpdate()
diaction.js
.onUpdate()
memanggil perintah yang sesuai dalam peta perintah discene.js
. - Perintah ini memetakan fungsi
correctAnswer()
danincorrectAnswer()
discene.js
. Fungsi ini memperbarui aplikasi web dengan tepat untuk merefleksikan tebakan pengguna dan memanggilsetCanvasState()
untuk mengirim data status dari aplikasi web ke webhook Anda.
7. Menambahkan fungsi menang/kalah
Di bagian ini, Anda akan menambahkan fungsi menang dan kalah ke Action Anda, yang mencakup logika untuk menentukan apakah pengguna menang atau kalah dan logika untuk memperbarui gambar aplikasi web berdasarkan hasil pengguna.
Action Percakapan
Fungsi yang menangani apakah pengguna menang atau kalah akan dikonfigurasi dalam intent guess
, sehingga Anda tidak perlu melakukan konfigurasi tambahan apa pun di Action Builder.
Webhook
Di bagian ini, Anda akan memperbarui webhook dengan logika yang menangani saat pengguna menang atau kalah, dan memetakan ke logika aplikasi web yang memperbarui game dengan layar menang atau kalah yang tepat.
Untuk memperbarui webhook, ikuti langkah-langkah berikut:
- Di Konsol Actions, klik Webhook di navigasi.
- Tambahkan kode berikut ke
index.js
di bagian pengendaliguess
:
index.js (Bagian D):
// Add SECTION D `if (userHasWon)` content here
if (userHasWon) {
conv.add(`<speak>Let's see if your guess is there...<break
time='2500ms'/> ${guess} is right. That spells ${correctWord}!
${randomArrayItem(WIN_RESPONSES)}</speak>`);
conv.add(new Canvas({
data: {
command: 'WIN_GAME',
displayedWord: displayedWord
},
}));
conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
} else {
index.js (Bagian E):
// Add SECTION E `}` here
}
index.js (Bagian F):
// Add SECTION F `Check if the user has exceeded the maximum` content here
// Check if the user has exceeded the maximum amount of max guesses allowed.
const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
if (userHasLost) {
conv.add(`<speak>Let's see if your guess is there...<break
time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
conv.add(new Canvas({
data: {
command: 'LOSE_GAME',
},
}));
conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
} else {
index.js (Bagian G):
// Add SECTION G `}` here
}
- Klik Save Fulfillment.
- Klik Deploy Fulfillment. Saat deployment selesai, pesan berikut akan muncul di atas editor Anda Your Cloud Function deployment is up to date.
Di sini, Anda menambahkan dua respons Canvas
dengan perintah WIN_GAME
dan LOSE_GAME
untuk menangani saat pengguna menang atau kalah. Di bagian berikutnya, Anda akan menambahkan fungsi yang memperbarui aplikasi web berdasarkan menang atau kalahnya pengguna.
Aplikasi web
Sekarang Anda dapat mengonfigurasi aplikasi web untuk diperbarui berdasarkan menang atau kalahnya pengguna. Untuk memperbarui aplikasi web, ikuti langkah-langkah berikut:
- Buka
public/js/action.js
di editor teks Anda. - Perbarui aplikasi web Anda untuk menangani perintah
WIN_GAME
danLOSE_GAME
:
action.js (Bagian H):
// Add SECTION H `WIN_GAME: (params) => {` content here
WIN_GAME: (params) => {
this.gameScene.winGame(params);
},
LOSE_GAME: (params) => {
this.gameScene.loseGame();
},
- Jalankan perintah berikut untuk memperbarui aplikasi web:
firebase deploy --project {PROJECT_ID} --only hosting
Menguji Action Anda di simulator
Sampai di sini, Action Anda dapat menangani saat pengguna menang atau kalah, dan memunculkan layar yang sesuai untuk setiap hasil.
Untuk menguji Action Anda, ikuti langkah-langkah berikut:
- Di menu navigasi Konsol Actions, klik Test.
- Ketik
Talk to Snow Pal sample
di kolom Input, lalu tekanEnter
. - Ketik Yes di kolom Input dan tekan
Enter
. Atau, klik tombol Start Game. - Tebak huruf dan kata sampai Anda menang atau kalah.
Jika Anda meminta untuk bermain lagi, Anda akan menerima pesan yang menunjukkan bahwa fungsi yang diperlukan untuk bermain lagi belum ditambahkan. Anda akan menambahkan fungsi ini di bagian berikutnya.
Memahami kode
Fungsi menang dan kalah ini bekerja dengan cara yang sama seperti fungsi menebak — input pengguna dicocokkan dengan intent guess
, dan webhook Anda mengevaluasi tebakan pengguna. Jika tebakannya benar, kode akan memeriksa apakah pengguna menang; dan jika ya, perintah WIN_GAME
akan dikirim ke aplikasi web. Jika tebakannya salah, kode akan memeriksa apakah pengguna kalah; jika ya, perintah LOSE_GAME
akan dikirim ke aplikasi web. Perintah ini memicu fungsi winGame()
dan loseGame()
di scene.js
, yang memperbarui aplikasi web untuk menampilkan layar menang atau kalah dan memperbarui status game.
8. Menambahkan fungsi main lagi
Di bagian ini, Anda akan menambahkan fungsi yang memungkinkan pengguna mengucapkan "Play again" ("Main lagi") atau mengklik tombol Play Again
di aplikasi web untuk memulai game baru. Anda akan mengubah intent play_again
di Action Builder untuk mengirim respons canvas
yang memperbarui aplikasi web dengan tepat, dan menambahkan logika yang memicu intent play_again
saat pengguna mengklik tombol Play Again
.
Action Percakapan
Saat menguji Action di bagian sebelumnya, Anda menerima pesan berikut jika mencoba bermain lagi: "That would be great, but we will build this functionality in a later section. For now, just reset the Action" ("Seru sekali kalau bisa main lagi, tapi kita akan buat fungsi itu nanti. Untuk sekarang, reset saja Action-nya") Anda sekarang dapat menghapus pesan ini dan menggantinya dengan yang menanggapi pengguna saat mereka meminta bermain lagi ("Okay, here's to another game!" "Oke, ayo kita main lagi"), dan menyertakan respons canvas
untuk memicu aplikasi web untuk memulai game baru.
Untuk memperbarui pesan saat pengguna ingin bermain lagi, ikuti langkah-langkah ini:
- Di Konsol Actions, klik drop-down Scene.
- Klik scene
Game
. - Klik
When play_again is matched
di bagian Custom intent handling. - Ganti pesan dengan yang berikut ini:
candidates: - first_simple: variants: - speech: 'Okay, here's another game!' canvas: sendStateDataToCanvasApp: true
- Klik Save.
Webhook
Di codelab ini, webhook mengelola logika game. Karena fungsi "main lagi" tidak memerlukan validasi logika jenis apa pun, Anda tidak perlu memanggil webhook; Anda dapat mengirim respons canvas
langsung dari Action Builder untuk meneruskan data yang diperlukan ke aplikasi web (Anda telah mengonfigurasinya di bagian sebelumnya).
Aplikasi web
Anda kini dapat mengubah file aplikasi web untuk diperbarui dengan sesuai saat pengguna meminta untuk bermain lagi. Untuk menambahkan fungsi ini, ikuti langkah-langkah berikut:
- Buka
public/js/action.js
di editor teks Anda. - Perbarui aplikasi web untuk menangani perintah
PLAY_AGAIN
:
action.js (Bagian I):
// Add SECTION I `PLAY_AGAIN: (params) => {` content here
PLAY_AGAIN: (params) => {
this.gameScene.start();
},
- Buka
public/js/scene.js
di editor teks Anda. - Perbarui aplikasi web untuk memulai sesi game baru saat pengguna mengklik tombol 'Play Again':
Scene.js (Bagian J):
// Add SECTION J `sendTextQuery` content here
window.interactiveCanvas.sendTextQuery('Play again');
- Jalankan perintah berikut untuk memperbarui aplikasi web:
firebase deploy --project {PROJECT_ID} --only hosting
Menguji Action Anda di simulator
Action Anda kini dapat memulai sesi game baru saat pengguna mengatakan "Play again" atau menekan tombol 'Play Again'.
Untuk menguji Action Anda, ikuti langkah-langkah berikut:
- Di menu navigasi, klik Test.
- Ketik
Talk to Snow Pal sample
di kolom Input, lalu tekanEnter
. - Ketik Yes di kolom Input dan tekan
Enter
. Atau, klik tombol Start Game. - Tebak huruf dan kata sampai Anda menang atau kalah.
- Ketik Play Again di kolom Input dan tekan
Enter
. Atau, klik tombol Play Again.
Memahami kode
Saat menguji Action, Anda dapat memulai game baru melalui input suara ("Play Again") atau input sentuh (dengan mengklik tombol 'Play Again').
Untuk opsi input suara, saat pengguna mengucapkan "Play again" atau variasi yang serupa intent tersebut, intent play_again
akan dicocokkan dan menambahkan pesan ("Okay, here's to another game!" "Oke, ayo kita main lagi!") ke antrean pesan. Respons canvas
yang disertakan dalam pesan tersebut akan mengirim nama intent dan metadata lainnya ke aplikasi web. Nama intent diteruskan ke callback onUpdate()
, yang memetakan perintah yang sesuai, PLAY_AGAIN
, ke peta perintah di action.js
. Perintah PLAY_AGAIN
memicu fungsi start()
di scene.js
, dan memperbarui aplikasi web dengan sesi game baru.
Untuk opsi input sentuh, Anda menggunakan sendTextQuery(),
sebuah API Canvas Interaktif yang memungkinkan Anda memicu intent melalui input sentuh, agar tombol berfungsi.
Di codelab ini, Anda menggunakan sendTextQuery()
untuk memanggil intent play_again
saat pengguna mengklik tombol 'Play Again'. Argumen Play again
dicocokkan dengan frasa pelatihan dalam intent play_again
, dan memicu intent ini dengan cara yang sama seperti saat pengguna mengucapkan "Play again". Intent play_again
kemudian memicu logika yang memperbarui aplikasi web dan memulai sesi game baru.
9. Memperbarui panggilan implisit PLAY_GAME
Di bagian ini, Anda akan memperbarui panggilan implisit PLAY_GAME
.
Panggilan implisit PLAY_GAME
memungkinkan pengguna memanggil Action saat mereka membuat permintaan umum, seperti "I want to play a game" ("Saya mau main game").
Kode sumber berisi intent global PLAY_GAME
, yang terletak di /sdk/custom/global/actions.intent.PLAY_GAME.yaml
. Hal ini terefleksi di konsol pada bagian Invocation sebagai PLAY_GAME
, seperti yang ditunjukkan pada screenshot berikut:
Untuk memungkinkan pengguna memanggil Action melalui panggilan implisit ini, Anda perlu menambahkan respons canvas
dengan URL aplikasi web ke panggilan implisit PLAY_GAME
. Untuk melakukannya, ikuti langkah-langkah berikut:
- Di Konsol Actions, klik PLAY_GAME di navigasi.
- Perbarui pesan untuk menyertakan URL aplikasi web, seperti yang ditampilkan di cuplikan berikut:
candidates: - canvas: url: 'https://<PROJECT_ID>.web.app'
- Klik Save.
Menguji Action Anda di simulator
Action Anda sekarang mendukung panggilan implisit PLAY_GAME
.
Untuk menguji Action Anda, ikuti langkah-langkah berikut:
- Di menu navigasi, klik Test.
- Klik Test fulfillment for system intents.
- Klik Invoke Action.
Action Anda seharusnya akan terpanggil di simulator.
10. Lampiran: Memecahkan Masalah Action Canvas Interaktif
Di bagian ini, Anda akan mempelajari cara men-debug Action Canvas Interaktif Anda jika Action tidak berfungsi dengan benar. Project Snow Pal telah dilengkapi dengan overlay debugging yang dapat diaktifkan. Overlay tersebut menampilkan semua output console.log()
dan console.error()
di kanan bawah layar, seperti yang ditunjukkan dalam screenshot berikut:
Untuk mengaktifkan overlay ini, buka file /public/css/main.css
dan tambahkan komentar pada baris display: none !important;
, seperti yang ditunjukkan dalam cuplikan berikut:
main.css
.debug {
display: flex;
flex-direction: column;
/* Comment below to view debug overlay */
/* display: none !important; */
width: 500px;
height: 150px;
right: 0;
bottom: 0;
position: absolute;
}
11. Langkah berikutnya
Selamat!
Anda telah menyelesaikan codelab pengantar Canvas Interaktif, dan kini Anda memiliki keterampilan yang diperlukan untuk membuat Action Canvas Interaktif Anda sendiri.
Yang telah Anda pelajari
- Cara membuat, men-deploy, dan menguji Action Canvas Interaktif
- Cara menggunakan respons
Canvas
untuk memperbarui aplikasi web - Cara menggunakan berbagai metode untuk meningkatkan Action Anda, seperti
sendTextQuery()
dansetCanvasState()
- Cara men-debug Action
Referensi pembelajaran tambahan
Jelajahi referensi berikut untuk mempelajari Canvas Interaktif lebih lanjut:
- Dokumentasi Canvas Interaktif: Dokumentasi resmi Actions on Google untuk Canvas Interaktif.
- Contoh Canvas Interaktif: Kode untuk game Canvas Interaktif sederhana yang memungkinkan Anda memutar segitiga dan mengubah warnanya.
Membersihkan project [disarankan]
Untuk menghindari biaya yang mungkin dikenakan, sebaiknya hapus project yang tidak ingin Anda gunakan. Untuk menghapus project yang Anda buat di codelab ini, ikuti langkah-langkah berikut:
- Untuk menghapus Project Cloud dan resource, selesaikan langkah-langkah yang tercantum di bagian Shutting down (deleting) projects.
- Opsional: Untuk segera menghapus project Anda dari Konsol Actions, selesaikan langkah-langkah yang tercantum di bagian Deleting a project. Jika Anda tidak menyelesaikan langkah ini, project Anda akan dihapus secara otomatis setelah sekitar 30 hari.
Survei masukan
Sebelum pergi, isi survei singkat tentang pengalaman Anda.