Подсказки на холсте

Чтобы передать информацию в ваше веб-приложение, вы должны отправить ответ Canvas из своей диалоговой логики. Ответ Canvas может выполнять одно из следующих действий:

  • Отображение полноэкранного веб-приложения на устройстве пользователя.
  • Передача данных для обновления веб-приложения

В следующих разделах описано, как вернуть ответ Canvas для каждого сценария.

Включить интерактивный холст

Чтобы использовать интерактивное полотно, вы должны настроить свое действие определенным образом. Создание действия, использующего интерактивное полотно, требует дополнительной настройки в консоли действий (а для Actions SDK — внесения изменений в файл settings.yaml ). Полную процедуру создания и настройки действия Interactive Canvas с помощью Actions SDK см. в разделе Создание проекта .

При использовании Actions Builder выполните следующие дополнительные шаги, чтобы включить интерактивное полотно:

  1. Если вы не выбрали игровую карту в поле «Какой тип действия вы хотите построить?» экране нажмите «Развернуть» в верхней части навигации. В разделе «Дополнительная информация» выберите категорию «Игры и развлечения» . Нажмите Сохранить .
  2. Нажмите «Разработка» в верхней части навигации консоли «Действия».
  3. Нажмите «Интерактивный холст» на левой панели навигации.
  4. В разделе « Хотите ли вы, чтобы ваше действие использовало интерактивное полотно?» , выберите один из следующих вариантов:
    • Включите Interactive Canvas с выполнением веб-перехватчика сервера. Этот параметр использует веб-перехватчик для доступа к определенным функциям и часто использует onUpdate() для передачи данных в веб-приложение. Если этот параметр включен, совпадения намерений обрабатываются в сценах, и вы можете вызвать веб-перехватчик перед переходом к другой сцене или завершением разговора.
    • Включите Interactive Canvas для выполнения клиентов. Этот параметр позволяет перенести логику выполнения веб-перехватчика в веб-приложение и ограничить вызовы веб-перехватчика только теми диалоговыми функциями, которые этого требуют, например привязкой учетной записи. Если эта функция включена, вы можете использовать expect() для регистрации обработчиков намерений на стороне клиента.
  5. Необязательно : введите URL-адрес веб-приложения в поле «Установить URL-адрес веб-приложения по умолчанию» . Это действие добавляет ответ Canvas по умолчанию с полем URL-адреса к вашему основному вызову.
  6. Нажмите Сохранить .

При использовании Actions SDK выполните следующие дополнительные действия, чтобы включить интерактивное полотно:

  1. Установите для поля category в файле settings.yaml значение GAMES_AND_TRIVIA чтобы лучше описать и помочь пользователям найти ваше действие.
  2. Установите для поля usesInteractiveCanvas в файле settings.yaml значение true .

Проверьте возможности поверхности

Платформа Interactive Canvas работает только на устройствах 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.

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 сразу после того, как пользователь вызывает ваше действие. Когда веб-приложение загружается, загружается библиотека Interactive Canvas, и веб-приложение регистрирует обработчик обратного вызова с помощью API Interactive Canvas.

Вы можете указать URL-адрес своего веб-приложения в Actions Builder, как показано на следующем снимке экрана:

Если вы создаете приглашение, включающее ответ Canvas , после указания URL-адреса веб-приложения, Actions Builder автоматически заполняет поле URL-адреса ответа Canvas . Дополнительные сведения о настройке URL-адреса веб-приложения в консоли см. в разделе «Включить интерактивное полотно» .

В следующих фрагментах показано, как создавать ответы 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'

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. Когда намерение совпадает в сцене, оно вызывает событие, и ответ Canvas , содержащий поле data с полезной нагрузкой JSON, затем отправляется обратно в качестве ответа.
  2. Поле data передается обратному вызову onUpdate и используется для обновления веб-приложения.

  3. Ваше диалоговое действие может отправить новый ответ Canvas и предоставить информацию в поле data для отправки новых обновлений или загрузки новых состояний.

Вы можете передавать данные в свое веб-приложение двумя способами:

  • С помощью Action Builder . Actions Builder автоматически заполняет поле data в ответе Canvas необходимыми метаданными для обновления веб-приложения.
  • С помощью вебхука . Если у вас есть веб-перехватчик, вы можете настроить пользовательские полезные данные для обновления веб-приложения в ответе Canvas .

В следующих разделах описывается, как передавать данные через Actions Builder и через веб-перехватчик.

Используйте Actions Builder для передачи данных

Благодаря Actions Builder вам не нужно определять веб-перехватчик для управления метаданными, отправляемыми в ваше веб-приложение. Вместо этого, когда вы настраиваете обработчик намерений в пользовательском интерфейсе Actions Builder, вы можете включить ответ Canvas . Поле data автоматически заполняется метаданными, необходимыми для обновления вашего веб-приложения, такими как имя намерения, любые параметры, полученные из ввода пользователя, и текущая сцена.

Например, следующий обработчик намерения Guess указывает, что вы хотите включить ответ Canvas :

ЯМЛ 

candidates:
  - canvas:
      send_state_data_to_canvas_app: true

JSON

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

При желании вы можете добавить следующий фрагмент к обработчику намерений для отправки сообщения TTS:

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

Actions Builder автоматически дополняет ответ Canvas метаданными для обновления веб-приложения, как показано в следующих фрагментах. В данном случае пользователь угадывал букву «а» в игре на угадывание слов:

ЯМЛ 

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

Этот ответ обновляет ваше веб-приложение ответом пользователя и переходит к соответствующей сцене.

Используйте вебхук для передачи данных

Вы можете вручную настроить поле data ответов Canvas в веб-перехватчике, указав необходимую информацию о состоянии для обновления вашего веб-приложения. Этот подход рекомендуется, если вам нужно включить пользовательские полезные data в ответ Canvas , а не только передавать типичные метаданные, необходимые для обновления веб-приложения.

В следующих фрагментах показано, как передавать данные в ответе Canvas в веб-перехватчике:

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 :

  • Каждый обработчик веб-перехватчика в вашем исполнении должен включать Canvas . Если ответ веб-перехватчика не включает Canvas , ваше веб-приложение закрывается.
  • Вам нужно только включить URL-адрес вашего веб-приложения в первый ответ Canvas , который вы отправляете пользователю.
  • URL-адрес ответа Canvas должен быть действительным, а его протокол должен быть https.
  • Размер ответа Canvas должен составлять 50 КБ или меньше.