Berinteraksi dengan pengguna menggunakan Action untuk Asisten Google

1. Ringkasan

Peringatan: Action Percakapan tidak 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 melalui percakapan untuk menyelesaikan berbagai hal, seperti membeli bahan makanan atau memesan transportasi online. (Untuk daftar lengkap hal yang dapat dilakukan, 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 Anda.

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 membiasakan diri dengan platform ini dengan mengikuti codelab pengantar kami ( Level 1, Level 2, dan Level 3). Modul lanjutan ini akan memberikan panduan tentang serangkaian fitur yang dapat membantu Anda memperluas fungsi Action dan meningkatkan jumlah audiens.

Salah satu cara penting untuk mengukur keberhasilan Tindakan adalah engagement pengguna atau seberapa efektif Tindakan dalam membuat pengguna kembali setelah interaksi pertama mereka. Untuk mempermudah hal tersebut, Anda dapat menerapkan beberapa fitur di Action yang memberikan jalur bagi pengguna untuk kembali ke percakapan Anda.

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

Yang akan Anda build

Anda akan meningkatkan kualitas fitur yang sudah dibuat dengan mengaktifkannya agar dapat:

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

Yang akan Anda pelajari

• Apa itu engagement pengguna dan mengapa hal ini penting untuk kesuksesan Action
• Cara mengubah Tindakan untuk meningkatkan engagement pengguna
• Fitur engagement pengguna 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 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 Tindakan yang sudah selesai dan dibuat sebelumnya.

Istilah utama:

• Engagement pengguna: Metrik yang digunakan untuk mengukur apakah pengguna menemukan nilai dalam suatu produk atau layanan. Engagement dapat diukur dengan jumlah pengguna yang kembali ke Action Anda, yang merupakan salah satu metrik yang digunakan untuk menentukan apakah akan mempromosikan Action. Engagement pengguna yang tinggi berasal dari dua komponen Tindakan—informasi berguna yang ingin dilihat pengguna di lain waktu dan cara bagi pengguna untuk kembali ke Tindakan Anda saat mereka kemungkinan besar akan mengambil informasi tersebut.

Memahami sampel

Contoh untuk codelab ini adalah Action sederhana untuk pusat kebugaran fiktif bernama "Action Gym". Action ini memberikan informasi tentang gym, termasuk daftar kelas yang berganti setiap hari. Tindakan informatif seperti ini adalah kandidat yang baik untuk semua fitur engagement pengguna karena daftar kelas yang berputar memberikan informasi berguna yang berbeda setiap hari.

Diagram berikut menunjukkan alur percakapan contoh Action Gym:

Anda akan membuat sedikit perubahan pada dialog agar lebih sesuai dengan fitur engagement 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, selesaikan langkah-langkah berikut:

1. Buka Konsol Actions.
2. Klik Project baru.
3. Ketikkan Project name, seperti engagement-codelab.
4. Klik Buat Project.
5. Daripada memilih kategori, scroll ke bawah ke bagian Opsi lainnya, lalu klik kartu Percakapan.
6. Klik Build your Action untuk meluaskan opsi, lalu 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 Create.
10. Klik (ikon roda gigi) di navigasi 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, lalu klik Pulihkan.
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 "Terjadi error tak terduga dari 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 memberikan URL ke fungsi cloud ke Dialogflow. Untuk mengambil URL ini, ikuti langkah-langkah berikut:

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

Menetapkan URL webhook di Dialogflow

Sekarang Anda perlu mengupdate agen Dialogflow untuk menggunakan webhook Anda untuk pemenuhan. Untuk melakukannya, ikuti langkah-langkah ini:

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

Pastikan project Anda disiapkan dengan benar

Pengguna harus dapat memanggil Action Anda untuk mendapatkan informasi tentang Action Gym, termasuk respons teks yang dikodekan secara permanen dengan jam buka dan respons teks yang mencantumkan jadwal kelas untuk setiap hari dalam seminggu.

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

Untuk menguji Action Anda di simulator Actions:

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

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

3. Menambahkan langganan info terbaru harian

Cara umum untuk berinteraksi dengan pengguna adalah dengan menawarkan informasi kepada mereka saat informasi tersebut paling berguna. Hal ini dapat dilakukan dengan menawarkan opsi kepada pengguna untuk berlangganan pembaruan harian untuk suatu maksud, yang akan mengirimkan notifikasi Asisten yang ditautkan langsung ke pemenuhan maksud tersebut.

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

Bagaimana cara ini akan membuat pengguna tertarik?

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

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

• Pastikan pembaruan harian akan menghasilkan informasi yang berbeda dan berguna bagi pengguna setiap hari. Jika mengetuk update harian menghasilkan perintah yang sama setiap saat, pengguna mungkin akan berhenti berlangganan setelah beberapa hari.
• Pastikan dialog Anda masuk akal bagi pengguna jika mereka langsung membuka maksud update harian Anda. Pengguna Anda tidak harus memulai percakapan dari awal, jadi mereka tidak diharapkan memiliki banyak konteks.
• Tunjukkan manfaat Action Anda kepada pengguna sebelum meminta mereka berlangganan update harian. Pengguna Anda harus berpikir "Saya ingin konten ini setiap hari" saat mereka diberi opsi untuk berlangganan.
• Jangan membuat pengguna bingung dengan saran untuk berlangganan yang berulang. Tawarkan langganan info terbaru harian tepat setelah menunjukkan kepada pengguna apa yang akan mereka langgani, dan hindari mengganggu mereka tentang hal itu di tempat lain.
• Buat percakapan singkat setelah maksud pembaruan dipicu. Sebagian besar update harian hanya boleh 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 info harian telah didesain sebelumnya untuk Asisten, tetapi prinsip yang sama berlaku saat memutuskan apakah info harian sesuai untuk maksud atau Tindakan Anda.

Mengaktifkan update harian

Langganan info terbaru harian dapat ditambahkan ke intent sambutan yang menempatkan pengguna di awal percakapan Anda, atau intent yang lebih spesifik untuk melakukan deep link ke suatu tempat dalam percakapan. Untuk codelab ini, maksud Class List adalah yang paling tepat karena dialog akan berubah setiap hari, dan pengguna mungkin merasa berguna jika diingatkan tentang kelas yang tersedia.

Ikuti langkah-langkah berikut untuk mengaktifkan pembaruan harian untuk intent Daftar Kelas:

1. Di Konsol Actions, klik tab Develop, lalu pilih Actions di menu navigasi kiri.
2. Klik Daftar Kelas di bagian daftar Tindakan.
3. Di bagian Engagement pengguna, aktifkan atau nonaktifkan opsi Apakah Anda ingin menawarkan info terbaru harian kepada pengguna.
4. Tetapkan Judul konten deskriptif yang menjelaskan info terbaru harian. Konteksnya adalah "Mau saya kirimi " harian jam berapa, 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 berikut di konsol Dialogflow untuk membuat intent bagi alur langganan info harian:

Minta pengguna untuk berlangganan

1. Siapkan intent baru untuk menangani permintaan pengguna agar berlangganan info terbaru harian. Di konsol Dialogflow, klik tombol + di samping Intents di navigasi kiri untuk membuat intent baru.
2. Beri nama intent baru ini Setup Updates.
3. Di bagian Training phrases, tambahkan user expressions berikut:

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

4. Di bagian Fulfillment, aktifkan 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 perintah langganan info terbaru harian. Klik tombol + di samping Intent di navigasi 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 info harian, baik mereka akhirnya berlangganan atau tidak.
4. Di bagian Fulfillment, aktifkan opsi Enable webhook call for this intent.
5. Klik Simpan di bagian atas halaman.

Menerapkan pemenuhan

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

Memuat dependensi

Dalam 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');

Chip saran pembaruan

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 pemenuhan untuk maksud baru

Saat pengguna mengatakan ingin berlangganan, mulai alur langganan info terbaru harian dengan memanggil helper RegisterUpdate dengan maksud target info terbaru (Class List) dan jenis (DAILY). Setelah alur langganan selesai, Asisten akan memicu peristiwa actions_intent_REGISTER_UPDATE dengan argumen status yang menjelaskan apakah langganan berhasil atau tidak. Menawarkan perintah lanjutan kepada pengguna yang 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 info harian di akhir, tetapi hal ini menimbulkan masalah. Karena respons yang sama ini akan dipicu saat pengguna mengetuk notifikasi info harian, mereka akan tetap diminta untuk berlangganan info harian meskipun baru saja berlangganan. Bagaimana cara mencegah pengguna berpikir bahwa mereka perlu berlangganan ulang?

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 info harian, dan mengubah respons yang sesuai. Anda juga dapat menggunakan cabang percakapan ini untuk menutup dialog segera setelah memberikan daftar kelas, yang mengikuti praktik terbaik kami untuk menjaga agar info 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]));
    };
  };
});

Menguji info terbaru harian Anda

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

firebase deploy

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

Untuk menguji perintah ulang kustom di simulator Actions, 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 sekarang akan menawarkan untuk mengirimkan pengingat harian.
4. Ketik Send daily reminders, lalu tekan enter.
5. Ketik waktu yang Anda inginkan untuk melihat pembaruan, lalu tekan enter. Untuk tujuan pengujian, coba berikan respons 3-5 menit setelah waktu saat ini.

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

Di perangkat seluler, Anda akan menerima notifikasi dari Asisten sekitar waktu yang Anda tentukan untuk mendapatkan info terbaru. Perhatikan bahwa notifikasi ini mungkin memerlukan waktu beberapa menit untuk muncul. Ketuk notifikasi dan notifikasi akan melakukan deep-link langsung ke maksud Daftar Kelas di Asisten, sehingga Anda akan mendapatkan daftar kelas mendatang:

4. Menambahkan notifikasi push

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

Istilah utama:

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

Pada langkah ini, Anda akan mempelajari cara menerapkan notifikasi push di Tindakan Anda dengan menambahkan intent Class Canceled baru dan mengirim 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 perlu menyiapkan akun layanan dan kredensial untuk berinteraksi dengan API ini.
• Bantuan izin - Anda memerlukan izin pengguna untuk mengakses ID pengguna yang diperlukan untuk mengirimkan notifikasi push kepada mereka. Dalam contoh ini, Anda akan menggunakan fungsi library klien untuk memanggil helper izin dan meminta ID ini.

Istilah utama:

• Helper: Helper adalah intent yang, saat dipenuhi, memungkinkan Asisten mengambil alih percakapan untuk sementara waktu 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 suatu tempat yang dapat dipanggil kapan saja. 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 Anda:

Bagaimana cara ini akan membuat pengguna tertarik?

Pengguna smartphone mungkin sudah 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 update 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 menerima banyak notifikasi per hari.

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

• 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 dapat memiliki deep link ke salah satu intent Tindakan Anda, jadi pastikan intent tersebut berguna dan relevan.
• Tunjukkan secara jelas saat meminta pengguna untuk berlangganan notifikasi push. Mereka harus memahami apa yang akan mereka dapatkan dari setiap notifikasi push, dan memiliki gambaran tentang seberapa sering notifikasi dikirim.

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

Mengaktifkan Actions API

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

2. Di menu navigasi (☰), buka APIs & Services > Library.
3. Telusuri Actions API, lalu 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 APIs & Services > Credentials.
2. Klik Create credentials > Service account key.
3. Di menu drop-down Service account, pilih New Service Account.
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 mengirim notifikasi di luar percakapan, Anda memerlukan cara untuk menyimpan ID pengguna yang dapat dirujuk dari kode notifikasi Anda. Untuk contoh ini, kita menggunakan database Firestore untuk menyimpan ID pengguna yang berlangganan.

Ikuti langkah-langkah berikut untuk membuat database Firestore untuk Tindakan Anda:

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

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

Menyiapkan Dialogflow

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

Minta pengguna untuk berlangganan

1. Siapkan intent baru untuk menangani permintaan pengguna agar berlangganan notifikasi push untuk kelas yang dibatalkan. Di konsol Dialogflow, klik tombol + di samping Intents di navigasi kiri untuk membuat intent baru.
2. Beri nama intent baru ini Setup Push Notifications.
3. Di bagian Training phrases, tambahkan user expressions berikut:

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

4. Di bagian Fulfillment, aktifkan 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 perintah berlangganan notifikasi push. Klik tombol + di samping Intent di navigasi 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, aktifkan 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 diarahkan melalui deep link langsung ke intent tersebut di Action Anda. Dalam contoh ini, tambahkan intent baru untuk notifikasi push yang memberikan detail tentang kelas yang dibatalkan.

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

1. Di konsol Dialogflow, klik tombol + di samping Intents 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, aktifkan 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 terpisah dari kode pemenuhan Tindakan yang mengirimkan notifikasi push. Untuk contoh ini, buat intent yang dapat Anda panggil untuk mengirimkan notifikasi push saat berbicara dengan Action Anda. Maksud ini hanya untuk tujuan debug; dalam praktiknya, notifikasi push tidak boleh ditangani oleh pemenuhan atau dipicu sebagai bagian dari percakapan Tindakan Anda.

Ikuti langkah-langkah berikut untuk membuat intent guna 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 Intents di navigasi 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, aktifkan opsi Enable webhook call for this intent.
5. Klik Simpan di bagian atas halaman.

Aktifkan notifikasi push

Ikuti langkah-langkah berikut untuk mengaktifkan notifikasi push untuk maksud Class Canceled:

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

5. Di Konsol Actions, klik tab Develop, lalu pilih Actions di menu navigasi 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 menjelaskan notifikasi push. Konteksnya adalah "Boleh saya kirim notifikasi push untuk ?", jadi pastikan judul Anda deskriptif dan terdengar benar saat diucapkan. Untuk contoh ini, tetapkan Judul konten ke class cancelations.
9. Klik Simpan di bagian atas halaman.

Menerapkan pemenuhan

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

Memuat dependensi

Dalam 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');

Chip saran pembaruan

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

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

Di 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');

Menawarkan 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 pemenuhan untuk maksud baru

Saat pengguna mengatakan 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 memutar percakapan.

Setelah Anda mendapatkan izin pengguna, ambil ID pengguna dari argumen objek conv dan simpan di database Anda. Anda akan mengirimkan ID pengguna ini ke Actions API nanti, 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 Tindakan yang siap produksi, skrip notifikasi Anda akan memberikan informasi yang lebih dinamis tentang kelas mana 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 mengirimkan notifikasi push kepada pengguna, kirim permintaan POST ke Actions API dengan ID pengguna, judul notifikasi, dan intent target. Dalam contoh ini, memicu maksud Test Notification akan melakukan iterasi melalui database Firestore Anda dan mengirimkan notifikasi push ke setiap pengguna yang telah berlangganan notifikasi.

Ingatlah bahwa dalam contoh ini, Anda menyertakan kode yang mengirimkan notifikasi push dalam pemenuhan webhook dan memicu kode tersebut dengan memanggil maksud pengujian dalam percakapan Anda. Dalam Tindakan yang ingin Anda publikasikan, kode notifikasi push harus ada dalam skrip yang terpisah dari pemenuhan 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 diupdate ke Firebase:

firebase deploy

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

Untuk menguji notifikasi di simulator Actions, 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 kepada Action untuk mengirimkan notifikasi push, ketik yes, lalu tekan enter.
6. Ketik yes, lalu tekan enter. Akun Google Anda kini akan berlangganan notifikasi push untuk Tindakan ini.

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

7. Ketik no dan 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 push Asisten "Test Notification from Action Gym" di perangkat seluler Anda. Mengetuk notifikasi ini akan membuka deep link ke maksud Class Canceled pada Tindakan Anda.

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

5. Membuat link Asisten

Sejauh ini kita telah membahas fitur engagement yang dapat Anda terapkan untuk membuat pengguna kembali menggunakan Action Anda, tetapi fitur tersebut didasarkan pada pengguna yang menemukan dan menggunakan Action Anda.

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

Pada langkah ini, Anda akan mempelajari apa itu link Asisten, cara membuatnya untuk maksud sambutan Action Anda, dan cara menambahkannya ke situs sederhana untuk pengujian.

Bagaimana cara ini akan membuat pengguna tertarik?

Menarik pengguna ke Action Anda untuk pertama kalinya bisa jadi sulit, terutama saat mereka perlu memanggil Action Anda secara eksplisit di Asisten. Link Asisten mengurangi hambatan ini dengan memberi pengguna link langsung ke Tindakan Anda. Saat pengguna membuka link Asisten Anda di perangkat yang kompatibel dengan Asisten, mereka akan langsung diarahkan ke Tindakan Anda. Saat pengguna membuka link Anda di perangkat non-seluler atau perangkat lain yang tidak mendukung Asisten, mereka akan tetap diarahkan ke listingan direktori Tindakan Anda (jika telah dipublikasikan) sehingga link tersebut tetap dapat memasarkan Tindakan Anda kepada pengguna tersebut.

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

• Link Asisten hanya berfungsi setelah Tindakan 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 dipublikasikan 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 maksud tujuan untuk link Asisten Anda memberikan kesan pertama yang baik bagi pengguna baru. Maksud sambutan Anda adalah tujuan default untuk link Asisten karena maksud ini sudah cukup baik dalam memperkenalkan Action Anda

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

Mengaktifkan link Asisten

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

1. Di Konsol Actions, klik tab Develop, lalu pilih Actions di menu navigasi kiri.
2. Klik actions.intent.MAIN di bagian daftar Actions.
3. Di bagian Link, aktifkan opsi Apakah Anda ingin mengaktifkan URL untuk Tindakan ini.
4. Tetapkan Judul link deskriptif yang menjelaskan Tindakan Anda. Buat judul Anda menjadi pasangan kata kerja-kata benda sederhana yang menjelaskan apa yang dapat dilakukan pengguna dengan Tindakan Anda. Untuk contoh ini, setel 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 pengujian

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

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

Di file index.html, tempelkan cuplikan HTML link Asisten Anda ke dalam elemen body. File 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>

Menguji 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 Anda dan Anda akan melihat link Asisten di situs pengujian Anda. Dengan mengklik link ini di perangkat seluler, Anda akan diarahkan ke maksud sambutan 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 belum dipublikasikan.

6. Langkah berikutnya

Selamat!

Sekarang Anda telah mempelajari pentingnya engagement pengguna saat mengembangkan Tindakan, fitur engagement pengguna yang tersedia di platform, dan cara menambahkan setiap fitur ke Tindakan.

Referensi pembelajaran tambahan

Pelajari 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 engagement pengguna secara umum.
• Analisis retensi pengguna: Dokumentasi untuk fitur analisis di konsol Actions yang menunjukkan retensi pengguna untuk Action yang dipublikasikan.
• Pedoman desain percakapan: Praktik terbaik dan pedoman tentang cara mendesain fitur engagement pengguna.
• Repo GitHub Actions on Google: Kode contoh dan library.
• r/GoogleAssistantDev: Komunitas Reddit resmi untuk developer yang menangani 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, isi formulir ini untuk memberi tahu kami tentang kualitas layanan kami.