Membuat Action Canvas Interaktif untuk Asisten Google dengan Action Builder

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.

Canvas Interaktif adalah sebuah framework yang dibuat di atas Asisten Google, yang memungkinkan Anda menambahkan visual dan animasi layar penuh ke Action Percakapan.

Istilah utama:

• Action Percakapan: Action yang menggunakan antarmuka percakapan untuk memenuhi permintaan pengguna.

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.

Istilah utama:

• Aplikasi web: Aplikasi yang menggunakan teknologi berbasis web, seperti HTML, CSS, dan JavaScript, untuk membuat pengalaman visual yang interaktif, seperti game. Di codelab ini, aplikasi web yang dimaksud adalah visual dan animasi game 'Snow Pal'.

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.

Istilah utama:

• Webhook: Callback HTTP yang menangani permintaan dari scene atau intent, biasanya digunakan untuk membuat respons percakapan secara dinamis (sering kali dengan melakukan panggilan API).

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:

1. Action Percakapan meminta pengguna untuk menebak huruf dalam kata atau menebak seluruh kata.
2. Pengguna akan mengatakan "I guess the letter i" ("Saya tebak hurufnya i") ke aplikasi web Snow Pal di layar smart.
3. Input pengguna diarahkan ke Action Percakapan Anda, yang ditetapkan dalam project Action Builder dan/atau project Actions SDK Anda.
4. 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.
5. 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.

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:

1. Buka halaman Kontrol Aktivitas.
2. Login dengan akun Google Anda, jika diperlukan.
3. 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.

Istilah utama:

• CLI gaction: Fitur yang memungkinkan Anda melakukan inisialisasi file project Action, mendorong update ke konsol Actions, men-deploy project Actions, dan lainnya.

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.

Catatan: Jika Anda telah menginstal Antarmuka Command Line Firebase, Anda dapat melewati langkah-langkah ini dan melanjutkan ke bagian berikutnya.

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

Tidak berhasil? Anda mungkin perlu mengubah izin npm.

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:

1. Buka terminal, lalu ubah ke direktori tempat Anda biasanya menyimpan project coding. Jika tidak punya, ubah ke direktori beranda Anda.
2. 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.

Catatan: File dengan kode lengkap ada di direktori complete/.

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:

1. Buka Konsol Actions.
2. Klik New project.
3. Ketikkan Project name, misalnya canvas-codelab. Nama ini untuk referensi internal Anda. Nanti Anda dapat menetapkan nama eksternal untuk project Anda.

4. Klik Create project.
5. Di layar What kind of Action do you want to build?, pilih kartu Game.
6. Klik Next.
7. 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:

1. Di Konsol Actions, klik tiga titik vertikal di kanan atas.
2. Klik Project settings.

3. 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:

1. Buka halaman penagihan Google Cloud Platform.
2. Klik Tambahkan akun penagihan.
3. Masukkan informasi pembayaran Anda dan klik Mulai uji coba gratis saya atau Kirim dan aktifkan penagihan.
4. Klik tab Project Saya di bagian atas halaman.
5. Klik tiga titik pada Action di samping project Action untuk codelab ini.
6. Klik Ubah penagihan.
7. 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.

Catatan: Anda dapat menetapkan Action untuk mengizinkan deployment file fulfillment dan file aplikasi web Anda dengan perintah Firebase firebase deploy (opsional). Di codelab ini, Anda akan men-deploy aplikasi web dan fulfillment secara terpisah.

Untuk men-deploy aplikasi web, ikuti langkah-langkah berikut:

1. Di terminal, buka direktori start/.
2. 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:

1. Dapatkan URL Hosting yang disediakan di output terminal Anda. URL tersebut seharusnya dalam format berikut: https://{PROJECT_ID}.web.app

Catatan: Jika URL tidak muncul di output terminal, Anda dapat memperoleh URL aplikasi web dengan langkah-langkah berikut:

1. Buka Firebase console.
2. Pilih project Action Anda dari daftar opsi.
3. Pilih Develop > Hosting di menu navigasi sebelah kiri.
4. Pada tab Dashboard, Anda akan melihat daftar domain untuk project Anda. Salin URL-nya. URL tersebut seharusnya memiliki format seperti ini: https://{PROJECT_ID}.web.app

2. 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:

1. Buka file start/sdk/custom/global/actions.intent.MAIN.yaml di editor teks.
2. Di kolom url, ganti string placeholder dengan URL aplikasi web Anda.
3. Buka file start/sdk/settings/settings.yaml di editor teks.
4. 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:

1. Ubah ke direktori sdk:

cd sdk/

2. 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:

1. Di Konsol Actions, klik Develop di navigasi.
2. Klik tab Webhook di navigasi.
3. Klik Deploy Fulfillment.

Perhatian: Pesan "Billing account needed" akan muncul setelah Anda mengklik Deploy Fulfillment. Untuk men-deploy webhook, Anda harus mengaitkan akun penagihan dengan project Anda di Google Cloud. Untuk menyiapkan akun penagihan, klik Buka Cloud Console dan ikuti langkah-langkah untuk menautkan akun penagihan. Anda dapat menghapus project ini di akhir codelab untuk menghindari tagihan. Untuk informasi selengkapnya, lihat bagian 'Membersihkan' di halaman 'Langkah berikutnya'.

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:

1. Di menu navigasi Konsol Actions, klik Test.
2. Ketik Talk to Snow Pal sample di kolom Input, lalu tekan Enter.
3. Ketik Yes di kolom Input dan tekan Enter. 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").

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.

Istilah utama:

• Canvas: Respons yang berisi URL aplikasi web dan/atau data untuk meneruskannya. Anda dapat mengonfigurasi respons Canvas di webhook atau di Action Builder. Untuk informasi selengkapnya, lihat Pesan Canvas.

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.

Istilah utama:

• Interactive Canvas API: Sebuah API JavaScript yang Anda sertakan di aplikasi web untuk mengaktifkan komunikasi antara aplikasi web dan Action Percakapan Anda.

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.

Istilah utama:

• onUpdate(): Callback yang dijalankan setiap kali Anda mengirim respons Canvas. onUpdate() dapat memetakan ke logika kustom yang memperbarui aplikasi web.

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.

Istilah utama:

• setCanvasState(): Metode yang memungkinkan Anda mengirim data status dari aplikasi web Canvas Interaktif ke webhook. Aplikasi web mengirim statusnya yang diperbarui sebagai objek JSON.

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;
...

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:

1. Di Konsol Actions, klik Scenes di navigasi.
2. Klik Game untuk membuka scene Game.
3. Klik When guess is matched di bagian Custom intent handling. Hapus Send prompts untuk menghapus pesan.
4. 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:

1. Di Konsol Actions, klik Webhook di navigasi.
2. Tambahkan kode berikut ke index.js di bagian pengendali guess:

Catatan: Di codelab ini, cuplikan kode yang Anda tambahkan dibagi menjadi beberapa bagian huruf. File yang Anda ubah menyertakan komentar yang menentukan tempat Anda harus menambahkan setiap cuplikan (misalnya, // Add section F} here). Tambahkan cuplikan yang sesuai di bawah baris yang dikomentari.

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',
  },
}));

3. Klik Save Fulfillment.
4. 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.

1. Buka public/js/action.js di editor teks Anda.
2. Perbarui aplikasi web untuk menangani perintah CORRECT_ANSWER dan INCORRECT_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();
      },

3. 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:

1. Di menu navigasi, klik Test.
2. Ketik Talk to Snow Pal sample di kolom Input, lalu tekan Enter.
3. Ketik Yes di kolom Input dan tekan Enter. Atau, klik tombol Yes.
4. 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:

1. Input pengguna cocok dengan intent yang menyertakan respons Canvas.
2. Action Percakapan atau webhook mengirim respons Canvas, yang memicu callback onUpdate().
3. Callback onUpdate() memetakan ke logika kustom yang memperbarui aplikasi web.

Istilah utama:

• onUpdate(): Callback yang dijalankan setiap kali fulfillment mengirim respons Canvas. onUpdate() dapat memetakan ke logika kustom yang memperbarui aplikasi web.

Khususnya untuk project ini, kode bekerja dengan cara berikut:

1. Saat pengguna cocok dengan intent guess, Action Builder mengekstrak huruf dari input pengguna sebagai parameter.
2. Action Builder memanggil pengendali guess di webhook Anda, yang berisi logika untuk menentukan apakah huruf yang ditebak pengguna muncul di kata.
3. Pengendali guess berisi dua respons Canvas — satu dijalankan saat huruf benar, dan satu lagi dijalankan saat huruf salah. Setiap respons Canvas akan meneruskan data yang sesuai (perintah CORRECT_ANSWER atau INCORRECT_ANSWER) ke aplikasi web.
4. Data yang terdapat dalam kolom data dari respons Canvas diteruskan ke metode onUpdate() di action.js. onUpdate() memanggil perintah yang sesuai dalam peta perintah di scene.js.
5. Perintah ini memetakan fungsi correctAnswer() dan incorrectAnswer() di scene.js. Fungsi ini memperbarui aplikasi web dengan tepat untuk merefleksikan tebakan pengguna dan memanggil setCanvasState() untuk mengirim data status dari aplikasi web ke webhook Anda.

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:

1. Di Konsol Actions, klik Webhook di navigasi.
2. Tambahkan kode berikut ke index.js di bagian pengendali guess:

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
}

3. Klik Save Fulfillment.
4. 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:

1. Buka public/js/action.js di editor teks Anda.
2. Perbarui aplikasi web Anda untuk menangani perintah WIN_GAME dan LOSE_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();
      },

3. 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:

1. Di menu navigasi Konsol Actions, klik Test.
2. Ketik Talk to Snow Pal sample di kolom Input, lalu tekan Enter.
3. Ketik Yes di kolom Input dan tekan Enter. Atau, klik tombol Start Game.
4. 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.

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:

1. Di Konsol Actions, klik drop-down Scene.
2. Klik scene Game.
3. Klik When play_again is matched di bagian Custom intent handling.
4. Ganti pesan dengan yang berikut ini:

candidates:
  - first_simple:
      variants:
        - speech: 'Okay, here's another game!'
    canvas:
      sendStateDataToCanvasApp: true

5. 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:

1. Buka public/js/action.js di editor teks Anda.
2. 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();
      },

3. Buka public/js/scene.js di editor teks Anda.
4. 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');

5. 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:

1. Di menu navigasi, klik Test.
2. Ketik Talk to Snow Pal sample di kolom Input, lalu tekan Enter.
3. Ketik Yes di kolom Input dan tekan Enter. Atau, klik tombol Start Game.
4. Tebak huruf dan kata sampai Anda menang atau kalah.
5. 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.

Istilah utama:

• sendTextQuery(): Metode yang mengirim kueri teks ke Action Percakapan untuk memanggil intent secara terprogram.

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.

Di bagian ini, Anda akan memperbarui panggilan implisit PLAY_GAME.

Istilah utama:

• Panggilan implisit: Alur interaksi yang terjadi saat pengguna membuat permintaan untuk melakukan sejumlah tugas tanpa memanggil Action dengan nama.

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:

1. Di Konsol Actions, klik PLAY_GAME di navigasi.
2. Perbarui pesan untuk menyertakan URL aplikasi web, seperti yang ditampilkan di cuplikan berikut:

candidates:
  - canvas:
      url: 'https://<PROJECT_ID>.web.app'

3. Klik Save.

Menguji Action Anda di simulator

Action Anda sekarang mendukung panggilan implisit PLAY_GAME.

Untuk menguji Action Anda, ikuti langkah-langkah berikut:

1. Di menu navigasi, klik Test.
2. Klik Test fulfillment for system intents.
3. Klik Invoke Action.

Action Anda seharusnya akan terpanggil di simulator.

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;
}

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() dan setCanvasState()
• 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:

1. Untuk menghapus Project Cloud dan resource, selesaikan langkah-langkah yang tercantum di bagian Shutting down (deleting) projects.

Perhatian: Pastikan Anda memilih project yang benar untuk dihapus di halaman Setelan Google Cloud Platform.

2. 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.