Berinteraksi dengan pengguna menggunakan Action untuk Asisten Google

1. Ringkasan

Peringatan: Action Percakapan tidak akan digunakan lagi pada tanggal 13 Juni 2023. Untuk mengetahui informasi selengkapnya, lihat Penghentian Action Percakapan.

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 melalui percakapan untuk menyelesaikan berbagai hal, seperti membeli bahan makanan atau memesan transportasi online. (Untuk daftar lengkap apa yang mungkin, lihat Direktori tindakan.) Sebagai developer, Anda dapat menggunakan Actions on Google untuk dengan mudah membuat dan mengelola pengalaman percakapan yang menyenangkan dan efektif antara pengguna dan layanan pihak ketiga.

Ini adalah modul codelab lanjutan yang 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, Level 2, dan Level 3 ). Modul lanjutan ini akan memandu Anda melalui serangkaian fitur yang dapat membantu Anda memperluas fungsi Action dan menumbuhkan audiens Anda.

Salah satu cara penting untuk mengukur keberhasilan Action adalah interaksi pengguna atau seberapa efektif Action tersebut dalam mendatangkan pengguna kembali setelah interaksi pertama mereka. Untuk mempermudahnya, Anda dapat menerapkan beberapa fitur di Action yang memberi pengguna jalur kembali ke percakapan.

Codelab ini mencakup fitur interaksi pengguna dan praktik terbaik untuk Actions on Google.

Yang akan Anda build

Anda akan meningkatkan fitur yang telah dibuat dengan mengaktifkannya untuk:

• Kirim update harian kepada pengguna, yang dapat mereka ketuk untuk berbicara dengan Action Anda
• Mengirimkan notifikasi push kepada pengguna yang menautkan kembali ke Action Anda
• Membuat link yang mengarahkan pengguna ke Action dari browser web seluler

Yang akan Anda pelajari

• Apa yang dimaksud dengan interaksi pengguna dan mengapa hal ini penting untuk keberhasilan Action
• Cara mengubah Action untuk meningkatkan interaksi pengguna
• Fitur engagement pengguna mana yang digunakan dalam berbagai jenis Tindakan
• Cara menggunakan Actions API untuk mengirim notifikasi melalui Asisten

Yang Anda butuhkan

Anda harus memiliki alat berikut:

• IDE/editor teks pilihan Anda, seperti WebStorm, Atom, atau Sublime
• Terminal untuk menjalankan perintah shell dengan Node.js, npm, dan git terinstal
• Browser web, seperti Google Chrome
• Lingkungan pengembangan lokal dengan antarmuka command line Firebase
• Perangkat seluler (Android atau iOS) dengan Asisten (Anda harus login ke Asisten dengan Akun Google yang sama yang akan digunakan untuk membuat project ini.)

Untuk memahami kode webhook, pemahaman tentang JavaScript (ES6) juga sangat direkomendasikan, meskipun tidak diwajibkan.

2. Menyiapkan project

Bagian ini menunjukkan cara menambahkan fitur interaksi pengguna ke Action yang telah selesai dibuat sebelumnya.

Istilah utama:

• Interaksi pengguna: Metrik yang digunakan untuk mengukur apakah pengguna menemukan nilai dalam produk atau layanan. Engagement dapat diwakili dengan jumlah pengguna yang kembali ke Action Anda, yaitu satu metrik yang digunakan untuk menentukan apakah akan mempromosikan Action. Engagement pengguna yang tinggi berasal dari dua komponen Action—informasi berguna yang ingin dilihat pengguna di kemudian hari dan cara bagi pengguna untuk kembali ke Action Anda saat mereka paling cenderung mengambil informasi tersebut.

Memahami contoh

Contoh codelab ini adalah Action sederhana untuk gym fiktif yang bernama "Action Gym." Action ini menyediakan informasi tentang gym, termasuk daftar kelas yang berputar setiap hari. Action informatif seperti ini merupakan kandidat yang baik untuk semua fitur interaksi pengguna karena daftar class yang berputar memberikan informasi berguna yang berbeda setiap hari.

Diagram berikut menunjukkan alur percakapan contoh Action Gym:

Anda akan melakukan sedikit modifikasi pada dialog agar lebih cocok dengan fitur interaksi yang Anda tambahkan. Namun, desain umum percakapan tidak akan banyak berubah.

Mendownload file dasar Anda

Jalankan perintah berikut untuk meng-clone repositori GitHub untuk codelab:

git clone https://github.com/actions-on-google/user-engagement-codelab-nodejs

Menyiapkan project dan agen

Untuk menyiapkan project Action dan agen Dialogflow, selesaikan langkah-langkah berikut:

1. Buka Konsol Actions.
2. Klik Project baru.
3. Ketikkan Project name, misalnya engagement-codelab.
4. Klik Buat Project.
5. Daripada memilih kategori, scroll ke bawah ke bagian Opsi lainnya lalu klik kartu Percakapan.
6. Klik Build Action Anda untuk memperluas opsi dan pilih Add Action(s).
7. Klik Tambahkan Tindakan Pertama Anda.
8. Pada dialog Create Action, pilih Custom Intent, lalu klik Build untuk meluncurkan konsol Dialogflow.
9. Di halaman pembuatan agen konsol Dialogflow, klik Buat.
10. Klik (ikon roda gigi) di navigasi sebelah kiri.
11. Klik Ekspor dan Impor, lalu Pulihkan Dari Zip.
12. Upload file agent.zip dari direktori /user-engagement-codelab-nodejs/start/ yang Anda download sebelumnya.
13. Ketik RESTORE dan klik Pulihkan.
14. Klik Done.

Men-deploy fulfillment Anda

Setelah project Action dan agen Dialogflow Anda siap, deploy file index.js lokal menggunakan Firebase Functions CLI.

Dari direktori /user-engagement-codelab-nodejs/start/functions/ clone file dasar Anda, jalankan perintah berikut:

firebase use <PROJECT_ID>

Tips: Temukan ID project Action Anda di konsol Actions di bagian Ringkasan > (ikon roda gigi) > Setelan project.

npm install

firebase deploy

Jika Anda melihat pesan error yang menyatakan "Terjadi error yang tidak terduga dari CLI" coba jalankan kembali perintah firebase deploy.

Setelah beberapa menit, Anda akan melihat "Deploy complete!", yang menunjukkan bahwa Anda berhasil men-deploy webhook ke Firebase.

Mengambil URL deployment

Anda harus memberikan URL ke Cloud Function fungsi. Untuk mengambil URL ini, ikuti langkah berikut:

1. Buka Firebase console.
2. Pilih project Action Anda dari daftar opsi.
3. Buka Develop > Functions di menu navigasi sebelah kiri. Jika Anda diminta untuk "Memilih setelan berbagi data", Anda dapat mengabaikan opsi ini dengan mengklik Lakukan ini nanti.
4. Pada tab Dasbor, Anda akan melihat entri untuk "fulfillment" dengan URL di bagian Pemicu. Simpan URL ini; Anda perlu menyalinnya ke Dialogflow di bagian berikutnya.

Menyetel URL webhook di Dialogflow

Sekarang Anda perlu memperbarui agen Dialogflow agar dapat menggunakan webhook untuk fulfillment. Untuk melakukannya, ikuti langkah berikut:

1. Buka konsol Dialogflow (Anda dapat menutup Firebase console jika mau).
2. Klik Fulfillment pada navigasi kiri.
3. Aktifkan Webhook.
4. Tempel URL yang Anda salin dari dasbor Firebase jika belum muncul.
5. Klik Simpan.

Pastikan project Anda telah disiapkan dengan benar

Pengguna harus dapat memanggil Action untuk informasi tentang Action Gym, termasuk respons teks hard code dengan jam buka dan respons teks yang mencantumkan jadwal kelas untuk setiap hari dalam seminggu.

Tips: Anda dapat menemukan informasi terbaru tentang penggunaan simulator Action di Panduan simulator Action. Silakan mengacu ke sana jika Anda mengalami masalah dalam mengikuti langkah-langkah yang tercantum di bawah ini.

Untuk menguji Action Anda di simulator Action:

1. Di navigasi kiri konsol Dialogflow, klik Integrations > Google Assistant.
2. Pastikan Pratinjau otomatis perubahan diaktifkan dan klik Uji untuk memperbarui project Action Anda.
3. Simulator Action memuat project Action Anda. Untuk menguji Action, ketik Talk to my test app ke kolom Input, lalu tekan enter.
4. Anda akan melihat respons yang menyambut Anda di Action Gym. Coba ikuti perintah untuk melanjutkan percakapan sembari memastikan bahwa fulfillment Anda memiliki respons untuk setiap input.

Jika Anda tidak melihat respons ini, kemungkinan ada masalah dengan penyiapan Firebase Anda. Pada kasus ini, coba ulangi langkah-langkah di bagian Deploy pemenuhan Anda.

3. Menambahkan langganan pembaruan harian

Cara umum untuk melibatkan pengguna adalah dengan menawarkan informasi kepada mereka pada saat yang paling berguna. Hal ini dilakukan dengan menawarkan opsi kepada pengguna untuk berlangganan pembaruan harian untuk intent, yang mengirimkan notifikasi Asisten yang menautkan langsung ke pemenuhan intent tersebut.

Pada langkah ini, Anda akan mempelajari langganan update harian dan menambahkannya ke intent List Class Action Anda. Setelah mengikuti petunjuk ini, percakapan Action Anda akan terlihat seperti diagram berikut:

Bagaimana interaksi ini akan melibatkan pengguna?

Pengguna smartphone mungkin terbiasa dengan notifikasi push, yang memberikan informasi dan update khusus aplikasi. Langganan update harian adalah cara sederhana untuk mengakses pengguna di perangkat seluler di luar Asisten, dengan ketentuan bahwa Anda mengirimkan update untuk terus memberikan nilai kepada pengguna setiap hari.

Update harian dapat menjadi alat interaksi yang berguna, tetapi tidak harus selalu disertakan dalam setiap Action. Pertimbangkan tips berikut saat memutuskan apakah akan menambahkan langganan update harian ke Action:

• Pastikan pembaruan harian akan membuat pengguna melihat informasi yang berguna dan berbeda setiap hari. Jika mengetuk pembaruan harian menghasilkan perintah yang sama setiap kali, pengguna mungkin akan berhenti berlangganan setelah beberapa hari.
• Pastikan dialog Anda relevan bagi pengguna jika mereka langsung beralih ke intent update harian Anda. Pengguna Anda belum tentu memulai dari awal percakapan, sehingga mereka diharapkan tidak memiliki banyak konteks.
• Tunjukkan manfaat Action Anda kepada pengguna sebelum meminta mereka untuk berlangganan info terbaru harian. Pengguna Anda seharusnya berpikir "Saya ingin konten ini setiap hari" saat mereka diberi opsi untuk berlangganan.
• Jangan membuat bingung pengguna dengan saran berulang untuk berlangganan. Tawarkan langganan pembaruan harian tepat setelah menunjukkan kepada pengguna apa yang menjadi langganan mereka, dan hindari mengganggu mereka di tempat lain.
• Pastikan percakapan tetap singkat setelah intent update dipicu. Sebagian besar update harian seharusnya hanya terdiri dari satu respons, lalu ditutup tanpa memerlukan input pengguna.

Tips: Karena info terbaru harian akan muncul sebagai notifikasi di perangkat pengguna, Anda harus meninjau praktik terbaik kami untuk mendesain notifikasi yang berguna. Sebagian besar konten notifikasi update harian telah dirancang sebelumnya untuk Asisten, tetapi prinsip yang sama berlaku saat memutuskan apakah update harian masuk akal untuk intent atau Action Anda.

Aktifkan info terbaru harian

Langganan update harian dapat ditambahkan ke intent selamat datang yang menempatkan pengguna di awal percakapan Anda, atau intent yang lebih spesifik untuk memberi mereka deep link ke suatu tempat dalam percakapan. Untuk codelab ini, intent Class List paling masuk akal karena dialog akan berubah setiap hari, dan pengguna mungkin merasa perlu untuk diingatkan tentang class yang tersedia.

Ikuti langkah-langkah berikut untuk mengaktifkan update harian untuk intent Class List:

1. Di Konsol Actions, klik tab Develop, dan pilih Actions di menu navigasi sebelah kiri.
2. Klik Daftar Kelas di bagian daftar Tindakan.
3. Di bagian Interaksi pengguna, alihkan opsi Apakah Anda ingin menawarkan update harian kepada pengguna.
4. Tetapkan Judul konten deskriptif yang menjelaskan pembaruan harian. Konteksnya akan menjadi "Pukul berapa yang Anda mau saya kirimkan harian Anda ", jadi pastikan judul Anda deskriptif dan terdengar benar saat diucapkan dengan keras. Untuk contoh ini, tetapkan Judul konten ke list of upcoming Action Gym classes.
5. Klik Simpan di bagian atas halaman.

Menyiapkan Dialogflow

Ikuti langkah-langkah berikut di konsol Dialogflow guna membuat intent untuk alur langganan update harian:

Meminta pengguna untuk berlangganan

1. Siapkan intent baru untuk menangani pengguna yang meminta berlangganan update harian. Di konsol Dialogflow, klik tombol + di samping Intent pada navigasi sebelah kiri untuk membuat intent baru.
2. Beri nama intent baru ini Setup Updates.
3. Di bagian Frasa pelatihan, tambahkan ekspresi pengguna berikut:

• Send daily reminders
• Reminder
• Remind me
• Updates
• Upcoming classes

4. Di bagian Fulfillment, alihkan opsi Enable call webhook for this intent.
5. Klik Simpan di bagian atas halaman.

Menangani keputusan pengguna

1. Siapkan intent baru untuk menangani respons pengguna terhadap permintaan langganan update harian. Klik tombol + di samping Intent di navigasi sebelah kiri untuk membuat intent baru.
2. Beri nama intent baru ini Confirm Updates.
3. Di bagian Peristiwa, tambahkan actions_intent_REGISTER_UPDATE. Peristiwa Dialogflow ini akan dipicu oleh pengguna yang menyelesaikan alur langganan update harian, terlepas dari apakah mereka akhirnya berlangganan atau tidak.
4. Di bagian Fulfillment, alihkan opsi Enable call webhook for this intent.
5. Klik Simpan di bagian atas halaman.

Menerapkan fulfillment

Untuk menerapkan fulfillment di webhook Anda, selesaikan langkah-langkah berikut:

Memuat dependensi

Dalam file index.js, update fungsi require() untuk menambahkan paket RegisterUpdate dari paket actions-on-google, sehingga impor Anda akan terlihat seperti ini:

index.js

const {
  dialogflow,
  Suggestions,
  RegisterUpdate,
} = require('actions-on-google');

Chip chip update

Dalam file index.js, tambahkan entri DAILY ke daftar judul chip saran, sehingga definisi Suggestion Anda akan terlihat seperti ini:

index.js

// Suggestion chip titles
const Suggestion = {
  HOURS: 'Ask about hours',
  CLASSES: 'Learn about classes',
  DAILY: 'Send daily reminders',
};

Menambahkan fulfillment untuk intent baru

Saat pengguna mengatakan bahwa mereka ingin berlangganan, mulai alur langganan update harian dengan memanggil helper RegisterUpdate dengan intent target update (Daftar Kelas) dan ketik (DAILY). Setelah alur langganan selesai, Asisten memicu peristiwa actions_intent_REGISTER_UPDATE dengan argumen status yang menjelaskan apakah langganan berhasil atau tidak. Menawarkan permintaan tindak lanjut kepada pengguna yang berubah bergantung pada status langganan.

Dalam file index.js, tambahkan kode berikut:

index.js

// Start opt-in flow for daily updates
app.intent('Setup Updates', (conv) => {
  conv.ask(new RegisterUpdate({
    intent: 'Class List',
    frequency: 'DAILY',
  }));
});

// Confirm outcome of opt-in for daily updates
app.intent('Confirm Updates', (conv, params, registered) => {
  if (registered && registered.status === 'OK') {
     conv.ask(`Gotcha, I'll send you an update everyday with the ` +
     'list of classes. Can I help you with anything else?');
  } else {
    conv.ask(` I won't send you daily reminders. Can I help you with anything else?`);
  }
  if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.HOURS, Suggestion.CLASSES]));
  }
});

Menawarkan perintah alternatif untuk pengguna

Respons Class List akan menawarkan langganan pembaruan harian di bagian akhir, tetapi ini akan menimbulkan masalah. Karena respons yang sama ini akan dipicu saat pengguna mengetuk notifikasi update harian, mereka masih akan diminta untuk subscribe ke update harian meskipun baru saja berasal dari salah satu notifikasi. Bagaimana cara mencegah pengguna berpikir bahwa mereka harus berlangganan kembali?

Untungnya, argumen objek conv Anda mencakup informasi tentang tempat pengguna memulai percakapan. Anda dapat memeriksa argumen conv untuk melihat apakah argumen tersebut berisi bagian UPDATES, yang menunjukkan bahwa pengguna memulai percakapan dari notifikasi update harian, dan mengubah respons sebagaimana mestinya. Anda juga dapat menggunakan cabang percakapan ini untuk menutup dialog segera setelah menyediakan daftar class, yang mengikuti praktik terbaik kami untuk menjaga update harian tetap singkat.

Dalam file index.js, ganti kode berikut:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  const classesMessage =
  `On ${day} we offer the following classes: ${classes}. ` +
  `Can I help you with anything else?`;
  conv.ask(classesMessage);
  if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.HOURS]));
  }
});

dengan ini:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
    };
  };
});

Menguji pembaruan harian

Di terminal, jalankan perintah berikut untuk men-deploy kode webhook Anda yang telah diupdate ke Firebase:

firebase deploy

Tips: Anda dapat menemukan informasi terbaru tentang penggunaan simulator Action di Panduan simulator Action. Silakan mengacu ke sana jika Anda mengalami masalah dalam mengikuti langkah-langkah yang tercantum di bawah ini.

Untuk menguji permintaan ulang kustom di simulator Action, ikuti langkah-langkah berikut:

1. Di Konsol Actions, buka Test.
2. Ketik Talk to my test app di kolom Input, lalu tekan enter.
3. Ketik Learn about classes dan tekan enter. Respons Action Anda sekarang akan menawarkan untuk mengirim pengingat harian.
4. Ketik Send daily reminders dan tekan enter.
5. Ketik waktu yang Anda inginkan untuk melihat pembaruan dan tekan enter. Untuk tujuan pengujian, coba balas dengan 3-5 menit lebih lama dari waktu saat ini.

Jika Anda mengalami error saat mencoba berlangganan info terbaru harian di langkah #4, kembali ke Build > Actions > Class List dan nonaktifkan update harian. Klik Simpan, aktifkan kembali update harian, klik Simpan lagi, lalu coba uji di Simulator lagi.

Di perangkat seluler, Anda akan menerima notifikasi dari Asisten sekitar waktu yang ditentukan untuk update. Perlu diketahui bahwa notifikasi ini mungkin akan muncul setelah beberapa menit. Ketuk notifikasi dan notifikasi tersebut akan melakukan deep-link langsung ke intent Class List di Asisten, yang memberi Anda daftar class mendatang:

4. Menambahkan notifikasi push

Sebagai opsi lain untuk melibatkan pengguna di luar Action, Anda dapat memanggil Actions API untuk mengirim notifikasi push kepada pengguna. Tidak seperti update harian, notifikasi ini tidak dijadwalkan secara otomatis oleh Asisten agar Anda dapat mengirimkannya sesuai keinginan.

Istilah utama:

• Actions API: API Actions adalah Assistant REST API yang digunakan untuk mengirim notifikasi kepada pengguna. Dengan izin pengguna, Anda dapat mengirim permintaan POST ke endpoint Actions API yang mengirimi mereka notifikasi push menggunakan konten permintaan.

Pada langkah ini, Anda akan mempelajari cara menerapkan notifikasi push di Action dengan menambahkan intent Class Dibatalkan baru dan mengirim notifikasi ke pengguna yang memberi tahu mereka tentang pembatalan kelas. Anda juga akan menyiapkan tiga komponen berikut yang diperlukan untuk mengirimkan notifikasi:

• Akun API Actions - Anda mengirimkan notifikasi ke pengguna dengan mengirim permintaan POST ke API, jadi Anda perlu menyiapkan akun layanan dan kredensial untuk berinteraksi dengan API ini.
• Bantuan izin - Anda memerlukan izin pengguna untuk mengakses ID pengguna yang diperlukan agar dapat mengirimkan notifikasi push kepada pengguna. Dalam contoh ini, Anda akan menggunakan fungsi library klien untuk memanggil helper izin dan meminta ID ini.

Istilah utama:

• Helper: Pembantu adalah intent yang, jika terpenuhi, memungkinkan Asisten mengambil alih percakapan untuk sementara guna meminta informasi tertentu dari pengguna. Jika permintaan berhasil, helper akan menampilkan informasi tersebut kepada Anda.

• Penyimpanan - Untuk mengirim notifikasi push kepada pengguna di luar percakapan, Anda perlu menyimpan ID pengguna di tempat yang dapat ditarik kembali sesuai keinginan. Pada contoh ini, Anda akan menyiapkan database Firestore untuk menyimpan informasi bagi setiap pengguna.

Setelah mengikuti petunjuk ini, Anda akan menambahkan dialog berikut ke percakapan Action:

Bagaimana interaksi ini akan melibatkan pengguna?

Pengguna smartphone mungkin terbiasa dengan notifikasi push, yang memberikan informasi dan update khusus aplikasi. Notifikasi push adalah cara yang fleksibel untuk mengakses pengguna di perangkat seluler di luar Asisten, asalkan pengguna diberi alasan yang baik untuk mengaktifkannya. Dengan pembaruan harian, pengguna sudah mengetahui bahwa mereka akan diberi tahu setiap hari. Namun, dengan notifikasi push, pengguna tidak tahu apakah mereka memilih untuk menerima notifikasi yang jarang atau akan diganggu dengan beberapa notifikasi per hari.

Notifikasi push bisa menjadi alat interaksi yang berguna, tetapi tidak harus disertakan di setiap Action. Pertimbangkan tips berikut saat memutuskan apakah akan menambahkan notifikasi push ke suatu Action:

• Rencanakan beberapa contoh jadwal untuk notifikasi push Anda. Jika Anda hanya berencana mengirimkan satu notifikasi push per hari, sebaiknya gunakan update harian.
• Pastikan notifikasi push Anda akan memberikan informasi yang berguna setiap kali notifikasi tersebut diterima. Notifikasi Anda juga dapat membuat deep link ke salah satu intent Action Anda, jadi pastikan intent tersebut berguna dan relevan.
• Sampaikan secara eksplisit saat meminta pengguna untuk berlangganan notifikasi push. Mereka harus memahami apa yang diharapkan dengan setiap notifikasi push, dan memiliki gambaran seberapa sering notifikasi dikirim.

Tips: Tinjau praktik terbaik kami untuk mendesain notifikasi yang berguna. Logo dan prioritas notifikasi sudah ditentukan sebelumnya untuk Asisten, tetapi prinsip yang sama ini berlaku saat memutuskan apakah akan menambahkan notifikasi push untuk Action Anda.

Mengaktifkan Actions API

1. Buka Google Cloud Console, lalu pilih nama project Action di menu drop-down.

2. Pada menu navigasi (☰), buka APIs & Services > Library.
3. Telusuri Actions API, dan klik Aktifkan.

Membuat akun layanan

Actions API memerlukan autentikasi sehingga Anda perlu membuat akun layanan untuk mengirim permintaan. Ikuti langkah-langkah berikut untuk membuat dan menginstal kunci akun layanan untuk Actions API:

1. Di menu navigasi Google Cloud Console (☰), buka API & Services > Credentials.
2. Klik Buat kredensial > Kunci akun layanan.
3. Di menu drop-down Akun layanan, pilih Akun Layanan Baru.
4. Isi informasi berikut:

• Nama akun layanan: service-account
• Peran: Project > Pemilik
• ID akun layanan: service-account (selalu diikuti dengan @<project_id>.iam.gserviceaccount.com)
• Jenis kunci: JSON

5. Klik Buat.
6. Pindahkan file JSON yang didownload ke direktori /user-engagement-codelab/start/functions/ project Anda.
7. Ganti nama file JSON menjadi service-account.json.

Aktifkan Firestore

Untuk mengirimkan notifikasi di luar percakapan, Anda memerlukan cara untuk menyimpan ID pengguna yang dapat direferensikan dari kode notifikasi Anda. Untuk contoh ini, kami menggunakan database Firestore untuk menyimpan ID pengguna dari pengguna yang berlangganan.

Ikuti langkah-langkah ini guna membuat database Firestore untuk Action Anda:

1. Di Firebase console, pilih nama project Action Anda.
2. Di navigasi sebelah kiri, buka Develop > Database dan klik Create database.
3. Pilih Mulai dalam mode pengujian.
4. Klik Enable.

Tips: Kami hanya menggunakan aturan keamanan mode pengujian untuk tujuan pengujian. Anda harus memiliki aturan keamanan data yang lebih kuat sebelum Action Anda dipublikasikan di produksi. Pelajari Aturan Keamanan Cloud Firestore lebih lanjut di dokumentasi Firestore.

Menyiapkan Dialogflow

Ikuti langkah-langkah berikut di konsol Dialogflow untuk membuat alur keikutsertaan notifikasi push:

Meminta pengguna untuk berlangganan

1. Siapkan intent baru untuk menangani pengguna yang meminta berlangganan notifikasi push untuk class yang dibatalkan. Di konsol Dialogflow, klik tombol + di samping Intent pada navigasi sebelah kiri untuk membuat intent baru.
2. Beri nama intent baru ini Setup Push Notifications.
3. Di bagian Frasa pelatihan, tambahkan ekspresi pengguna berikut:

• Subscribe to notifications
• Send notification
• Notify me
• Send class notifications
• Cancelled notifications

4. Di bagian Fulfillment, alihkan opsi Enable call webhook for this intent.
5. Klik Simpan di bagian atas halaman.

Menangani keputusan pengguna

1. Siapkan intent baru untuk menangani respons pengguna terhadap permintaan langganan notifikasi push. Klik tombol + di samping Intent di navigasi sebelah kiri untuk membuat intent baru.
2. Beri nama intent baru ini Confirm Push Notifications.
3. Di bagian Peristiwa, tambahkan actions_intent_PERMISSION. Peristiwa Dialogflow ini akan dipicu oleh pengguna yang menyelesaikan alur langganan notifikasi push, terlepas dari apakah mereka akhirnya berlangganan atau tidak.
4. Di bagian Fulfillment, alihkan opsi Enable call webhook for this intent.
5. Klik Simpan di bagian atas halaman.

Menangani notifikasi push

Anda dapat menautkan notifikasi push ke intent tertentu, sehingga pengguna yang mengetuk notifikasi push memiliki deep link langsung ke intent tersebut dalam Action Anda. Dalam contoh ini, tambahkan intent baru untuk notifikasi push yang memberikan detail tentang class yang dibatalkan.

Ikuti langkah-langkah berikut untuk menambahkan intent yang akan dipicu oleh pengguna yang mengetuk notifikasi push:

1. Di konsol Dialogflow, klik tombol + di samping Intent pada navigasi sebelah kiri untuk membuat intent baru.
2. Beri nama intent baru ini Class Canceled.
3. Di bagian Frasa pelatihan, tambahkan Cancelations sebagai ekspresi pengguna.
4. Di bagian Fulfillment, alihkan opsi Enable call webhook for this intent.
5. Klik Simpan di bagian atas halaman.

Mengirim notifikasi pengujian di tengah percakapan

Dalam produksi, harus ada skrip yang terpisah dari kode fulfillment Action Anda yang mengirimkan notifikasi push. Untuk contoh ini, buat intent yang bisa Anda panggil untuk mengirim notifikasi push saat berbicara dengan Action Anda. Intent ini hanya untuk tujuan debug; dalam praktiknya, notifikasi push tidak boleh ditangani oleh fulfillment Anda atau dipicu sebagai bagian dari percakapan Action Anda.

Ikuti langkah-langkah ini untuk membuat intent untuk menguji notifikasi push:

1. Untuk tujuan pengujian dan proses debug, siapkan intent baru yang memungkinkan Anda mengirim notifikasi push kepada pengguna yang berlangganan. Di konsol Dialogflow, klik tombol + di samping Intent pada navigasi sebelah kiri untuk membuat intent baru.
2. Beri nama intent baru ini Test Notification.
3. Di bagian Frasa pelatihan, tambahkan Test notification sebagai ekspresi pengguna.
4. Di bagian Fulfillment, alihkan opsi Enable call webhook for this intent.
5. Klik Simpan di bagian atas halaman.

Aktifkan pemberitahuan push

Ikuti langkah-langkah berikut untuk mengaktifkan notifikasi push untuk intent Class Dibatalkan:

1. Di konsol Dialogflow, buka Integrations di menu navigasi.
2. Pada kartu Asisten Google, klik Setelan Integrasi.
3. Tambahkan Class Dibatalkan sebagai intent Panggilan implisit. Langkah ini diperlukan agar Dialogflow mengenali bahwa pengguna dapat memulai percakapan Anda dengan intent Class Dibatalkan (dengan mengetuk notifikasi push).
4. Klik Close.

5. Di Konsol Actions, klik tab Develop, dan pilih Actions di menu navigasi sebelah kiri.
6. Klik Class Dibatalkan di bagian daftar Tindakan.
7. Di bagian Interaksi pengguna, alihkan opsi Apakah Anda ingin mengirim notifikasi push?.
8. Tetapkan Judul konten deskriptif yang menjelaskan notifikasi push. Konteksnya akan menjadi "Apakah boleh jika saya mengirim notifikasi push untuk ?" jadi pastikan judul Anda deskriptif dan terdengar benar saat diucapkan dengan keras. Untuk contoh ini, tetapkan Judul konten ke class cancelations.
9. Klik Simpan di bagian atas halaman.

Menerapkan fulfillment

Untuk menerapkan fulfillment di webhook Anda, selesaikan langkah-langkah berikut:

Memuat dependensi

Dalam file index.js, update fungsi require() untuk menambahkan paket UpdatePermission dari paket actions-on-google, sehingga impor Anda akan terlihat seperti ini:

index.js

const {
  dialogflow,
  Suggestions,
  RegisterUpdate,
  UpdatePermission,
} = require('actions-on-google');

Chip chip update

Dalam file index.js, tambahkan entri NOTIFICATIONS ke daftar judul chip saran, sehingga definisi Suggestion Anda akan terlihat seperti ini:

index.js

// Suggestion chip titles
const Suggestion = {
  HOURS: 'Ask about hours',
  CLASSES: 'Learn about classes',
  DAILY: 'Send daily reminders',
  NOTIFICATIONS: 'Get notifications',
};

Menyiapkan impor baru

Agar terhubung ke database Firestore, tambahkan paket firebase-admin dan tambahkan konstanta untuk kolom yang disimpan dalam database. Selain itu, impor paket google-auth-library dan request untuk menangani autentikasi dan permintaan ke Actions API.

Dalam file index.js, tambahkan kode berikut ke impor Anda:

index.js

// Firebase admin import
const admin = require('firebase-admin');

// Initialize Firestore
admin.initializeApp();
const db = admin.firestore();

// Firestore constants
const FirestoreNames = {
 INTENT: 'intent',
 USER_ID: 'userId',
 USERS: 'users',
};

// Actions API authentication imports
const {auth} = require('google-auth-library');
const request = require('request');

Tawarkan untuk menyiapkan notifikasi pembatalan kelas

Dalam file index.js, ganti kode berikut:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
    };
  };
});

dengan ini:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like to receive daily reminders of upcoming classes, subscribe to notifications about cancelations, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.NOTIFICATIONS,
Suggestion.HOURS]));
    };
  };
});

Menambahkan fulfillment untuk intent baru

Saat pengguna mengatakan bahwa mereka ingin berlangganan notifikasi push, panggil helper UpdatePermission untuk meminta izin dari pengguna. Jika itu berhasil, argumen PERMISSION akan ditambahkan ke argumen objek conv yang dapat Anda periksa untuk melakukan pivot percakapan.

Setelah Anda memiliki izin pengguna, ambil ID pengguna dari argumen objek conv dan simpan dalam database Anda. Anda nanti akan mengirim ID pengguna ini ke Actions API, yang merupakan cara Asisten menentukan siapa yang menerima notifikasi.

Terakhir, tambahkan fulfillment untuk intent Class Canceled yang dipicu dengan mengetuk notifikasi push. Dalam contoh ini, respons Anda adalah string placeholder, meskipun dalam versi Action yang siap produksi ini, skrip notifikasi Anda akan memberikan informasi yang lebih dinamis tentang class mana yang telah dibatalkan.

Dalam file index.js, tambahkan kode berikut:

index.js

// Call the User Information helper for permission to send push notifications
app.intent('Setup Push Notifications', (conv) => {
 conv.ask('Update permission for setting up push notifications');
 conv.ask(new UpdatePermission({intent: 'Class Canceled'}));
});

// Handle opt-in or rejection of push notifications
app.intent('Confirm Push Notifications', (conv) => {
 if (conv.arguments.get('PERMISSION')) {
   let userId = conv.arguments.get('UPDATES_USER_ID');
   if (!userId) {
     userId = conv.request.conversation.conversationId;
   }
   // Add the current conversation ID and the notification's
   // target intent to the Firestore database.
   return db.collection(FirestoreNames.USERS)
   .add({
     [FirestoreNames.INTENT]: 'Class Canceled',
     [FirestoreNames.USER_ID]: userId,
   })
   .then(() => {
     conv.ask(`Great, I'll notify you whenever there's a class cancelation. ` +
     'Can I help you with anything else?');
   });
 } else {
   conv.ask(`Okay, I won't send you notifications about class cancelations. ` +
     'Can I help you with anything else?');
 }
 if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.CLASSES, Suggestion.HOURS]));
  }
});

// Intent triggered by tapping the push notification
app.intent('Class Canceled', (conv) => {
 conv.ask('Classname at classtime has been canceled.');
});

Menambahkan notifikasi pengujian

Untuk mengirim notifikasi push kepada pengguna, kirim permintaan POST ke Actions API dengan ID pengguna, judul notifikasi, dan intent target. Dalam contoh ini, memicu intent Notifikasi Pengujian akan melakukan iterasi melalui database Firestore dan mengirimkan notifikasi push kepada setiap pengguna yang berlangganan notifikasi.

Ingatlah bahwa dalam contoh ini, Anda menyertakan kode yang mengirimkan notifikasi push di fulfillment webhook Anda dan memicu kode tersebut dengan memanggil intent pengujian dalam percakapan Anda. Di Action yang ingin Anda publikasikan, kode notifikasi push harus ada dalam skrip yang terpisah dari fulfillment Anda.

Dalam file index.js, tambahkan kode berikut:

index.js

// Debug intent to trigger a test push notification
app.intent('Test Notification', (conv) => {
 // Use the Actions API to send a Google Assistant push notification.
 let client = auth.fromJSON(require('./service-account.json'));
 client.scopes = ['https://www.googleapis.com/auth/actions.fulfillment.conversation'];
 let notification = {
   userNotification: {
     title: 'Test Notification from Action Gym',
   },
   target: {},
 };
 client.authorize((err, tokens) => {
   if (err) {
     throw new Error(`Auth error: ${err}`);
   }
   // Iterate through Firestore and send push notifications to every user
   // who's currently opted in to canceled class notifications.
   db.collection(FirestoreNames.USERS)
       .where(FirestoreNames.INTENT, '==', 'Class Canceled')
       .get()
       .then((querySnapshot) => {
         querySnapshot.forEach((user) => {
           notification.target = {
             userId: user.get(FirestoreNames.USER_ID),
             intent: user.get(FirestoreNames.INTENT),
           };
           request.post('https://actions.googleapis.com/v2/conversations:send', {
             'auth': {
               'bearer': tokens.access_token,
             },
             'json': true,
             'body': {'customPushMessage': notification, 'isInSandbox': true},
           }, (err, httpResponse, body) => {
             if (err) {
               throw new Error(`API request error: ${err}`);
             }
             console.log(`${httpResponse.statusCode}: ` +
               `${httpResponse.statusMessage}`);
             console.log(JSON.stringify(body));
           });
         });
       })
       .catch((error) => {
         throw new Error(`Firestore query error: ${error}`);
       });
 });
 conv.ask('A notification has been sent to all subscribed users.');
});

Menguji notifikasi push

Di terminal, jalankan perintah berikut untuk men-deploy kode webhook Anda yang telah diupdate ke Firebase:

firebase deploy

Tips: Anda dapat menemukan informasi terbaru tentang penggunaan simulator Action di Panduan simulator Action. Silakan mengacu ke sana jika Anda mengalami masalah dalam mengikuti langkah-langkah yang tercantum di bawah ini.

Untuk menguji notifikasi di simulator Action, ikuti langkah-langkah berikut:

1. Di Konsol Actions, buka tab Test.
2. Ketik Talk to my test app di kolom Input, lalu tekan enter.
3. Ketik Learn about classes dan tekan enter.
4. Ketik Get notifications dan tekan enter.
5. Jika Anda belum memberikan izin Action untuk mengirim notifikasi push, ketik yes dan tekan enter.
6. Ketik yes dan tekan enter. Akun Google Anda kini telah berlangganan notifikasi push untuk Tindakan ini.

Jika Anda mendapatkan error saat mencoba berlangganan notifikasi push di langkah #4, kembali ke Build > Actions > Class Dibatalkan dan nonaktifkan notifikasi push. Klik Simpan, aktifkan kembali notifikasi push, klik Simpan lagi, lalu coba uji di Simulator lagi.

7. Ketik no dan tekan enter untuk keluar.
8. Ketik Talk to my test app dan tekan enter untuk memulai percakapan baru.
9. Ketik Test notification dan tekan enter.

Dalam beberapa menit, Anda akan menerima "Notifikasi Pengujian dari Action Gym" Notifikasi push Asisten di perangkat seluler Anda. Mengetuk notifikasi ini akan mengarahkan Anda ke intent Class Dibatalkan melalui Action.

Jika Anda mengalami masalah saat menampilkan notifikasi, coba ikuti petunjuk pengujian di ponsel. Buka Asisten di ponsel Anda dan ucapkan "talk to my test app" lalu ikuti petunjuk pengujian di atas dari langkah #3.

5. Membuat link Asisten

Sejauh ini kami telah membahas fitur interaksi yang dapat Anda terapkan untuk membuat pengguna terus kembali ke Action Anda, tetapi fitur tersebut didasarkan pada keinginan pengguna yang menemukan dan menggunakan Action Anda.

Anda dapat membuat link Asisten yang akan menautkan pengguna di perangkat seluler langsung ke Action di Asisten. Karena link Asisten adalah hyperlink standar, Anda dapat menambahkannya ke situs atau materi pemasaran web apa pun seperti blog atau postingan media sosial.

Pada langkah ini, Anda akan mempelajari apa yang dimaksud dengan link Asisten, cara membuatnya untuk intent selamat datang Action, dan cara menambahkannya ke situs sederhana untuk pengujian.

Bagaimana interaksi ini akan melibatkan pengguna?

Menarik pengguna ke Action untuk pertama kalinya bisa menjadi hal yang menantang, terutama saat mereka perlu memanggil Action di Asisten secara eksplisit. Link Asisten mengatasi kendala ini dengan memberikan link langsung ke Action Anda kepada pengguna. Saat pengguna mengikuti link Asisten Anda di perangkat yang dilengkapi dengan Asisten, mereka akan diarahkan langsung ke Action Anda. Saat pengguna membuka link Anda di perangkat non-seluler atau perangkat lain yang tidak mendukung Asisten, dia akan tetap diarahkan ke listingan direktori Action Anda (jika dipublikasikan) sehingga link tersebut masih dapat memasarkan Action Anda kepada pengguna tersebut.

Link Asisten bisa menjadi alat interaksi yang berguna, jadi Anda harus membuatnya jika Anda berencana untuk mengiklankan Action melalui situs atau media sosial Anda. Perhatikan tips berikut sebelum Anda membuat dan mendistribusikan link Asisten:

• Link Asisten hanya berfungsi setelah Action Anda dipublikasikan. Saat project Anda dalam status draf, link hanya akan berfungsi di perangkat Anda sendiri. Pengguna lain akan diarahkan ke halaman 404 di direktori Actions.
• Anda dapat mengizinkan pengguna menguji link Asisten sebelum publikasi dengan merilis Action Anda di lingkungan alfa atau beta. Perhatikan bahwa hanya pengguna yang berpartisipasi dalam alfa atau beta Anda yang bisa menguji link Asisten Anda.
• Pastikan intent tujuan untuk link Asisten Anda memberikan kesan pertama yang baik kepada pengguna baru. Intent selamat datang Anda adalah tujuan default untuk link Asisten karena seharusnya sudah berfungsi dengan baik dalam memperkenalkan Action Anda

Tips: Dalam contoh ini, Anda hanya akan membuat link Asisten sederhana untuk mengirim pengguna ke intent sambutan, tetapi masih banyak lagi yang dapat Anda lakukan untuk menyesuaikan link Asisten. Anda dapat menambahkan parameter URL ke link yang mengarahkan pengguna ke intent tertentu dan bahkan menyertakan parameter intent untuk menyesuaikan respons yang diterima pengguna saat mereka mengikuti link Anda. Meskipun kami tidak membahas opsi lanjutan ini dalam codelab ini, Anda dapat mempelajari lebih lanjut di dokumentasi developer.

Aktifkan link Asisten

Ikuti langkah-langkah berikut guna membuat link Asisten untuk intent sambutan:

1. Di Konsol Actions, klik tab Develop, dan pilih Actions di menu navigasi sebelah kiri.
2. Klik actions.intent.MAIN di bagian daftar Actions.
3. Di bagian Link, alihkan opsi Apakah Anda ingin mengaktifkan URL untuk Tindakan ini.
4. Tetapkan Judul link deskriptif yang menjelaskan Action Anda. Buat judul menjadi pasangan kata kerja sederhana yang menjelaskan apa yang dapat dilakukan pengguna dengan Action Anda. Untuk contoh ini, tetapkan Judul tautan ke learn about Action Gym.
5. Salin cuplikan HTML dari bagian bawah halaman ini, lalu simpan untuk nanti.
6. Klik Simpan di bagian atas halaman.

Men-deploy situs uji coba

Untuk menguji link Asisten, Anda dapat menggunakan alat Firebase untuk men-deploy situs uji coba bersama dengan fulfillment Anda. Kami telah membuat situs pengujian sederhana untuk contoh ini, Anda hanya perlu menambahkan link Asisten.

Buka direktori /user-engagement-codelab-nodejs/start/public/ fulfillment Anda dan buka file index.html di editor teks.

Di file index.html, tempelkan cuplikan HTML link Asisten ke elemen isi. File tersebut akan terlihat seperti cuplikan di bawah:

index.html

<body>
    <p>
     <a href="https://assistant.google.com/services/invoke/uid/000000efb5f2fd97">🅖 Ask my test app to learn about Action Gym
     </a>
    </p>
</body>

Uji link Asisten Anda

Di terminal, jalankan perintah berikut untuk men-deploy situs pengujian Anda ke Firebase:

firebase deploy

Setelah perintah deploy selesai berjalan, catat URL Hosting dalam output.

Buka URL ini di browser web perangkat seluler dan Anda akan melihat link Asisten di situs pengujian. Mengklik link ini di perangkat seluler akan mengarahkan Anda ke intent selamat datang Action di Asisten.

Anda juga dapat mencoba membuka URL Hosting di browser desktop, yang akan mengarahkan Anda ke halaman 404 di direktori Asisten karena Action Anda tidak dipublikasikan.

6. Langkah berikutnya

Selamat!

Anda sudah mempelajari pentingnya interaksi pengguna saat mengembangkan Action, fitur interaksi pengguna apa yang tersedia di platform, dan cara menambahkan setiap fitur ke Action.

Referensi pembelajaran tambahan

Jelajahi referensi berikut ini untuk mempelajari interaksi pengguna untuk Action Anda lebih lanjut:

• Interaksi pengguna & Dokumen link asisten: Dokumentasi resmi Actions on Google tentang fitur yang dibahas dalam codelab ini dan interaksi pengguna secara umum.
• Analisis retensi pengguna: Dokumentasi untuk fitur analisis di Konsol Actions yang menunjukkan retensi pengguna untuk Action yang Anda publikasikan.
• Pedoman desain percakapan: Praktik terbaik dan pedoman untuk mendesain fitur interaksi pengguna.
• Repo GitHub Actions on Google: Kode contoh dan library.
• r/GoogleAssistantDev: Komunitas Reddit resmi untuk developer yang bekerja dengan Asisten.

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

Survei masukan

Sebelum melanjutkan, harap isi formulir ini untuk memberi tahu bagaimana performa kami.