कैनवस प्रॉम्प्ट

अपने वेब ऐप्लिकेशन पर जानकारी रिले करने के लिए, आपको बातचीत वाले लॉजिक से Canvas जवाब भेजना होगा. Canvas रिस्पॉन्स में इनमें से कोई एक काम किया जा सकता है:

• उपयोगकर्ता के डिवाइस पर फ़ुल-स्क्रीन वेब ऐप्लिकेशन दिखाना
• वेब ऐप्लिकेशन अपडेट करने के लिए डेटा पास करें

नीचे दिए सेक्शन में बताया गया है कि हर स्थिति के लिए कैनवस रिस्पॉन्स कैसे दिखाया जाता है.

इंटरैक्टिव कैनवस की सुविधा चालू करें

इंटरैक्टिव कैनवस का इस्तेमाल करने के लिए, आपको अपनी सेट की गई कार्रवाई को किसी खास तरीके से कॉन्फ़िगर करना होगा. इंटरैक्टिव कैनवस का इस्तेमाल करने वाली कोई कार्रवाई बनाने के लिए, ऐक्शन कंसोल में अतिरिक्त कॉन्फ़िगरेशन की ज़रूरत होती है. साथ ही, ऐक्शन SDK टूल के लिए आपकी settings.yaml फ़ाइल में बदलाव करने की ज़रूरत होती है. Actions SDK टूल की मदद से, इंटरैक्टिव कैनवस ऐक्शन बनाने और उसे कॉन्फ़िगर करने की पूरी प्रोसेस जानने के लिए, प्रोजेक्ट बनाना लेख पढ़ें.

Actions Builder का इस्तेमाल करते समय, इंटरैक्टिव कैनवस चालू करने के लिए यह तरीका अपनाएं:

1. अगर आपने आपको किस तरह की कार्रवाई बनानी है? स्क्रीन पर, गेम कार्ड नहीं चुना है, तो सबसे ऊपर मौजूद नेविगेशन में डिप्लॉय करें पर क्लिक करें. ज़्यादा जानकारी में, गेम और मज़ेदार कैटगरी चुनें. सेव करें पर क्लिक करें.
2. Actions कंसोल के सबसे ऊपर मौजूद नेविगेशन में, डेवलप करें पर क्लिक करें.
3. बाएं नेविगेशन में, इंटरैक्टिव कैनवस पर क्लिक करें.
4. क्या आपकी सेट की गई कार्रवाई में इंटरैक्टिव कैनवस का इस्तेमाल करना है? में, इनमें से कोई एक चुनें:
   • सर्वर वेबहुक फ़ुलफ़िलमेंट की मदद से इंटरैक्टिव कैनवस को चालू करें. यह विकल्प कुछ सुविधाओं को ऐक्सेस करने के लिए, वेबहुक पर निर्भर करता है. साथ ही, वेब ऐप्लिकेशन में डेटा भेजने के लिए अक्सर onUpdate() का इस्तेमाल करता है. चालू होने पर, इंटेंट मैच को सीन के तौर पर हैंडल किया जाता है. साथ ही, किसी दूसरे सीन पर जाने या बातचीत खत्म करने से पहले, वेबहुक को कॉल किया जा सकता है.
   • क्लाइंट फ़ुलफ़िलमेंट के साथ इंटरैक्टिव कैनवस चालू करें. इस विकल्प की मदद से, वेबहुक फ़ुलफ़िलमेंट लॉजिक को वेब ऐप्लिकेशन में ले जाया जा सकता है. साथ ही, वेबहुक कॉल को बातचीत वाली सिर्फ़ उन सुविधाओं तक सीमित किया जा सकता है जिनमें इसकी ज़रूरत होती है, जैसे कि खाता लिंक करना. इसके चालू होने पर, क्लाइंट-साइड पर इंटेंट हैंडलर रजिस्टर करने के लिए expect() का इस्तेमाल किया जा सकता है.
5. ज़रूरी नहीं: अपना डिफ़ॉल्ट वेब ऐप्लिकेशन यूआरएल सेट करें फ़ील्ड में अपना वेब ऐप्लिकेशन यूआरएल डालें. इस कार्रवाई से डिफ़ॉल्ट रूप से Canvas रिस्पॉन्स जुड़ जाएगा. साथ ही, यह जवाब आपके मुख्य इवेंट में, यूआरएल फ़ील्ड के साथ जुड़ जाएगा.
6. सेव करें पर क्लिक करें.

कार्रवाइयां SDK टूल का इस्तेमाल करते समय, इंटरैक्टिव कैनवस चालू करने के लिए यह तरीका अपनाएं:

1. अपनी settings.yaml फ़ाइल के category फ़ील्ड को GAMES_AND_TRIVIA पर सेट करें. इससे आपकी सेट की गई कार्रवाई को खोजने में लोगों की मदद की जा सकेगी और उनके बारे में बेहतर तरीके से जानकारी दी जा सकेगी.
2. अपनी settings.yaml फ़ाइल के usesInteractiveCanvas फ़ील्ड को true पर सेट करें.

सतह की क्षमता की जांच करें

इंटरैक्टिव कैनवस फ़्रेमवर्क सिर्फ़ Assistant की सुविधा वाले उन डिवाइसों पर काम करता है जो विज़ुअल इंटरफ़ेस उपलब्ध कराते हैं. इसलिए, आपकी सेट की गई कार्रवाई को यह देखना होगा कि उपयोगकर्ता के डिवाइस पर INTERACTIVE_CANVAS क्षमता है या नहीं. Actions Builder में प्रॉम्प्ट तय करते समय, candidates ऑब्जेक्ट के selector फ़ील्ड में, डिवाइस की क्षमताओं की सूची तय की जा सकती है. प्रॉम्प्ट चुनने वाला टूल, ऐसे प्रॉम्प्ट कैंडिडेट को चुनता है जो उपयोगकर्ता के डिवाइस की क्षमता के हिसाब से सबसे सही हो.

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 जवाब में वेब ऐप्लिकेशन का यूआरएल होना चाहिए. इस तरह के Canvas जवाब में Google Assistant को उपयोगकर्ता के डिवाइस पर उस पते पर वेब ऐप्लिकेशन रेंडर करने के लिए कहा जाता है. आम तौर पर, उपयोगकर्ता के आपकी सेट की गई कार्रवाई को शुरू करने के तुरंत बाद, पहला Canvas रिस्पॉन्स भेजा जाता है. वेब ऐप्लिकेशन लोड होने पर, इंटरैक्टिव कैनवस लाइब्रेरी लोड होती है और वेब ऐप्लिकेशन, Interactive Canvas API के साथ एक कॉलबैक हैंडलर रजिस्टर करता है.

नीचे दिए गए स्क्रीनशॉट में दिखाए गए तरीके से, Actions Builder में अपने वेब ऐप्लिकेशन का यूआरएल तय किया जा सकता है:

अगर आपने ऐसा प्रॉम्प्ट बनाया है जिसमें वेब ऐप्लिकेशन के यूआरएल की जानकारी देने के बाद, Canvas रिस्पॉन्स शामिल है, तो Actions Builder Canvas जवाब के यूआरएल फ़ील्ड में अपने-आप जानकारी भर जाएगा. कंसोल में वेब ऐप्लिकेशन यूआरएल सेट करने के बारे में ज़्यादा जानकारी के लिए, इंटरैक्टिव कैनवस चालू करें सेक्शन देखें.

नीचे दिए गए स्निपेट से Canvas रिस्पॉन्स बनाने का तरीका पता चलता है, जो वेब ऐप्लिकेशन को Actions Builder और आपके वेबहुक, दोनों में रेंडर करते हैं:

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 वाला शुरुआती जवाब भेजने के बाद, data में अपडेट देने के लिए, अतिरिक्त Canvas रिस्पॉन्स इस्तेमाल किए जा सकते हैं. आपके वेब ऐप्लिकेशन का कस्टम लॉजिक, आपके वेब ऐप्लिकेशन में बदलाव करने के लिए इसका इस्तेमाल करता है. जब वेब ऐप्लिकेशन को डेटा पास करने वाला Canvas रिस्पॉन्स भेजा जाता है, तो यह तरीका अपनाया जा सकता है:

1. जब किसी सीन में इंटेंट को मैच किया जाता है, तो यह एक इवेंट ट्रिगर करता है. इसके बाद, JSON पेलोड के साथ data फ़ील्ड वाला Canvas रिस्पॉन्स, रिस्पॉन्स के तौर पर वापस भेजा जाता है.
2. data फ़ील्ड को onUpdate कॉलबैक में भेजा जाता है और इसका इस्तेमाल वेब ऐप्लिकेशन को अपडेट करने के लिए किया जाता है.

3. आपकी बातचीत वाली कार्रवाई, नया Canvas जवाब भेज सकती है और नए अपडेट भेजने या नई स्थितियां लोड करने के लिए, data फ़ील्ड में जानकारी दे सकती है.

अपने वेब ऐप्लिकेशन पर डेटा भेजने के दो तरीके हैं:

• Actions Builder की मदद से. ऐक्शन बिल्डर, Canvas के जवाब में दिए गए data फ़ील्ड में ज़रूरी मेटाडेटा अपने-आप भर देता है. इसमें वेब ऐप्लिकेशन को अपडेट करने के लिए ज़रूरी मेटाडेटा शामिल होता है.
• वेबहुक की मदद से. अगर आपके पास कोई वेबहुक है, तो Canvas रिस्पॉन्स में वेब ऐप्लिकेशन को अपडेट करने के लिए, कस्टम डेटा पेलोड कॉन्फ़िगर किया जा सकता है.

इन सेक्शन में, Actions Builder से और वेबहुक के ज़रिए डेटा भेजने का तरीका बताया गया है.

डेटा भेजने के लिए Actions Builder का इस्तेमाल करना

Actions Builder की मदद से, आपको अपने वेब ऐप्लिकेशन को भेजे गए मेटाडेटा को मैनेज करने के लिए, वेबहुक तय करने की ज़रूरत नहीं होती. इसके बजाय, Actions Builder यूज़र इंटरफ़ेस (यूआई) में अपना इंटेंट हैंडलर कॉन्फ़िगर करते समय, Canvas रिस्पॉन्स शामिल किया जा सकता है. वेब ऐप्लिकेशन को अपडेट करने के लिए, data फ़ील्ड में ज़रूरी मेटाडेटा अपने-आप भर जाता है. जैसे, इंटेंट का नाम, उपयोगकर्ता के इनपुट से कैप्चर किए गए पैरामीटर, और मौजूदा सीन.

उदाहरण के लिए, यह Guess इंटेंट हैंडलर बताता है कि आपको एक Canvas रिस्पॉन्स शामिल करना है:

candidates:
  - canvas:
      send_state_data_to_canvas_app: true
    

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

आप टीटीएस मैसेज भेजने के लिए, नीचे दिए गए स्निपेट को इंटेंट हैंडलर में वैकल्पिक रूप से जोड़ सकते हैं:

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

यह रिस्पॉन्स, आपके वेब ऐप्लिकेशन को उपयोगकर्ता के जवाब से अपडेट कर देता है और सही सीन पर ट्रांज़िशन कर देता है.

डेटा भेजने के लिए अपने वेबहुक का इस्तेमाल करें

अपने वेब ऐप्लिकेशन को अपडेट करने के लिए, स्थिति की ज़रूरी जानकारी के साथ अपने वेबहुक में Canvas रिस्पॉन्स के data फ़ील्ड को मैन्युअल तरीके से कॉन्फ़िगर किया जा सकता है. अगर आपको वेब ऐप्लिकेशन को अपडेट करने के लिए ज़रूरी सामान्य मेटाडेटा को पास करने के बजाय, Canvas के जवाब में कस्टम data पेलोड शामिल करना है, तो इस तरीके का सुझाव दिया जाता है.

नीचे दिए गए स्निपेट, आपके वेबहुक में Canvas रिस्पॉन्स में डेटा पास करने का तरीका दिखाते हैं:

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 जवाबों के लिए इन दिशा-निर्देशों और पाबंदियों को ध्यान में रखें:

• आपके फ़ुलफ़िलमेंट में हर वेबहुक हैंडलर में Canvas शामिल होना चाहिए. अगर वेबहुक रिस्पॉन्स में Canvas शामिल नहीं है, तो आपका वेब ऐप्लिकेशन बंद हो जाता है.
• उपयोगकर्ता को भेजे जाने वाले पहले Canvas जवाब में आपको सिर्फ़ अपना वेब ऐप्लिकेशन यूआरएल शामिल करना होगा.
• Canvas रिस्पॉन्स यूआरएल मान्य होना चाहिए और उसका प्रोटोकॉल एचटीटीपीएस होना चाहिए.
• Canvas रिस्पॉन्स का साइज़ 50 केबी या उससे कम होना चाहिए.