Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

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

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

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

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

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

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

Проверьте способность поверхности

Инфраструктура интерактивного холста работает только на устройствах Assistant, которые предоставляют визуальный интерфейс, поэтому вашему действию необходимо проверить возможность INTERACTIVE_CANVAS на устройстве пользователя. Когда вы определяете подсказки в Actions Builder, вы можете указать список возможностей устройства в поле selector объекта candidates . Селектор подсказок выбирает вариант подсказки, наиболее подходящий для возможностей устройства пользователя.

Чтобы вернуть ответ Canvas , логика вашего действия должна выполнять следующие действия:

Убедитесь, что устройство пользователя поддерживает возможность INTERACTIVE_CANVAS . Если это так, отправьте пользователю ответ Canvas .
Если возможность Interactive Canvas недоступна, проверьте, поддерживает ли устройство пользователя возможность RICH_RESPONSE . Если это так, отправьте пользователю расширенный ответ .
Если возможность расширенного ответа недоступна, отправьте пользователю простой ответ .

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

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.');
}

Рендеринг веб-приложения

Действие, использующее Interactive Canvas, включает веб-приложение с настроенными визуальными элементами, которые вы отправляете пользователям в качестве ответа. После отображения веб-приложения пользователи продолжают взаимодействовать с ним с помощью голоса, текста или касаний, пока разговор не будет завершен.

Ваш первый ответ Canvas должен содержать URL-адрес веб-приложения. Этот тип ответа Canvas сообщает Google Assistant об отображении веб-приложения по этому адресу на устройстве пользователя. Как правило, вы отправляете первый ответ Canvas сразу после того, как пользователь вызывает ваше действие. Когда загружается веб-приложение, загружается библиотека Interactive Canvas, и веб-приложение регистрирует обработчик обратного вызова с помощью Interactive Canvas API.

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

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

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

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 , который передает данные в веб-приложение, выполняются следующие шаги:

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

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

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

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

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

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

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

YAML

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 метаданными для обновления веб-приложения, как показано в следующих фрагментах. В данном случае пользователь угадал букву «а» в игре на угадывание слов:

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

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

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

Вы можете вручную настроить поле 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": ""
    }
  }
}

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

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

Проверьте способность поверхности

YAML

JSON

Node.js

Рендеринг веб-приложения

YAML

JSON

Node.js

JSON

Передача данных для обновления веб-приложения

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

YAML

JSON

YAML

JSON

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

Node.js

JSON

Рекомендации и ограничения