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

עידוד המשתמשים לבצע פעולה באמצעות Google Assistant

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

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

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

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

שיעור הקוד מכסה את התכונות של מעורבות המשתמשים ואת השיטות המומלצות ל-Action 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. הגדרת הפרויקט

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

הבנת הדוגמה

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

התרשים הבא מציג את זרימת השיחות של 'חדר הכושר התעשייתי':

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

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

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

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

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

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

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

פריסת מילוי הזמנות

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

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

firebase use <PROJECT_ID>

npm install

firebase deploy

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

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

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

פותחים את מסוף Firebase.
בוחרים את פרויקט ה-Action מתוך רשימת האפשרויות.
עוברים אל פיתוח &gt פונקציות בסרגל הניווט הימני. אם &&39;תבקשו "בחרו בהגדרות שיתוף הנתונים&quot, תוכלו להתעלם האפשרות הזו על ידי לחיצה על עשה זאת מאוחר יותר.
בכרטיסייה מרכז הבקרה, אמורה להופיע רשומה עבור "מילוי" עם כתובת URL בקטע טריגר. שומרים את כתובת ה-URL הזו. צריך להעתיק אותה ל-Dialogflow בקטע הבא.

הגדרת ה-webhook URL ב-Dialogflow

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

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

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

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

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

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

3. הוספת מינויים יומיים

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

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

מה תהיה מידת המעורבות של המשתמשים?

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

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

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

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

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

כך מפעילים עדכונים יומיים לגבי כוונת הרשימת כיתות:

במסוף הפעולות, לוחצים על הכרטיסייה פיתוח ובוחרים באפשרות פעולות בסרגל הניווט הימני.
לוחצים על רשימת כיתות ברשימה פעולות.
בקטע התעניינות המשתמשים, משנים את האפשרות רוצה להציע עדכונים יומיים למשתמשים.
מגדירים כותרת תוכן תיאורית שמתארת את העדכון היומי. ההקשר יהיה " ובאיזו שעה היית רוצה לשלוח את &ציטוט היומי שלך; לכן עליך לוודא שהכותרת שלך גם תיאורית וגם נשמעת נכונה כאשר היא מוקראת בקול. בדוגמה הזו, מגדירים את שם התוכן ל-list of upcoming Action Gym classes.
בראש הדף לוחצים על שמירה.

הגדרת Dialogflow

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

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

Send daily reminders
Reminder
Remind me
Updates
Upcoming classes

בקטע מימוש, מחליפים את האפשרות הפעלת webhook לביצוע 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',
};

הוספת מילוי הזמנות עבור כוונות חדשות

כשהמשתמש אומר שהוא רוצה להירשם, צריך להתחיל את תהליך המינוי היומי של העדכונים על ידי קריאה לעוזר הדיגיטלי של 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

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

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

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

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

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

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

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

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

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

מה תהיה מידת המעורבות של המשתמשים?

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

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

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

הפעלת ה-API של הפעולות

פותחים את Google Cloud Console ובוחרים את השם של פרויקט הפעולות בתפריט הנפתח.

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

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

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

בתפריט הניווט של Google Cloud Console (☰), עוברים אל APIs & Services > Credentials [שירותי &פרטי כניסה].
לוחצים על יצירת פרטי כניסה > מפתח חשבון שירות.
בתפריט הנפתח חשבון שירות, בוחרים באפשרות חשבון שירות חדש.
ממלאים את הפרטים הבאים:

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

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

הפעלת Firestore

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

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

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

הגדרת Dialogflow

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

שליחת בקשה למשתמשים להירשם כמנויים

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

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

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

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

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

שימוש בהתראות

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

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

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

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

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

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

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

הפעלת הודעות בדחיפה

כך מפעילים התראות בכוונת רכישה עבור סיווג מבוטל:

במסוף Dialogflow, עוברים לשילובים בסרגל הניווט.
בכרטיס Google Assistant, לוחצים על הגדרות שילוב.
הוספה של סיווג מבוטל ככוונת הפעלה מרומזת. חייבים לבצע את השלב הזה כדי ש-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 כדי לטפל באימות ובבקשות ל-Action 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]));
    };
  };
});

הוספת מילוי הזמנות עבור כוונות חדשות

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

אחרי שתקבלו את הרשאת המשתמש, תוכלו להשתמש ב-User-ID מהארגומנטים של האובייקט #conv ולשמור אותם במסד הנתונים. מאוחר יותר שולחים את מזהה המשתמש הזה ל-Action API, כדי לקבוע מי יקבל את ההתראה.

לסיום, מוסיפים מילוי הזמנות לכוונה 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 ל-Action API באמצעות מזהה המשתמש, כותרת ההתראה ומטרת היעד. בדוגמה הזו, הפעלת Intent התראות הבדיקה תחזור על עצמה דרך מסד הנתונים של Firestore ותשלח התראות לכל משתמש שנרשם לקבלת התראות.

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

בקובץ 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

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

במסוף הפעולות, עוברים לכרטיסייה בדיקה.
מקלידים 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 ההגדרה. הקשה על ההתראה הזו תכלול קישור עמוק אל כוונת הביטול של הכיתה עבור הפעולה שלכם.

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

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

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

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

מה תהיה מידת המעורבות של המשתמשים?

קשה לנסח משתמשים לפעולה בפעם הראשונה, במיוחד כשהם צריכים להפעיל באופן מפורש את הפעולה שלכם ב-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 ברכיב הגוף. הקובץ אמור להיראות כך:

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. לחיצה על הקישור הזה בנייד תעביר אתכם אל כוונות הפתיחה של Action' Assistant.

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

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

מזל טוב!

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

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

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

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

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

סקר משוב

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