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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

YAML

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.
    

JSON

{
  "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."
          }
        ]
      }
    }
  ]
}

    

Node.js

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 מיד אחרי שהמשתמש מפעיל את הפעולה. כשאפליקציית האינטרנט נטענת, הספרייה האינטראקטיבית של Canvas נטענת ואפליקציית האינטרנט רושמת handler של קריאה חוזרת (callback) באמצעות ה-Interactive Canvas API.

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

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

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

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

YAML

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'
    

JSON

{
  "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"
      }
    }
  ]
}
    

Node.js

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`,
  }));
});
    

JSON

{
  "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 כדי לשלוח עדכונים חדשים או לטעון מצבים חדשים.

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

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

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

בקטעים הבאים מוסבר איך להעביר נתונים דרך Actions Builder ו-webhook.

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

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

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

YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true
    

JSON

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

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

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

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

YAML

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

JSON

{
  "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:

Node.js

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

JSON

{
  "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.