Berinteraksi dengan pengguna menggunakan Action untuk Asisten Google

1. Ringkasan

Peringatan: Action Percakapan tidak akan digunakan lagi pada 13 Juni 2023. Untuk mengetahui informasi selengkapnya, lihat Penghentian Tindakan 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 dalam percakapan untuk menyelesaikan berbagai hal, seperti membeli bahan makanan atau memesan transportasi. (Untuk mengetahui daftar lengkap yang mungkin dilakukan, lihat direktori Actions.) 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, sebaiknya Anda memahami 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 memperluas fungsi Action dan meningkatkan jumlah audiens.

Salah satu cara penting untuk mengukur keberhasilan Action adalah engagement pengguna atau seberapa efektif Action tersebut dalam membawa pengguna kembali setelah interaksi pertama mereka. Untuk membantu memudahkannya, Anda bisa menerapkan beberapa fitur di Action Anda yang memberikan jalur kembali kepada pengguna ke percakapan Anda.

Codelab ini membahas praktik terbaik dan fitur engagement pengguna untuk Actions on Google.

Yang akan Anda build

Anda akan meningkatkan fitur yang telah dibuat dengan mengaktifkannya untuk:

• Kirim info harian terbaru kepada pengguna yang dapat diketuk untuk berkomunikasi dengan Action Anda
• Kirim notifikasi push kepada pengguna yang menautkan kembali ke Action Anda
• Buat link yang mengarahkan pengguna ke Action Anda dari browser web seluler

Yang akan Anda pelajari

• Apa yang dimaksud dengan engagement pengguna dan mengapa hal ini penting bagi kesuksesan Action
• Cara mengubah Action untuk meningkatkan engagement pengguna
• Fitur engagement pengguna mana yang akan 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 dengan yang akan Anda gunakan untuk membuat project ini.)

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

2. Menyiapkan project

Bagian ini menunjukkan cara menambahkan fitur engagement pengguna ke Action lengkap yang dibuat sebelumnya.

Istilah utama:

• Engagement pengguna: Metrik yang digunakan untuk mengukur apakah pengguna menemukan nilai dalam suatu produk atau layanan. Engagement dapat ditunjukkan oleh jumlah pengguna yang kembali ke Action Anda, yang merupakan satu metrik yang digunakan untuk menentukan apakah akan mempromosikan suatu Action atau tidak. Engagement pengguna yang tinggi berasal dari dua komponen Action—informasi berguna yang ingin dilihat pengguna di kemudian hari dan cara pengguna untuk kembali ke Action Anda ketika mereka kemungkinan besar akan mengambil informasi tersebut.

Memahami sampel

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

Diagram berikut menunjukkan alur percakapan contoh Action Gym:

Anda akan melakukan sedikit perubahan pada dialog tersebut agar lebih sesuai 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 Actions dan agen Dialogflow Anda, selesaikan langkah-langkah berikut:

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

Men-deploy fulfillment Anda

Setelah project Actions 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 project ID Action Anda di Konsol Actions di bagian Ringkasan > (ikon roda gigi) > Setelan project.

npm install

firebase deploy

Jika Anda melihat pesan error yang menyatakan "An Unknown error has changed from the CLI", coba jalankan kembali perintah firebase deploy.

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

Mengambil URL deployment

Anda perlu menyediakan URL ke fungsi cloud pada Dialogflow. Untuk mengambil URL ini, ikuti langkah-langkah berikut:

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

Menetapkan URL webhook di Dialogflow

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

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

Memastikan project Anda disiapkan dengan benar

Pengguna harus dapat memanggil Action Anda 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 Tindakan di Panduan simulator tindakan. Lihat halaman tersebut jika Anda mengalami masalah saat mengikuti langkah-langkah yang tercantum di bawah ini.

Untuk menguji Action Anda di simulator Action:

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

Jika Anda tidak melihat respons ini, mungkin ada masalah dengan penyiapan Firebase Anda. Dalam hal ini, coba ulangi langkah-langkah di bagian Deploy your fulfillment.

3. Menambahkan langganan update harian

Cara umum untuk melibatkan pengguna adalah dengan menawarkan informasi kepada mereka pada saat yang tepat. Hal ini dilakukan dengan menawarkan opsi kepada pengguna untuk berlangganan update harian untuk intent, yang akan mengirimi mereka notifikasi Asisten yang menautkan langsung ke fulfillment intent tersebut.

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

Bagaimana hal ini akan melibatkan pengguna?

Pengguna smartphone mungkin sudah terbiasa dengan notifikasi push, yang menyediakan informasi dan update khusus aplikasi. Langganan update harian adalah cara sederhana untuk mengakses pengguna di perangkat seluler di luar Asisten, asalkan intent yang Anda kirimkan updatenya terus memberikan nilai kepada pengguna setiap hari.

Info terbaru harian dapat menjadi alat interaksi yang berguna, tetapi tidak boleh disertakan dalam setiap Tindakan. Pertimbangkan tips ini saat memutuskan apakah akan menambahkan langganan update harian ke Action:

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

Tips: Karena update harian akan muncul sebagai notifikasi di perangkat pengguna, Anda harus meninjau praktik terbaik kami untuk merancang notifikasi yang berguna. Sebagian besar konten notifikasi update harian sudah didesain sebelumnya untuk Asisten, tetapi prinsip yang sama ini berlaku saat memutuskan apakah update harian relevan untuk intent atau Action Anda.

Aktifkan info terbaru harian

Langganan update harian dapat ditambahkan ke intent sambutan yang menempatkan pengguna di awal percakapan, atau niat yang lebih spesifik untuk mengarahkan mereka ke suatu tempat dalam percakapan dengan deep link. Untuk codelab ini, intent Class List adalah intent yang paling tepat karena dialog akan berubah setiap hari, dan pengguna mungkin ingin diingatkan tentang class apa saja yang tersedia.

Ikuti langkah-langkah berikut guna mengaktifkan update harian untuk intent Daftar Kelas:

1. Di Konsol Actions, klik tab Develop, dan pilih Actions di menu navigasi sebelah kiri.
2. Klik Daftar Kelas pada daftar Tindakan.
3. Di bagian Engagement pengguna, alihkan opsi Ingin menawarkan informasi terbaru harian kepada pengguna.
4. Tetapkan Judul konten deskriptif yang mendeskripsikan pembaruan harian. Konteksnya adalah "Jam berapa Anda ingin saya mengirimkan <judul konten>" harian, jadi pastikan judul Anda deskriptif dan terdengar benar saat diucapkan. 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 ini 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 info terbaru harian. Di konsol Dialogflow, klik tombol + di samping Intent di navigasi kiri untuk membuat intent baru.
2. Beri nama untuk 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 webhook call for this intent.
5. Klik Simpan di bagian atas halaman.

Menangani keputusan pengguna

1. Menyiapkan intent baru untuk menangani respons pengguna terhadap dialog langganan update harian. Klik tombol + di samping Intent di navigasi kiri untuk membuat intent baru.
2. Beri nama untuk 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, baik pada akhirnya mereka berlangganan atau tidak.
4. Di bagian Fulfillment, alihkan opsi Enable webhook call for this intent.
5. Klik Simpan di bagian atas halaman.

Mengimplementasikan fulfillment

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

Memuat dependensi

Pada file index.js, perbarui 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');

Memperbarui chip saran

Di file index.js, tambahkan entri DAILY ke daftar judul chip saran, sehingga definisi Suggestion Anda 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 ingin berlangganan, mulai alur langganan update harian dengan memanggil helper RegisterUpdate dengan intent target update (Daftar Class) dan jenis (DAILY). Setelah alur langganan selesai, Asisten memicu peristiwa actions_intent_REGISTER_UPDATE dengan argumen status yang menjelaskan apakah langganan berhasil atau tidak. Tawarkan perintah lanjutan kepada pengguna yang dapat berubah bergantung pada status langganan.

Di 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 kepada pengguna

Respons Daftar Kelas Anda akan menawarkan langganan update harian di bagian akhir, tetapi ini menimbulkan masalah. Karena respons yang sama ini akan dipicu ketika pengguna mengetuk notifikasi update harian, mereka akan tetap diminta untuk berlangganan update harian meskipun mereka baru saja berlangganan. Bagaimana Anda bisa menjaga pengguna agar tidak berpikir bahwa mereka perlu berlangganan kembali?

Untungnya, argumen objek conv Anda menyertakan 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 yang sesuai. Anda juga dapat menggunakan cabang percakapan ini untuk menutup dialog segera setelah menyediakan daftar class, yang mengikuti praktik terbaik kami untuk membuat update harian tetap singkat.

Di 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]));
    };
  };
});

Uji pembaruan harian Anda

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

firebase deploy

Tips: Anda dapat menemukan informasi terbaru tentang penggunaan simulator Tindakan di Panduan simulator tindakan. Lihat halaman tersebut jika Anda mengalami masalah saat mengikuti langkah-langkah yang tercantum di bawah ini.

Untuk menguji perintah ulang kustom Anda di simulator Tindakan, 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 lalu tekan enter. Respons Action Anda kini akan menawarkan untuk mengirim pengingat harian.
4. Ketik Send daily reminders lalu tekan enter.
5. Ketik waktu yang Anda inginkan untuk melihat pembaruan dan tekan enter. Untuk tujuan pengujian, coba respons dengan waktu 3-5 menit lebih lama dari waktu saat ini.

Jika Anda mendapatkan error saat mencoba berlangganan info harian di langkah #4, kembali ke Build > Tindakan > Daftar Kelas dan nonaktifkan pembaruan harian. Klik Simpan, aktifkan kembali pembaruan harian, klik Simpan lagi, lalu coba lakukan pengujian di Simulator lagi.

Di perangkat seluler, Anda akan menerima notifikasi dari Asisten sekitar waktu yang telah ditentukan untuk update. Perlu diperhatikan bahwa mungkin perlu waktu beberapa menit hingga notifikasi ini muncul. Ketuk notifikasi tersebut dan notifikasi akan membuat deep link langsung ke intent Daftar Kelas di Asisten, sehingga Anda akan mendapatkan daftar kelas mendatang:

4. Tambahkan notifikasi push

Sebagai opsi lain untuk berinteraksi dengan pengguna di luar Action, Anda dapat memanggil Actions API untuk mengirim notifikasi push kepada pengguna. Tidak seperti info terbaru harian, notifikasi ini tidak otomatis dijadwalkan oleh Asisten sehingga Anda dapat mengirimkannya sesuai keinginan.

Istilah utama:

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

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

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

Istilah utama:

• Penunjang: Penolong adalah intent yang, saat 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 mengirimkan notifikasi push kepada pengguna di luar percakapan, Anda harus menyimpan ID pengguna di tempat yang dapat ditarik kembali. Dalam contoh ini, Anda akan menyiapkan database Firestore untuk menyimpan informasi setiap pengguna.

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

Bagaimana hal ini akan melibatkan pengguna?

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

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

• Rencanakan beberapa contoh jadwal untuk notifikasi push Anda. Jika Anda berencana hanya mengirim satu notifikasi push per hari, pertimbangkan untuk menggunakan update harian.
• Pastikan notifikasi push Anda akan memberikan informasi yang berguna setiap kali diterima. Notifikasi Anda juga bisa membuat deep link ke salah satu intent Action Anda, jadi pastikan intent tersebut berguna dan relevan.
• Berterus terang saat meminta pengguna untuk berlangganan notifikasi push. Mereka harus memahami apa yang diharapkan dari setiap notifikasi push, dan memiliki gambaran tentang seberapa sering notifikasi tersebut dikirim.

Tips: Tinjau praktik terbaik kami untuk merancang 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 atau tidak.

Mengaktifkan Actions API

1. Buka Konsol Google Cloud dan pilih nama project Actions Anda di dropdown.

2. Di menu navigasi (☰), buka API & Layanan > Koleksi.
3. Telusuri Actions API, lalu klik Enable.

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 Konsol Google Cloud (☰), buka API & Layanan > Kredensial.
2. Klik Create credentials > 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 oleh @<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.

Mengaktifkan Firestore

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

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

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

Tips: Kami hanya menggunakan aturan keamanan mode pengujian untuk tujuan pengujian. Anda harus memiliki aturan keamanan data yang lebih andal sebelum Action dipublikasikan dalam 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 kelas yang dibatalkan. Di konsol Dialogflow, klik tombol + di samping Intent di navigasi 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 webhook call for this intent.
5. Klik Simpan di bagian atas halaman.

Menangani keputusan pengguna

1. Siapkan intent baru untuk menangani respons pengguna terhadap dialog langganan notifikasi push. Klik tombol + di samping Intent di navigasi kiri untuk membuat intent baru.
2. Beri nama untuk 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, baik pada akhirnya mereka berlangganan atau tidak.
4. Di bagian Fulfillment, alihkan opsi Enable webhook call 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 akan memiliki deep link langsung ke intent tersebut di 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 di navigasi 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 webhook call for this intent.
5. Klik Simpan di bagian atas halaman.

Mengirim notifikasi pengujian di tengah percakapan

Dalam produksi, Anda harus memiliki 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 sambil berbicara dengan Action Anda. Intent ini hanya untuk tujuan debug; dalam praktiknya, notifikasi push seharusnya tidak ditangani oleh pemenuhan Anda atau dipicu sebagai bagian dari percakapan Action Anda.

Ikuti langkah-langkah berikut guna 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 di navigasi kiri untuk membuat intent baru.
2. Beri nama untuk intent baru ini Test Notification.
3. Di bagian Frasa pelatihan, tambahkan Test notification sebagai ekspresi pengguna.
4. Di bagian Fulfillment, alihkan opsi Enable webhook call for this intent.
5. Klik Simpan di bagian atas halaman.

Aktifkan notifikasi push

Ikuti langkah-langkah berikut guna mengaktifkan notifikasi push untuk intent Kelas Dibatalkan:

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

5. Di Konsol Actions, klik tab Develop, dan pilih Actions di menu navigasi sebelah kiri.
6. Klik Kelas Dibatalkan di bagian daftar Tindakan.
7. Di bagian Engagement pengguna, aktifkan opsi Apakah Anda ingin mengirim notifikasi push?.
8. Tetapkan Judul konten deskriptif yang mendeskripsikan notifikasi push. Konteksnya adalah "Apakah boleh jika saya mengirim notifikasi push untuk <judul konten>?", jadi pastikan judul Anda bersifat deskriptif dan terdengar benar saat diucapkan dengan lantang. Untuk contoh ini, tetapkan Judul konten ke class cancelations.
9. Klik Simpan di bagian atas halaman.

Mengimplementasikan fulfillment

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

Memuat dependensi

Pada file index.js, perbarui 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');

Memperbarui chip saran

Di file index.js, tambahkan entri NOTIFICATIONS ke daftar judul chip saran, sehingga definisi Suggestion Anda 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 dapat terhubung ke database Firestore Anda, tambahkan paket firebase-admin dan tambahkan konstanta untuk kolom yang disimpan di 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

Di 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 berhasil, argumen PERMISSION akan ditambahkan ke argumen objek conv yang dapat Anda periksa untuk melakukan pivot percakapan.

Setelah mendapatkan izin pengguna, ambil ID pengguna dari argumen objek conv, lalu simpan di 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 ini yang siap produksi, skrip notifikasi Anda akan memberikan informasi yang lebih dinamis tentang class yang telah dibatalkan.

Di 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 Anda dan mengirimkan notifikasi push ke setiap pengguna yang berlangganan notifikasi.

Perlu diingat bahwa dalam contoh ini, Anda menyertakan kode yang mengirim notifikasi push di fulfillment webhook Anda dan memicu kode tersebut dengan memanggil intent pengujian dalam percakapan Anda. Dalam Actions yang ingin Anda publikasikan, kode notifikasi push harus ada dalam skrip yang terpisah dari fulfillment Anda.

Di 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 Anda

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

firebase deploy

Tips: Anda dapat menemukan informasi terbaru tentang penggunaan simulator Tindakan di Panduan simulator tindakan. Lihat halaman tersebut jika Anda mengalami masalah saat mengikuti langkah-langkah yang tercantum di bawah ini.

Untuk menguji notifikasi di simulator Tindakan, 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 lalu tekan enter.
4. Ketik Get notifications lalu tekan enter.
5. Jika Anda belum memberikan izin Tindakan untuk mengirimkan notifikasi push, ketik yes, lalu tekan enter.
6. Ketik yes lalu tekan enter. Akun Google Anda sekarang seharusnya sudah berlangganan notifikasi push untuk Action ini.

Jika Anda mendapatkan pesan error saat mencoba berlangganan notifikasi push di langkah #4, kembali ke Build > Tindakan > Kelas Dibatalkan dan nonaktifkan notifikasi dorong. Klik Simpan, aktifkan kembali notifikasi push, klik Simpan lagi, lalu coba lakukan pengujian di Simulator lagi.

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

Dalam beberapa menit Anda akan menerima "Notifikasi Pengujian dari Action Gym" Notifikasi push Asisten di perangkat seluler Anda. Mengetuk notifikasi ini akan membuat deep link Anda ke intent Kelas Dibatalkan dari Action Anda.

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

5. Buat link Asisten

Sejauh ini kita telah membahas fitur interaksi yang dapat Anda terapkan agar pengguna terus kembali ke Action Anda, tetapi fitur tersebut didasarkan pada jumlah pengguna yang menemukan dan menggunakan Action Anda.

Anda dapat membuat link Asisten yang akan menautkan pengguna di perangkat seluler langsung ke Action di Asisten Anda. 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 Anda, dan cara menambahkannya ke situs sederhana untuk pengujian.

Bagaimana hal ini akan melibatkan pengguna?

Menarik pengguna ke Action untuk pertama kalinya bisa jadi sulit, terutama saat mereka perlu memanggil Action di Asisten secara eksplisit. Link Asisten mengurangi hambatan ini dengan memberi pengguna link langsung ke Action Anda. 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, ia akan tetap diarahkan ke listingan direktori Actions (jika sudah dipublikasikan) sehingga link 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 dalam status draf, link hanya akan berfungsi di perangkat Anda. Orang lain akan diarahkan ke halaman 404 di direktori Tindakan.
• Anda dapat mengizinkan pengguna menguji link Asisten sebelum publikasi dengan merilis Action di lingkungan alfa atau beta. Perhatikan bahwa hanya pengguna yang berpartisipasi dalam versi alfa atau beta Anda yang dapat menguji link Asisten Anda.
• Pastikan intent tujuan untuk link Asisten Anda memberikan kesan pertama yang baik bagi 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 yang mengarahkan pengguna ke intent selamat datang, tetapi ada banyak hal lain 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 selamat datang:

1. Di Konsol Actions, klik tab Develop, dan pilih Actions di menu navigasi sebelah kiri.
2. Klik actions.intent.MAIN dalam daftar Actions.
3. Di bagian Link, aktifkan opsi Ingin mengaktifkan URL untuk Tindakan ini.
4. Tetapkan Judul link deskriptif yang mendeskripsikan Action Anda. Buat judul Anda menjadi pasangan kata kerja-kata benda sederhana yang menggambarkan apa yang dapat dicapai pengguna dengan Action Anda. Untuk contoh ini, tetapkan Judul link ke learn about Action Gym.
5. Salin cuplikan HTML dari bagian bawah halaman ini dan 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 pengujian bersama dengan fulfillment Anda. Kami sudah 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, tempel cuplikan HTML link Asisten Anda ke elemen isi. File akan terlihat seperti cuplikan di bawah ini:

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 di 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 kini telah mempelajari pentingnya engagement pengguna saat mengembangkan Action, fitur engagement pengguna apa yang tersedia di platform, dan cara menambahkan setiap fitur ke Action.

Referensi pembelajaran tambahan

Jelajahi referensi berikut untuk mempelajari lebih lanjut engagement pengguna untuk Action Anda:

• Engagement 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 menampilkan retensi pengguna untuk Action yang Anda publikasikan.
• Pedoman desain percakapan: Praktik terbaik dan panduan cara 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 Anda melanjutkan, harap isi formulir ini untuk memberitahukan performa kami.