הנחיות בלוח הציור

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

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

בקטעים הבאים מוסבר איך להחזיר תגובה על קנבס במקרה הזה.

הפעלת לוח שיתופי אינטראקטיבי

צריך להגדיר את הפעולה בדרך ספציפית כדי להשתמש בלוח הציור האינטראקטיבי. כדי ליצור פעולה שמשתמשת בלוח הציור האינטראקטיבי צריך להוסיף בקונסולה ל-Actions (וגם, ב-Actions SDK, שינויים ב- קובץ settings.yaml שלך). כדי לראות את התהליך המלא ליצירה כדי להגדיר פעולה אינטראקטיבית של לוח הציור באמצעות Actions SDK: יוצרים פרויקט.

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

1. אם לא בחרת בכרטיס משחק באיזה סוג של פעולה שרוצים ליצור?, לוחצים על Deploy בתפריט הניווט העליון. בקטע מידע נוסף, בוחרים באפשרות משחקים ו כיפית. לוחצים על Save (שמירה).
2. לוחצים על פיתוח בסרגל הניווט העליון במסוף הפעולות.
3. בתפריט הניווט הימני, לוחצים על לוח שיתופי אינטראקטיבי.
4. בקטע האם ברצונך שהפעולה תשתמש בלוח הציור האינטראקטיבי?, בוחרים באחת מהאפשרויות הבאים:
   • הפעלת לוח הציור האינטראקטיבי עם מילוי ה-webhook של השרת. האפשרות הזו מסתמכת על התגובה לפעולה מאתר אחר (webhook) כדי לגשת לתכונות מסוימות, onUpdate() כדי להעביר נתונים לאפליקציית האינטרנט. כשהאפשרות מופעלת, התאמות Intent הן מטופלות בסצנות, ואפשר לבחור להפעיל את ה-webhook לפני המעבר לסצנה אחרת או לסיום השיחה.
   • הפעלת לוח שיתופי אינטראקטיבי עם מילוי הזמנות של הלקוח. האפשרות הזו מאפשרת להעביר את הלוגיקה של מילוי הזמנות לפעולה מאתר אחר (webhook) לאפליקציית האינטרנט, ולהגביל את האפשרויות האלה התגובה לפעולה מאתר אחר (webhook) מפעילה רק את תכונות השיחה שמחייבות אותה. כמו קישור חשבונות. כשהאפשרות מופעלת, אפשר להשתמש ב-expect() כדי רושמים handlers של Intent בצד הלקוח.
5. אופציונלי: מזינים את כתובת ה-URL של אפליקציית האינטרנט בקטע הגדרת כתובת ה-URL של אפליקציית האינטרנט המשמשת כברירת מחדל השדה הזה. הפעולה הזו מוסיפה תשובת ברירת מחדל Canvas עם שדה כתובת ה-URL כדי בהפעלה הראשית שלכם.
6. לוחצים על שמירה.

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

1. צריך להגדיר את השדה category בקובץ settings.yaml בתור GAMES_AND_TRIVIA כדי לתאר את הפעולה ולעזור למשתמשים לגלות אותה בצורה הטובה ביותר.
2. צריך להגדיר את השדה usesInteractiveCanvas בקובץ settings.yaml בתור true.

בדיקת היכולות של הפלטפורמה

ה-framework של לוח הציור האינטראקטיבי פועל רק במכשירים עם Assistant שמספקים ממשק ויזואלי, לכן הפעולה צריכה לחפש את INTERACTIVE_CANVAS יכולות במכשיר של המשתמש. כשמגדירים הנחיות ב-Actions Builder, אפשר לציין רשימה של יכולות המכשיר בשדה selector של אובייקט candidates. בורר ההנחיות בוחר את ההצעה לפעולה המתאימה ביותר המתאימה ליכולת המכשיר של המשתמש.

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

1. בדיקת המכשיר של המשתמש שיש תמיכה ביכולת של INTERACTIVE_CANVAS. אם המיקום היא תשלח למשתמש תגובת Canvas.
2. אם היכולת של לוח הציור האינטראקטיבי לא זמינה, צריך לבדוק אם המכשיר תומך ביכולת RICH_RESPONSE. אם כן, יש לשלוח למשתמש תגובה עשירה.
3. אם היכולת של תגובה מתקדמת לא זמינה, שולחים למשתמש תגובה פשוטה.

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

candidates:
  - selector:
      surface_capabilities:
        capabilities:
          - INTERACTIVE_CANVAS
    canvas:
      url: 'https://example.web.app'
  - selector:
      surface_capabilities:
        capabilities:
          - RICH_RESPONSE
    content:
      card:
        title: Card title
        text: Card Content
        image:
          url: 'https://example.com/image.png'
          alt: Alt text
        button:
          name: Link name
          open:
            url: 'https://example.com/'
  - first_simple:
      variants:
        - speech: Example simple response.
    

{
  "candidates": [
    {
      "selector": {
        "surface_capabilities": {
          "capabilities": [
            "INTERACTIVE_CANVAS"
          ]
        }
      },
      "canvas": {
        "url": "https://example.web.app"
      }
    },
    {
      "selector": {
        "surface_capabilities": {
          "capabilities": [
            "RICH_RESPONSE"
          ]
        }
      },
      "content": {
        "card": {
          "title": "Card title",
          "text": "Card Content",
          "image": {
            "url": "https://example.com/image.png",
            "alt": "Alt text"
          },
          "button": {
            "name": "Link name",
            "open": {
              "url": "https://example.com/"
            }
          }
        }
      }
    },
    {
      "first_simple": {
        "variants": [
          {
            "speech": "Example simple response."
          }
        ]
      }
    }
  ]
}

    

const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");
if (supportsInteractiveCanvas) {
  // Respond with a Canvas response
  conv.add(new Canvas({
    url: 'https://example.web.app',
  }));
} else if (supportsRichResponse) {
  // Respond with a rich response
  conv.add(new Card({
    title: 'Card title',
    image: new Image({
      url: 'https://example.com/image.png',
      alt: 'Alt text',
    }),
    button: new Link({
      name: 'Link name',
      open: {
        url: 'https://example.com/',
      },
    }),
  }));
} else {
  // Respond with a simple response
  conv.add('Example simple response.');
}
  

עיבוד של אפליקציית האינטרנט

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

התשובה הראשונה של Canvas חייבת להכיל את כתובת ה-URL של אפליקציית האינטרנט. הסוג הזה של התשובה Canvas מנחה את Google Assistant לעבד את אפליקציית האינטרנט בכתובת הזו במכשיר של המשתמש. בדרך כלל, שולחים את התשובה הראשונה (Canvas) מיד לאחר שהמשתמש מפעיל את הפעולה. כשאפליקציית האינטרנט נטענת, ספריית הקנבס האינטראקטיבית נטענת, ואפליקציית האינטרנט רושמת handler של קריאה חוזרת באמצעות Interactive Canvas API.

ניתן לציין את כתובת ה-URL של אפליקציית האינטרנט ב-Actions Builder כפי שמוצג ב- צילום המסך הבא:

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

קטעי הקוד הבאים מראים איך לבנות Canvas תשובות במהירות אפליקציית האינטרנט גם ב-Actions Builder וגם ב-webhook:

candidates:
  - first_simple:
       variants:
         - speech: >-
             Welcome! Do you want me to change color or pause spinning? You can
             also tell me to ask you later.
     canvas:
       url: 'https://your-web-app.com'
    

{
  "candidates": [
    {
      "first_simple": {
        "variants": [
          {
            "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later."
          }
        ]
      },
      "canvas": {
        "url": "https://your-web-app.com"
      }
    }
  ]
}
    

app.handle('welcome', (conv) => {
  conv.add('Welcome! Do you want me to change color or pause spinning? ' +
    'You can also tell me to ask you later.');
  conv.add(new Canvas({
    url: `https://your-web-app.com`,
  }));
});
    

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later.",
      "text": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later."
    },
    "canvas": {
      "data": [],
      "suppressMic": false,
      "url": "https://your-web-app.com"
    }
  }
}
    

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

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

1. כשמתבצעת התאמה בין ה-Intent בסצנה, האירוע מפעיל אירוע והתשובה Canvas שמכיל את השדה data עם מטען ייעודי (payload) של JSON, נשלח בחזרה כתגובה.
2. השדה data מועבר לקריאה חוזרת (callback) של onUpdate ומשמש לעדכון בדפדפן.

3. פעולת השיחה יכולה לשלוח תשובה חדשה של Canvas ולספק מידע השדה data כדי לשלוח עדכונים חדשים או לטעון מצבים חדשים.

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

• באמצעות Actions Builder הכלי ליצירת פעולות מאכלס באופן אוטומטי את השדה data ב- התשובה Canvas עם המטא-נתונים הנדרשים לעדכון אפליקציית האינטרנט.
• באמצעות webhook אם יש לכם תגובה לפעולה מאתר אחר (webhook), אתם יכולים להגדיר נתונים בהתאמה אישית מטען ייעודי (payload) לעדכון אפליקציית האינטרנט בתשובה של Canvas.

בקטעים הבאים מתואר איך להעביר נתונים דרך 'הכלי ליצירת פעולות', webhook.

איך משתמשים ב-Actions Builder כדי להעביר נתונים

בעזרת Actions Builder לא צריך להגדיר webhook כדי לנהל את המטא-נתונים שנשלח לאפליקציית האינטרנט שלך. במקום זאת, כשמגדירים את ה-handler של Intent בממשק המשתמש של Actions Builder, אפשר לכלול את התשובה Canvas. א' השדה data מאוכלס באופן אוטומטי במטא-נתונים הנדרשים לעדכון אפליקציית האינטרנט שלכם, למשל שם ה-Intent, פרמטרים שתועדו מהקלט של המשתמש, לסצנה הנוכחית.

לדוגמה, ה-handler הבא של Intent Guess מציין שאתם רוצים לכלול Canvas. תגובה:

candidates:
  - canvas:
      send_state_data_to_canvas_app: true
    

{
  "candidates": [
    {
      "canvas": {
        "send_state_data_to_canvas_app": true
      }
    }
  ]
}
    

אפשר גם לצרף את קטע הקוד הבא ל-Intent כדי לשלוח הודעת TTS:

...
  - first_simple:
      variants:
        - speech: Optional message.

הכלי Actions Builder מרחיב באופן אוטומטי את התשובה Canvas עם מטא-נתונים ל- מעדכנים את אפליקציית האינטרנט, כמו שמוצג בקטעי הקוד הבאים. במקרה הזה, המשתמש ניחשו את האות "a" במשחק חיזוי מילים:

candidates:
  - canvas:
      data:
        - google:
            intent:
              params:
                letter:
                  resolved: a
                  original: a
              name: guess
            scene: Game
      sendStateDataToCanvasApp: true
    

{
  "candidates": [
    {
      "canvas": {
        "data": [
          {
            "google": {
              "intent": {
                "params": {
                  "letter": {
                    "resolved": "a",
                    "original": "a"
                  }
                },
                "name": "guess"
              },
              "scene": "Game"
            }
          }
        ],
        "sendStateDataToCanvasApp": true
      }
    }
  ]
}
    

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

שימוש ב-webhook כדי להעביר נתונים

אפשר להגדיר באופן ידני את השדה data של Canvas תשובות ב-webhook עם פרטי המצב הנדרשים כדי לעדכן את אפליקציית האינטרנט. בגישה הזאת מומלץ אם צריך לכלול מטען ייעודי (payload) מותאם אישית של data בתשובה של Canvas במקום להעביר רק את המטא-נתונים הטיפוסיים הנדרשים לעדכון אפליקציית האינטרנט.

קטעי הקוד הבאים מראים איך להעביר נתונים בתגובה Canvas תגובה לפעולה מאתר אחר (webhook):

app.handle('start_spin', (conv) => {
  conv.add(`Ok, I'm spinning. What else?`);
  conv.add(new Canvas({
    data: {
      command: 'SPIN',
      spin: true,
    },
  }));
});
    

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Ok, I'm spinning. What else?",
      "text": "Ok, I'm spinning. What else?"
    },
    "canvas": {
      "data": {
        "command": "SPIN",
        "spin": true
      },
      "suppressMic": false,
      "url": ""
    }
  }
}
    

הנחיות והגבלות

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

• כל handler של webhook למילוי הזמנות צריך לכלול Canvas. אם התגובה לפעולה מאתר אחר (webhook) התשובה לא כוללת את Canvas, אפליקציית האינטרנט שלך נסגרת.
• עליך לכלול את כתובת ה-URL של אפליקציית האינטרנט רק בתשובה הראשונה (Canvas) ששולחים למשתמש.
• כתובת ה-URL של התשובה Canvas צריכה להיות חוקית והפרוטוקול שלה חייב להיות HTTPS.
• גודל התשובה Canvas חייב להיות 50KB לכל היותר.