דף זה תורגם על ידי Cloud Translation API.

לעורר עניין בקרב המשתמשים באמצעות הפעולה ב-Google Assistant

1. סקירה כללית

Actions on Google היא פלטפורמה למפתחים שמאפשרת ליצור תוכנה כדי להרחיב את הפונקציונליות של Google Assistant, העוזרת האישית הווירטואלית של Google, שכוללת יותר ממיליארד מכשירים, כולל רמקולים חכמים, טלפונים, מכוניות, טלוויזיות, אוזניות ועוד. המשתמשים מעורבים בשיחה עם Assistant כדי לבצע פעולות, כמו קניית מצרכים או הזמנת נסיעה. (רשימה מלאה של הפעולות האפשריות זמינה במאגר הפעולות). כמפתחים, אתם יכולים להשתמש ב-Actions on Google כדי ליצור ולנהל בקלות חוויות שיחה יעילות ומעניינות בין המשתמשים לבין שירות הצד השלישי.

זהו מודול Codelab מתקדם שנועד לקוראים שכבר יש להם ניסיון מסוים בפיתוח פעולות ל-Google Assistant. אם אין לכם ניסיון פיתוח קודם ב-Actions on Google, מומלץ מאוד להכיר את הפלטפורמה בעזרת Codelabs המבוא שלנו ( רמה 1, רמה 2 ורמה 3). במודולים המתקדמים האלה, תוכלו למצוא סדרת תכונות שיעזרו לכם להרחיב את הפונקציונליות של הפעולה ולהגדיל את הקהל שלכם.

אחת הדרכים החשובות למדידת ההצלחה של פעולה היא מעורבות המשתמשים, או מידת האפקטיביות של הפעולה בניסיון להחזיר משתמשים אחרי האינטראקציה הראשונה שלהם. כדי להקל על התהליך, אפשר להטמיע כמה תכונות בפעולה שיעניקו למשתמשים נתיבים חוזרים לשיחה.

ב-Codelab מפורטים תכונות לעידוד משתמשים ושיטות מומלצות לשימוש ב-Actions on Google.

מה תפַתחו

תשפרו תכונה שכבר נוצרה על ידי הפעלת האפשרות:

ניתן לשלוח למשתמשים עדכון יומי שהם יכולים להקיש כדי לדבר עם הפעולה
שליחת התראות למשתמשים עם קישור לפעולה
יצירת קישור שמעביר את המשתמשים לפעולה מדפדפן אינטרנט לנייד

מה תלמדו

מהי התעניינות המשתמשים ולמה היא חשובה להצלחת הפעולה
איך לשנות פעולה כדי להגביר את התעניינות המשתמשים
באילו תכונות של התעניינות משתמשים כדאי להשתמש בסוגים שונים של פעולות
איך משתמשים ב-Actions API כדי לשלוח התראות דרך Assistant

מה נדרש

צריכים להיות לכם את הכלים הבאים:

עורך IDE/טקסט לפי בחירה, כמו WebStorm , Atom או Sublime
טרמינל להרצת פקודות מעטפת עם Node.js , npm ו-Git מותקנים
דפדפן אינטרנט, כמו Google Chrome
סביבת פיתוח מקומית עם ממשק שורת הפקודה של Firebase
מכשיר נייד (Android או iOS) עם Assistant (צריך להיות מחוברים ל-Assistant עם אותו חשבון Google שבו תשתמשו כדי לבנות את הפרויקט הזה).

בנוסף, מומלץ להכיר את JavaScript (ES6), אם כי לא נדרש, כדי להבין את קוד ה-webhook.

2. הגדרת הפרויקט

בקטע הזה מוסבר איך להוסיף תכונות של התעניינות משתמשים לפעולה שלמה שנוצרה בעבר.

הסבר על הדוגמה

הדוגמה של Codelab זה היא פעולה פשוטה עבור מכון כושר בדיוני בשם 'Action Gym'. הפעולה מספקת מידע על מכון הכושר, כולל רשימת כיתות שמתחלפות בכל יום. פעולה אינפורמטיבית, כמו זו, מתאימה לכל התכונות של התעניינות המשתמשים, כי רשימת הכיתות המתחלפות מספקת מידע שימושי שונה בכל יום.

בתרשים הבא מוצג תהליך השיחה לדוגמה של Action Gym:

תבצעו שינויים קלים בתיבת הדו-שיח כדי שתתאים יותר לתכונות של מעורבות המשתמשים שהוספתם. אבל העיצוב הכללי של השיחה לא ישתנה במידה רבה.

הורדת הקבצים הבסיסיים

כדי לשכפל את המאגר של GitHub בשביל ה-Codelab, מריצים את הפקודה הבאה:

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

הגדרת הפרויקט ונציג התמיכה

כדי להגדיר את פרויקט הפעולות וסוכן של Dialogflow:

פותחים את מסוף Actions.
לוחצים על פרויקט חדש.
מקלידים שם הפרויקט, למשל engagement-codelab.
לוחצים על Create Project.
במקום לבחור קטגוריה, גוללים למטה לקטע אפשרויות נוספות ולוחצים על הכרטיס שיחות.
לוחצים על יצירת הפעולה כדי להרחיב את האפשרויות ובוחרים באפשרות הוספת פעולות.
לוחצים על הוספת הפעולה הראשונה.
בתיבת הדו-שיח Create Action, בוחרים באפשרות Custom Intent ואז לוחצים על Build כדי להפעיל את מסוף Dialogflow.
בדף ליצירת נציג תמיכה במסוף Dialogflow, לוחצים על Create.
לוחצים על (סמל גלגל השיניים) בתפריט הניווט הימני.
לוחצים על ייצוא וייבוא ואז על שחזור מ-Zip.
מעלים את הקובץ agent.zip מהספרייה /user-engagement-codelab-nodejs/start/ שהורדתם קודם.
מקלידים RESTORE ולוחצים על Restore.
לוחצים על סיום.

איך פורסים את מילוי ההזמנות

עכשיו, כשפרויקט הפעולות והסוכן של Dialogflow מוכנים, פורסים את קובץ index.js המקומי באמצעות ה-CLI של Firebase Functions.

מהספרייה /user-engagement-codelab-nodejs/start/functions/ של השכפול של קובצי הבסיס, מריצים את הפקודות הבאות:

firebase use <PROJECT_ID>

npm install

firebase deploy

אחרי כמה דקות תופיע ההודעה הפריסה הושלמה!. פירוש הדבר הוא שפרסתם בהצלחה את ה-webhook ל-Firebase.

אחזור כתובת ה-URL לפריסה

עליכם לספק ל-Dialogflow את כתובת ה-URL של הפונקציה ב-Cloud Functions. כדי לאחזר את כתובת ה-URL הזו, צריך לבצע את השלבים הבאים:

פותחים את מסוף Firebase.
בוחרים את פרויקט הפעולות מרשימת האפשרויות.
עוברים אל פיתוח > פונקציות בסרגל הניווט הימני. אם מופיעה הבקשה 'בחירת הגדרות שיתוף נתונים', אפשר להתעלם מהאפשרות הזו בלחיצה על עשה זאת מאוחר יותר.
בכרטיסייה מרכז שליטה, אמורה להופיע רשומה של 'מילוי הזמנה' באמצעות כתובת URL שמופיעה בקטע Trigger שמירת כתובת ה-URL הזו. צריך להעתיק אותה ל-Dialogflow בקטע הבא.

הגדרת webhook URL ב-Dialogflow

עכשיו צריך לעדכן את הנציג ב-Dialogflow כדי להשתמש ב-webhook שלך למילוי הזמנות. לשם כך, בצע את הצעדים הבאים:

פותחים את מסוף Dialogflow (אם רוצים, אפשר לסגור את מסוף Firebase).
בתפריט הניווט הימני לוחצים על מילוי.
מפעילים את ה-webhook.
מדביקים את כתובת ה-URL שהעתקתם ממרכז הבקרה של Firebase, אם היא לא מופיעה עדיין.
לוחצים על שמירה.

מוודאים שהפרויקט מוגדר בצורה נכונה

למשתמשים צריכה להיות אפשרות להפעיל את הפעולה כדי לקבל מידע על 'מכון כושר לפעולה', כולל תשובה בהודעת טקסט בתוך הקוד עם שעות הפעילות ותשובה בטקסט עם לוח הזמנים של השיעור בכל יום בשבוע.

כדי לבדוק את הפעולה בסימולטור הפעולות:

בתפריט הניווט השמאלי במסוף Dialogflow, לוחצים על Integrations (שילובים) > Google Assistant
מוודאים שהאפשרות תצוגה מקדימה אוטומטית של שינויים מופעלת ולוחצים על בדיקה כדי לעדכן את פרויקט הפעולות.
סימולטור הפעולות טוען את פרויקט הפעולות. כדי לבדוק את הפעולה, מקלידים Talk to my test app בשדה קלט ומקישים על Enter.
אמורה להופיע תשובה ברכה ל-Action Gym. נסו לפעול לפי ההנחיות כדי להמשיך את השיחה ולוודא שלמילוי יש תשובה לכל קלט.

3. הוספת מינויים לעדכונים יומיים

אחת הדרכים הנפוצות לעורר עניין בקרב המשתמשים היא להציע להם מידע, כשהמידע יהיה המועיל ביותר. לשם כך, אתם יכולים להציע למשתמשים אפשרות להירשם לעדכונים יומיים מתוך כוונה, ואז הם יקבלו התראה מ-Assistant שמקשרת ישירות למימוש של הכוונה הזו.

בשלב הזה תלמדו על מינויים לעדכונים יומיים ותוסיפו אותם ל-Intent של רשימת הכיתה של הפעולה שלכם. לאחר ביצוע ההוראות האלה, השיחה של הפעולה תיראה כמו התרשים הבא:

איך זה ישפיע על המשתמשים?

משתמשי סמארטפון ככל הנראה מכירים את ההתראות, שמספקות מידע ועדכונים ספציפיים לאפליקציה. מינויים לעדכונים יומיים מאפשרים לגשת בקלות למשתמשים בניידים מחוץ ל-Assistant, בתנאי שהכוונה שאתם שולחים להם עדכונים תמשיך לספק ערך למשתמש על בסיס יומיומי.

עדכונים יומיים יכולים להיות כלי שימושי למעורבות, אבל לא בהכרח כדאי לשלב אותם בכל פעולה. כדאי לשקול את הטיפים הבאים כשמחליטים אם להוסיף לפעולה מינויים לעדכונים יומיים:

חשוב לוודא שהעדכונים היומיים יגרמו למשתמשים לראות מידע שימושי שונה מדי יום. אם הקשה על עדכון יומי מובילה לאותה הנחיה בכל פעם, המשתמש כנראה יבטל את ההרשמה אחרי כמה ימים.
אם המשתמשים ידלגו ישירות לכוונה של העדכון היומי, כדאי לוודא שתיבת הדו-שיח שלהם מובנת. המשתמש לא יתחיל בהכרח בתחילת השיחה, לכן לא אמור להיות לו הקשר רב.
כדאי להראות למשתמשים את היתרונות של הפעולה לפני שמבקשים מהם להירשם לקבלת עדכונים יומיים. המשתמש שלך צריך לחשוב "אני רוצה את התוכן הזה כל יום" כשניתנת להם האפשרות להירשם למינוי.
אל תציפו את המשתמש בהצעות חוזרות להירשם למינוי. הציעו מינוי לעדכון יומי מיד אחרי שתראו למשתמשים לאיזה מינוי הם נרשמו, והימנעו מלהציק להם בנושא הזה במקומות אחרים.
חשוב שהשיחה תהיה קצרה אחרי שמפעילים את כוונת העדכון. רוב העדכונים היומיים צריכים לכלול רק תגובה אחת, ולאחר מכן להיסגר ללא צורך בקלט של המשתמשים.

הפעלת עדכונים יומיים

ניתן להוסיף מינויים לעדכונים יומיים לכוונת ההצטרפות הראשונית של המשתמש, שבה המשתמש נמצא בתחילת השיחה, או לכוונת רכישה ספציפית יותר כדי לבצע קישור עומק למקום כלשהו בשיחה. ב-Codelab הזה, הכוונה היא בתור רשימת כיתה הכי הגיונית, כי הדו-שיח משתנה מדי יום, ויכול להיות שלמשתמשים כדאי להזכיר להם אילו כיתות זמינות.

כדי להפעיל עדכונים יומיים ל-Intent של רשימת הכיתה:

במסוף הפעולות, לוחצים על הכרטיסייה פיתוח ובוחרים באפשרות פעולות בסרגל הניווט הימני.
לוחצים על רשימת הכיתה ברשימה פעולות.
בקטע התעניינות המשתמשים, מחליפים את המצב של האפשרות רוצה להציע עדכונים יומיים למשתמשים.
מגדירים שם תוכן תיאורי שמתאר את העדכון היומי. ההקשר יהיה: 'באיזו שעה היית רוצה שאשלח את <שם התוכן> היומי שלך?', לכן חשוב לוודא שהכותרת היא גם תיאורית וגם שנשמעת נכון כשהיא נאמרת בקול רם. בדוגמה הזו, מגדירים את שם התוכן לערך list of upcoming Action Gym classes.
לוחצים על שמירה בחלק העליון של הדף.

הגדרת Dialogflow

כדי ליצור כוונות (Intent) לתהליך המינוי לעדכון היומי, פועלים לפי השלבים הבאים במסוף Dialogflow:

מגדירים כוונה חדשה לטיפול במשתמש שמבקש להירשם לקבלת עדכונים יומיים. במסוף Dialogflow, לוחצים על הלחצן + לצד Intents בתפריט הניווט הימני כדי ליצור Intent חדש.
צריך לתת ל-Intent החדש את השם Setup Updates.
בקטע ביטויים לאימון, מוסיפים את ביטויי המשתמשים הבאים:

Send daily reminders
Reminder
Remind me
Updates
Upcoming classes

בקטע מילוי, מפעילים את האפשרות הפעלת קריאה לפעולה מאתר אחר (webhook) עבור Intent זה.
לוחצים על שמירה בחלק העליון של הדף.

טיפול בהחלטה של המשתמש

צריך להגדיר Intent חדש כדי לטפל בתגובת המשתמש לבקשה לעדכונים היומיים. לוחצים על הלחצן + לצד אובייקטים מסוג Intent בתפריט הניווט הימני כדי ליצור Intent חדש.
צריך לתת ל-Intent החדש את השם Confirm Updates.
בקטע אירועים, מוסיפים actions_intent_REGISTER_UPDATE. האירוע הזה ב-Dialogflow יופעל על ידי המשתמש שיסיים את תהליך המינוי לעדכון היומי, גם אם בסופו של דבר הוא נרשם וגם אם לא.
בקטע מילוי, מפעילים את האפשרות הפעלת קריאה לפעולה מאתר אחר (webhook) עבור Intent זה.
לוחצים על שמירה בחלק העליון של הדף.

הטמעת מילוי ההזמנות

כך מטמיעים את מילוי ההזמנות ב-webhook:

טעינת יחסי תלות

בקובץ index.js, מעדכנים את הפונקציה require() כדי להוסיף את החבילה RegisterUpdate מחבילת actions-on-google, כך שפעולות הייבוא ייראה כך:

index.js

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

עדכון הצ'יפים של ההצעות

בקובץ index.js, צריך להוסיף רשומת DAILY לרשימת הכותרות של הצ'יפים של ההצעות, כדי שההגדרה של Suggestion תיראה כך:

index.js

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

הוספת מילוי הזמנות ל-Intents חדשים

כשהמשתמש אומר שהוא רוצה להירשם, מתחילים את תהליך קבלת העדכונים היומי על ידי קריאה לעוזר הדיגיטלי של RegisterUpdate עם כוונת היעד של העדכון (רשימת כיתה) ומקלידים (DAILY). בסיום תהליך המינוי, Assistant תפעיל את האירוע actions_intent_REGISTER_UPDATE עם ארגומנט status שמתאר אם המינוי הצליח או לא. להציע למשתמש הודעות המשך, בהתאם לסטטוס המינוי.

בקובץ index.js, מוסיפים את הקוד הבא:

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

הצעת הנחיות חלופיות למשתמש

בסיום התשובות שלכם מרשימת הכיתות תוכלו לראות את המינוי לעדכון יומי, אבל זו בעיה. מכיוון שאותה תשובה תופעל כשהמשתמש יקיש על התראת העדכון היומית, עדיין תתבקשו להירשם לקבלת עדכונים יומיים למרות קבלת ההודעה שהתקבלה לאחרונה. איך מונעים מהמשתמש לחשוב שהוא צריך להירשם מחדש?

למרבה המזל, הארגומנטים של האובייקט conv כוללים מידע על המקום שבו המשתמש התחיל את השיחה. אפשר לבדוק את הארגומנטים מסוג conv כדי לראות אם הם מכילים קטע בשם UPDATES שמציין את המשתמש שהתחיל את השיחה מהתראה על עדכון יומי, ולשנות את התשובה בהתאם. אפשר גם להשתמש בהסתעפות השיחה הזו כדי לסגור את תיבת הדו-שיח מיד אחרי שמספקים את רשימת הכיתות, בהתאם לשיטות המומלצות שלנו לשמור על עדכון יומי קצר.

בקובץ index.js, מחליפים את הקוד הבא:

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

עם זה:

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

בדיקת העדכונים היומיים

בטרמינל, מריצים את הפקודה הבאה כדי לפרוס את קוד ה-webhook המעודכן ב-Firebase:

firebase deploy

כדי לבדוק את הבקשה בהתאמה אישית בסימולטור הפעולות, מבצעים את השלבים הבאים:

במסוף Actions, עוברים אל Test.
מקלידים Talk to my test app בשדה קלט ומקישים על Enter.
מקלידים Learn about classes ומקישים על Enter. מעכשיו, התשובה של הפעולה אמורה להציע לשלוח תזכורות יומיות.
מקלידים Send daily reminders ומקישים על Enter.
מקלידים את הזמן שרוצים לראות את העדכון ומקישים על Enter. למטרות בדיקה, יש לנסות להשיב 3-5 דקות מאוחר יותר מהזמן הנוכחי.

בנייד, אתם אמורים לקבל התראה מ-Assistant בסביבות השעה שבה ציינתם עדכונים. לתשומת ליבכם: יכול להיות שיחלפו כמה דקות עד שההודעה תופיע. מקישים על ההתראה והיא אמורה לקשר ישירות ל-Intent של רשימת הכיתה ב-Assistant. כך תופיע רשימה של הכיתות הקרובות:

4. הוספת התראות

עוד אפשרות לעורר עניין בקרב משתמשים שלא במסגרת הפעולה, אפשר להפעיל את Actions API כדי לשלוח התראות למשתמשים. בניגוד לעדכונים יומיים, ההתראות האלה לא מתוזמנות באופן אוטומטי על ידי Assistant, כך שאפשר לשלוח אותן לפי הצורך.

בשלב הזה מוסבר איך להטמיע התראות בפעולה: להוסיף כוונה חדשה מסוג הכיתה בוטלה ולשלוח התראות למשתמשים שמיידעות אותם על ביטול כיתה. בנוסף, תגדירו את שלושת הרכיבים הבאים שנדרשים כדי לשלוח התראות:

חשבון Actions API – שולחים התראות למשתמש על ידי שליחת בקשת POST ל-API, לכן צריך להגדיר חשבון שירות ופרטי כניסה כדי להתממשק עם ה-API הזה.
עוזר הרשאות - נדרשת הרשאה של המשתמש כדי לגשת למזהה המשתמש שנדרש כדי לשלוח לו התראות. בדוגמה הזו משתמשים בפונקציה של ספריית לקוח כדי להפעיל את כלי ההרשאות ולבקש את המזהה הזה.

אחסון – כדי לשלוח התראות למשתמש מחוץ לשיחה, עליכם לאחסן את מזהי המשתמשים במקום שבו ניתן לשחזר אותם כשהם רוצים. בדוגמה הזו תגדירו מסד נתונים של Firestore כדי לאחסן מידע עבור כל משתמש.

לאחר ביצוע ההוראות, תוסיפו את תיבת הדו-שיח הבאה לשיחה של הפעולה:

איך זה ישפיע על המשתמשים?

משתמשי סמארטפון ככל הנראה מכירים את ההתראות, שמספקות מידע ועדכונים ספציפיים לאפליקציה. התראות הן דרך גמישה לגשת למשתמשים בניידים מחוץ ל-Assistant, כל עוד יש למשתמשים סיבה טובה להפעיל אותן. בעדכונים היומיים, המשתמשים כבר מודעים לכך שהם יקבלו התראות מדי יום. עם זאת, כשמדובר בהתראות, המשתמשים לא יכולים לדעת אם הם מביעים הסכמה לקבלת התראות בתדירות נמוכה, או אם הם מקבלים התראות מרובות ביום.

התראות יכולות להיות כלי שימושי למעורבות, אבל אין לשלב אותן בכל פעולה. כדאי לשקול את הטיפים הבאים כשמחליטים אם להוסיף התראות לפעולה:

כדאי לתכנן כמה לוחות זמנים לדוגמה של התראות. אם אתם מתכננים לשלוח רק התראה אחת בכל יום, כדאי להשתמש בעדכונים יומיים במקום זאת.
חשוב לוודא שההתראות מספקות מידע שימושי בכל פעם שהן מתקבלות. ההתראות יכולות גם ליצור קישור עומק לאחת מהמטרות של הפעולה, לכן חשוב לוודא שהכוונה היא מועילה ורלוונטית.
חשוב להתנסח בצורה מפורשת כשמבקשים ממשתמש להירשם לקבלת התראות. המשתמשים צריכים להבין למה לצפות עם כל התראה, והם צריכים לדעת באיזו תדירות ההתראות נשלחות.

הפעלת Actions API

פותחים את מסוף Google Cloud ובוחרים את השם של פרויקט הפעולות שלכם בתפריט הנפתח.

בתפריט הניווט (☰), עוברים אל APIs שירותים > ספרייה.
מחפשים את Actions API ולוחצים על Enable.

יצירה של חשבון שירות

נדרש אימות ב-Actions API, לכן צריך ליצור חשבון שירות לשליחת בקשות. כדי ליצור ולהתקין מפתח לחשבון שירות ל-Actions API יש לפעול לפי השלבים הבאים:

בתפריט הניווט של מסוף Google Cloud (☰), עוברים אל APIs & שירותים > פרטי כניסה.
לוחצים על Create credentials > מפתח לחשבון השירות.
בתפריט הנפתח Service account, בוחרים באפשרות New Service Account.
ממלאים את הפרטים הבאים:

שם חשבון השירות: service-account
תפקיד: פרויקט > בעלת האתר
מספר חשבון השירות: service-account (תמיד ואחריו @<project_id>.iam.gserviceaccount.com)
סוג מפתח: JSON

לוחצים על יצירה.
מעבירים את קובץ ה-JSON שהורדתם לספרייה /user-engagement-codelab/start/functions/ בפרויקט.
משנים את השם של קובץ ה-JSON לשם service-account.json.

הפעלת Firestore

כדי לשלוח התראות מחוץ לשיחה, צריכה להיות לכם דרך לאחסן מזהי משתמשים שאפשר להפנות אליהם מקוד ההתראות. בדוגמה הזו אנחנו משתמשים במסד נתונים של Firestore כדי לאחסן את מזהי המשתמשים של המשתמשים הרשומים.

כדי ליצור מסד נתונים ב-Firestore לפעולה שלכם, יש לבצע את השלבים הבאים:

במסוף Firebase, בוחרים את השם של פרויקט הפעולות.
בתפריט הניווט הימני, עוברים אל פיתוח > מסד נתונים ולוחצים על יצירת מסד נתונים.
בוחרים באפשרות הפעלה במצב בדיקה.
לוחצים על Enable.

הגדרת Dialogflow

כדי ליצור את תהליך ההצטרפות לקבלת התראות, פועלים לפי השלבים הבאים במסוף Dialogflow:

שליחת בקשה למשתמש להירשם

צריך להגדיר Intent חדש, שיטפל באם המשתמש מבקש להירשם לקבלת התראות על כיתות שבוטלו. במסוף Dialogflow, לוחצים על הלחצן + לצד Intents בתפריט הניווט הימני כדי ליצור Intent חדש.
צריך לתת את השם של ה-Intent החדש הזה Setup Push Notifications.
בקטע ביטויים לאימון, מוסיפים את ביטויי המשתמשים הבאים:

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

בקטע מילוי, מפעילים את האפשרות הפעלת קריאה לפעולה מאתר אחר (webhook) עבור Intent זה.
לוחצים על שמירה בחלק העליון של הדף.

טיפול בהחלטה של המשתמש

צריך להגדיר Intent חדש כדי לטפל בתשובה של המשתמש לבקשת ההרשמה להתראות. לוחצים על הלחצן + לצד אובייקטים מסוג Intent בתפריט הניווט הימני כדי ליצור Intent חדש.
צריך לתת ל-Intent החדש את השם Confirm Push Notifications.
בקטע אירועים, מוסיפים actions_intent_PERMISSION. האירוע הזה ב-Dialogflow יופעל על ידי המשתמש שיסיים את תהליך המינוי להתראות, גם אם בסופו של דבר הוא נרשם וגם אם לא.
בקטע מילוי, מפעילים את האפשרות הפעלת קריאה לפעולה מאתר אחר (webhook) עבור Intent זה.
לוחצים על שמירה בחלק העליון של הדף.

טיפול בהתראה

אפשר לקשר את ההתראות לכוונה ספציפית, כך שמשתמשים שמקישים על ההתראה יקושרו ישירות לכוונה הזו בפעולה. בדוגמה הזו, מוסיפים כוונה חדשה לקבלת התראות עם פרטים על כיתות שבוטלו.

כדי להוסיף כוונה שיופעלו על ידי המשתמש שמקישים על התראה, פועלים לפי השלבים הבאים:

במסוף Dialogflow, לוחצים על הלחצן + לצד Intents בתפריט הניווט הימני כדי ליצור Intent חדש.
צריך לתת את השם של ה-Intent החדש הזה Class Canceled.
בקטע ביטויים לאימון, מוסיפים את Cancelations כביטוי משתמש.
בקטע מילוי, מפעילים את האפשרות הפעלת קריאה לפעולה מאתר אחר (webhook) עבור Intent זה.
לוחצים על שמירה בחלק העליון של הדף.

שליחת התראות לבדיקה באמצע השיחה

בסביבת הייצור, אמור להיות לכם סקריפט ששולח התראות, בנפרד מקוד מילוי ההזמנות של הפעולה. בדוגמה הזו, אפשר ליצור Intent שאפשר להפעיל כדי לשלוח התראה בזמן שמדברים אל הפעולה. הכוונה הזו היא למטרות ניפוי באגים בלבד. בפועל, אין לטפל בהתראות שההזמנה ממלאת או להפעיל אותן בדרך אחרת כחלק מהשיחה של הפעולה.

כדי ליצור כוונה לבדיקת התראות, פועלים לפי השלבים הבאים:

למטרות בדיקה וניפוי באגים, צריך להגדיר Intent חדש שיאפשר לכם לשלוח התראות למשתמשים רשומים. במסוף Dialogflow, לוחצים על הלחצן + לצד Intents בתפריט הניווט הימני כדי ליצור Intent חדש.
צריך לתת ל-Intent החדש את השם Test Notification.
בקטע ביטויים לאימון, מוסיפים את Test notification כביטוי משתמש.
בקטע מילוי, מפעילים את האפשרות הפעלת קריאה לפעולה מאתר אחר (webhook) עבור Intent זה.
לוחצים על שמירה בחלק העליון של הדף.

הפעלת התראות

כדי להפעיל התראות לגבי Intent שהכיתה בוטלה, פועלים לפי השלבים הבאים:

במסוף Dialogflow, עוברים אל Integrations (שילובים) בסרגל הניווט.
בכרטיס Google Assistant, לוחצים על Integration Settings (הגדרות שילוב).
מוסיפים את הכיתה בוטלה כ-Intent מסוג הפעלה משתמעת. השלב הזה נדרש כדי שמערכת Dialogflow תזהה שהמשתמשים יכולים להתחיל את השיחה עם הכוונה שלה להכיתה בוטלה (על ידי הקשה על התראה).
לוחצים על סגירה.

במסוף הפעולות, לוחצים על הכרטיסייה פיתוח ובוחרים באפשרות פעולות בסרגל הניווט הימני.
לוחצים על הכיתה בוטלה ברשימה פעולות.
בקטע התעניינות המשתמשים, מחליפים את המצב של האפשרות רוצה לשלוח התראות?.
מגדירים שם תוכן תיאורי שמתאר את ההתראה. ההקשר יהיה 'האם זה בסדר לשלוח התראות על <שם התוכן>?', לכן חשוב לוודא ששם הפריט גם תיאורי וגם נשמע נכון כשהוא נאמר בקול. בדוגמה הזו, מגדירים את שם התוכן לערך class cancelations.
לוחצים על שמירה בחלק העליון של הדף.

הטמעת מילוי ההזמנות

כך מטמיעים את מילוי ההזמנות ב-webhook:

טעינת יחסי תלות

בקובץ index.js, מעדכנים את הפונקציה require() כדי להוסיף את החבילה UpdatePermission מחבילת actions-on-google, כך שפעולות הייבוא ייראה כך:

index.js

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

עדכון הצ'יפים של ההצעות

בקובץ index.js, צריך להוסיף רשומת NOTIFICATIONS לרשימת הכותרות של הצ'יפים של ההצעות, כדי שההגדרה של Suggestion תיראה כך:

index.js

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

הגדרת ייבוא חדש

כדי להתחבר למסד הנתונים של Firestore, צריך להוסיף את החבילה firebase-admin ולהוסיף קבועים לשדות שמאוחסנים במסד הנתונים. בנוסף, צריך לייבא את החבילות google-auth-library ו-request כדי לטפל באימות ובבקשות ל-Actions API.

בקובץ index.js, צריך להוסיף את הקוד הבא לייבוא:

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

הצעה להגדיר התראות על ביטולי כיתה

בקובץ index.js, מחליפים את הקוד הבא:

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

עם זה:

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

הוספת מילוי הזמנות ל-Intents חדשים

כשמשתמש אומר שהוא רוצה להירשם לקבלת התראות, צריך להתקשר לעוזר הדיגיטלי של UpdatePermission כדי לבקש הרשאה מהמשתמש. אם הפעולה בוצעה ללא שגיאות, הארגומנט PERMISSION יתווסף לארגומנטים של האובייקט conv. אפשר לבדוק זאת כדי לשנות את השיחה.

אחרי שמקבלים הרשאה מהמשתמש, לוקחים את מזהה המשתמש מהארגומנטים של האובייקט conv ושומרים אותו במסד הנתונים. בהמשך שולחים את מזהה המשתמש הזה ל-Actions API. כך Assistant קובעת מי יקבל את ההתראה.

לסיום, מוסיפים מילוי בקשה ל-Intent מסוג Class Canceled שמופעל על ידי הקשה על ההתראה. בדוגמה הזו, התשובה שלך היא מחרוזת placeholder, אבל בגרסה המוכנות לייצור של הפעולה הזו, סקריפט ההתראה יספק מידע דינמי יותר לגבי המחלקה שבוטלו.

בקובץ index.js, מוסיפים את הקוד הבא:

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

הוספת התראות לבדיקה

כדי לשלוח התראה למשתמש, צריך לשלוח בקשת POST ל-Actions API עם מזהה המשתמש, כותרת ההתראה וכוונת היעד. בדוגמה הזו, הפעלת 'Intent של התראת בדיקה' תעבור איטרציה במסד הנתונים של Firestore ותשלח התראות לכל משתמש שנרשם לקבלת התראות.

חשוב לזכור: בדוגמה הזו, הטמעת את הקוד ששולח את ההתראה בתגובה לפעולה מאתר אחר (webhook) ומפעיל את הקוד הזה באמצעות הפעלת Intent לניסיון בשיחה. בפעולות שאתם מתכוונים לפרסם, קוד ההתראה צריך להופיע בסקריפט נפרד ממילוי ההזמנות.

בקובץ index.js, מוסיפים את הקוד הבא:

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

בדיקת ההתראות

בטרמינל, מריצים את הפקודה הבאה כדי לפרוס את קוד ה-webhook המעודכן ב-Firebase:

firebase deploy

כדי לבדוק התראות בסימולטור הפעולות:

במסוף Actions, עוברים לכרטיסייה Test.
מקלידים Talk to my test app בשדה קלט ומקישים על Enter.
מקלידים Learn about classes ומקישים על Enter.
מקלידים Get notifications ומקישים על Enter.
אם עדיין לא הענקתם לפעולה הרשאה לשלוח התראות, מקלידים yes ומקישים על Enter.
מקלידים yes ומקישים על Enter. חשבון Google שלך אמור להיות רשום לקבלת התראות על הפעולה הזו.

כדי לצאת, מקלידים no ומקישים על Enter.
כדי להתחיל שיחה חדשה, אפשר להקליד Talk to my test app ולהקיש על Enter.
מקלידים Test notification ומקישים על Enter.

תוך כמה דקות אמורה להגיע אליך "הודעת בדיקה מ-Action Gym" התראה מ-Assistant בנייד. הקשה על ההתראה הזו תקשר אתכם ל-Intent של הפעולה בסטטוס הפעולה בוטלה.

5. יצירת קישור ל-Assistant

עד עכשיו דיברנו על תכונות של מעורבות שאפשר להטמיע כדי לגרום למשתמשים לחזור לפעולה שלכם, אבל הן מבוססות על כך שמשתמשים יגלו את הפעולה שלכם ותשתמשו בה.

אפשר ליצור קישור ל-Assistant שיקשר משתמשים במכשירים ניידים ישירות לפעולה ב-Assistant. קישור ל-Assistant הוא היפר-קישור רגיל, ולכן אפשר להוסיף אותו לאתר או לכל חומר שיווקי באינטרנט, כמו בלוג או פוסט ברשתות החברתיות.

בשלב הזה נסביר מהו קישור ל-Assistant, איך ליצור קישור לכוונת הרכישה של הפעולה ואיך להוסיף אותו לאתר פשוט לצורך בדיקה.

איך זה ישפיע על המשתמשים?

קשה מאוד למשוך משתמשים לפעולה בפעם הראשונה, במיוחד כשהם צריכים להפעיל את הפעולה באופן מפורש ב-Assistant. קישור ל-Assistant מבטל את הקושי הזה ומאפשר למשתמשים קישור ישיר לפעולה. כשמשתמש עוקב אחר הקישור ל-Assistant במכשיר עם Assistant מובנית, הוא מועבר ישירות לפעולה. כשמשתמש יפתח את הקישור במכשיר שהוא לא נייד או בכל מכשיר אחר שלא תומך ב-Assistant, הוא עדיין יועבר לדף האפליקציה במאגר הפעולות (אם הוא פורסם), כך שהקישור עדיין יוכל לשווק את הפעולה למשתמשים האלה.

קישורים ל-Assistant יכולים להיות כלי שימושי ליצירת מעורבות, ולכן כדאי ליצור כלי כזה אם אתם מתכננים לפרסם את הפעולה באתר או ברשתות החברתיות. לפני שיוצרים ומפיצים קישור ל-Assistant, חשוב לשים לב לטיפים הבאים:

קישורים ל-Assistant פועלים רק אחרי שהפעולה מתפרסמת. כשהפרויקט במצב טיוטה, הקישור יפעל רק במכשירים שלכם. כל משתמש אחר יופנה לדף 404 בספרייה 'פעולות'.
כדי לאפשר למשתמשים לבדוק קישור ל-Assistant לפני הפרסום, אפשר לפרסם את הפעולה בסביבת אלפא או בטא. חשוב לדעת שרק משתמשים שמשתתפים בגרסת האלפא או הבטא שלך יוכלו לבדוק את הקישור ל-Assistant.
חשוב לוודא שכוונת היעד של הקישור ל-Assistant יוצרת רושם ראשוני טוב בקרב משתמשים חדשים. כוונת הרכישה שלך היא יעד ברירת המחדל לקישור ל-Assistant, כי הוא כבר אמור לעשות עבודה טובה בהצגת הפעולה

הפעלת קישורים ל-Assistant

כדי ליצור קישור ל-Assistant עבור כוונת ההצטרפות, צריך לפעול לפי השלבים הבאים:

במסוף הפעולות, לוחצים על הכרטיסייה פיתוח ובוחרים באפשרות פעולות בסרגל הניווט הימני.
לוחצים על actions.intent.MAIN ברשימה פעולות.
בקטע קישורים, מחליפים את המצב של האפשרות רוצה להפעיל כתובת URL לפעולה הזו?
מגדירים כותרת קישור תיאורית שמתארת את הפעולה. השם יכול להיות צמד פשוט של פועל-שם, שמתאר מה המשתמש יכול לבצע באמצעות הפעולה. לצורך הדוגמה הזו, מגדירים את שם הקישור כ-learn about Action Gym.
מעתיקים את קטע קוד ה-HTML מהחלק התחתון של הדף ושומרים אותו לשימוש במועד מאוחר יותר.
לוחצים על שמירה בחלק העליון של הדף.

פריסה של אתר לבדיקה

כדי לבדוק את הקישור ל-Assistant, אפשר להשתמש בכלים של Firebase כדי לפרוס אתר לבדיקה לצד מילוי ההזמנות. כבר יצרנו אתר בדיקה פשוט בשביל הדוגמה הזו, צריך רק להוסיף את הקישור ל-Assistant.

נכנסים לספרייה /user-engagement-codelab-nodejs/start/public/ של מילוי ההזמנות ופותחים את הקובץ index.html בכלי לעריכת טקסט.

בקובץ index.html, מדביקים את קטע קוד ה-HTML של הקישור ל-Assistant ברכיב body. הקובץ אמור להיראות כמו קטע הקוד הבא:

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>

בדיקת הקישור ל-Assistant

בטרמינל, מריצים את הפקודה הבאה כדי לפרוס את האתר לבדיקה ב-Firebase:

firebase deploy

כשהרצת פקודת הפריסה תסתיים, שימו לב לכתובת ה-URL לאירוח בפלט.

צריך לעבור לכתובת ה-URL הזו בדפדפן האינטרנט בנייד. הקישור ל-Assistant אמור להופיע באתר הבדיקה. לחיצה על הקישור הזה בנייד אמורה להעביר אותך לכוונת הפתיחה של הפעולה ב-Assistant.

אפשר גם לנסות לעבור אל כתובת ה-URL לאירוח בדפדפן במחשב. הפעולה אמורה להוביל לדף 404 בספרייה של Assistant, כי הפעולה לא מתפרסמת.

6. השלבים הבאים

מזל טוב!

למדתם עכשיו על החשיבות של התעניינות המשתמשים בזמן פיתוח הפעולה, אילו תכונות של התעניינות המשתמשים זמינות בפלטפורמה ואיך להוסיף כל תכונה לפעולה.

מקורות מידע נוספים ללמידה

כדי לקבל מידע נוסף על התעניינות המשתמשים בפעולה שלכם, כדאי לעיין במקורות המידע הבאים:

התעניינות המשתמשים & קישורים למסמכים ב-Assistant: מסמכי התיעוד הרשמיים של Actions on Google בנוגע לתכונות המתוארות ב-Codelab הזה ומעורבות המשתמשים באופן כללי.
ניתוח נתונים של שימור משתמשים: תיעוד של תכונת ניתוח הנתונים במסוף הפעולות, שבה מוצג שימור המשתמשים לגבי הפעולה שפרסמתם.
הנחיות לעיצוב שיחה: שיטות מומלצות והנחיות לעיצוב תכונות של מעורבות המשתמשים.
פעולות במאגר GitHub של Google: קוד וספריות לדוגמה.
r/GoogleAssistantDev: הקהילה הרשמית של Reddit למפתחים שעובדים עם Assistant.

אפשר לעקוב אחרינו ב- Twitter @ActionsOnGoogle כדי להתעדכן בהכרזות האחרונות, ולשלוח ציוץ אל #AoGDevs כדי לשתף את מה שיצרתם!

סקר משוב

לפני שנסיים, מלאו את הטופס הזה כדי לספר לנו על הביצועים שלנו.