Диалоговые действия устарели 13 июня 2023 г. Дополнительные сведения см. в разделе Закрытие диалоговых действий .

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

Ссылки помощника

Вы можете создать URL-адрес, который напрямую ссылается на конкретное намерение вашего действия. Пользователи, которые нажимают ссылку Ассистента (ранее называвшуюся ссылками действий) в веб-браузере или мобильном браузере, перенаправляются к Ассистенту на своем устройстве, где они напрямую взаимодействуют с вашим действием.

Ссылки Ассистента отличаются от веб-ссылок каталога , которые направляют пользователя на страницу вашего действия в каталоге Ассистента .

Вот несколько ситуаций, в которых ссылки Ассистента могут быть полезны:

Связывание пользователей с голосовыми инструкциями с практического веб-сайта.
Связывание пользователей со службой поддержки клиентов со страницы справки.
Связывание пользователей с намерением обновить , чтобы они могли подписаться на ваши будущие обновления.

Создать ссылку Ассистента

Вы можете создавать ссылки Ассистента из своего проекта в консоли действий. Ссылки на помощника доступны по всем каналам развертывания (альфа-, бета-версии и рабочей версии). Например, если ссылка на Ассистента включена в альфа-версии вашего действия, она будет доступна альфа-тестерам.

Чтобы создать URL-адрес для действия, выполните следующие действия:

В консоли «Действия» выберите «Развертывание» > «Ссылки помощника» .
В поле Intent выберите намерение, для которого вы хотите создать ссылку.
Включите параметр «Хотите ли вы включить связывание для Intent_name?» вариант.
(необязательно) В разделе «Параметры кампании» введите любую информацию, которую вы хотите дополнительно зафиксировать в ссылке в качестве параметров URL.
(необязательно) Введите заголовок ссылки . Используйте этот заголовок, чтобы описать, что делает Действие. Например, если ваше действие переводит пользователя в поток транзакций , чтобы купить билеты на концерт, заголовок вашей ссылки может быть «купить билеты на концерт».

После ввода информации вы можете просмотреть и скопировать сгенерированный URL-адрес или сгенерированный фрагмент кода для ссылки Ассистента. Используйте ссылку «Ассистент» везде, где вы хотите направить пользователей к этому конкретному действию.

Ссылки на Ассистента тестирования

Вы можете проверить ссылки Ассистента на предмет любого намерения (основного или пользовательского, с параметрами или без них) через симулятор или на устройстве.

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

Создайте ссылку «Ассистент» в консоли «Действия».
Отправьте ссылку Ассистента себе в виде URL-адреса по электронной почте, в сообщении чата или в другом формате.
На устройстве с поддержкой Assistant войдите в Assistant, используя ту же учетную запись, которую вы использовали для создания проекта Actions.
На том же устройстве нажмите на ссылку Ассистента, которую вы отправили себе.

После того, как вы подтвердите, что ссылка Ассистента функционирует должным образом, вам необходимо повторно развернуть свое действие, чтобы сделать ссылку доступной для ваших пользователей.

Параметры ссылки Ассистента

Ссылки помощника могут дополнительно содержать намерение и параметры в URL-адресе. Используйте раздел «Параметры кампании» , чтобы добавить параметры кампании.

Если ссылка Ассистента не содержит дополнительных параметров, Google Ассистент ссылается на MAIN намерение ( actions.intent.MAIN ) вашего действия со следующим поведением:

Если вы явно не включили намерение MAIN в ссылке Assistant, Assistant сопоставляет основное намерение без каких-либо параметров, аналогично поведению для «Поговорить с app_name».
Если вы явно включили намерение MAIN , Ассистент передает параметры вашим действиям.

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

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4

Спецификация URL-адреса ссылки Ассистента

Общий синтаксис URL-адреса ссылки Ассистента следующий:

https://assistant.google.com/services/invoke[/$action_id][?intent=$intent&param.$param=$value][&$utm_param=$utm_value]

Параметры URL-адреса, которые вы можете установить, описаны в следующей таблице:

URL-параметр	Описание
`$action_id`	Числовой идентификатор действия.
`$intent`	Полное имя встроенного или пользовательского намерения.
`$param`	Полное имя параметра намерения, указанного в пакете действий.
`$value`	Значение в кодировке URL-адреса типа, объявленного для `$param` в пакете Action.
`$utm_param`	Список одного или нескольких типов параметров UTM. Допустимые значения: `utm_source` , `utm_medium` , `utm_campaign` , `utm_term` и `utm_content` .
`$utm_value`	Строковое значение параметра UTM.

URL-адреса ссылок Ассистента со встроенными намерениями

Если ссылка Ассистента содержит встроенное намерение (намерение начинается с actions.intent. ), Google Assistant пытается извлечь любые встроенные параметры намерения из URL-адреса и передает их вашему действию. Любые параметры, которые Ассистент не воспринимает как встроенные параметры намерения, удаляются.

Для диалоговых действий Ассистент отправляет эти параметры вам как часть сообщения AppRequest .

В следующем примере показано, как можно указать URL-адрес ссылки Ассистента, включающий встроенное намерение, с одним параметром намерения:

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.PLAY_GAME&param.name=%22ExampleGame%22

URL-адреса ссылок Ассистента на намерения пользователя

Что касается намерений пользователя, Google Assistant извлекает только те параметры, которые определены вашим действием как часть намерения, и отбрасывает любые другие параметры.

В следующем примере показано, как можно указать URL-адрес ссылки Ассистента, включающий намерение пользователя:

https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK&param.topic=sports

Для приведенного выше примера URL-адреса в AppRequest Assistant добавляет объект JSON следующим образом:

argument {
  name: 'topic',
  raw_text: 'sports',
  text_value: 'sports',
}

URL-адреса ссылок Ассистента с параметрами UTM

Параметры UTM — это строки, которые Google Assistant отправляет вашему действию, когда пользователи нажимают на ссылку Ассистента. Вы можете использовать информацию, содержащуюся в этих строках, позже для аналитики.

Параметры UTM, которые Ассистент отправляет в ваше действие, включают следующее:

utm_source
utm_medium
utm_campaign
utm_term
utm_content

В следующем примере показано, как можно указать URL-адрес ссылки Ассистента, включающий параметры UTM:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4?utm_source=Google&utm_medium=email&utm_campaign=holiday+sale

Для приведенного выше примера URL-адреса Assistant добавляет следующие аргументы в сообщение AppRequest :

argument {
  name: 'utm_source',
  raw_text: 'Google',
  text_value: 'Google',
}
argument {
  name: 'utm_medium',
  raw_text: 'email',
  text_value: 'email',
}
argument {
  name: 'utm_campaign',
  raw_text: 'holiday sale',
  text_value: 'holiday sale',
}

Расширенные ссылки Ассистента

Ссылки с расширенными возможностями Ассистента дают вам возможность повысить узнаваемость вашего действия на вашем веб-сайте с помощью Assist.js. Пользователи могут опробовать ваше действие, а также связать свою учетную запись Google с вашим сервисом, используя привязку учетных записей.

Когда пользователь посещает ваш веб-сайт, он видит кнопку «Попробовать с Google Assistant», которая запускает поток ссылок Rich Assistant.

Включение привязки учетных записей для вашего действия позволяет пользователям получать доступ к вашему действию на любом из своих устройств с поддержкой Ассистента. Кроме того, пользователи могут связать свою учетную запись вашего сервиса со своей учетной записью Google, что обеспечивает более персонализированный опыт.

При использовании со связыванием учетных записей ссылки Rich Assistant используют ваш URL-адрес авторизации, который установлен в вашем проекте в консоли действий. Дополнительную информацию см. в документации по привязке учетной записи .

Предварительные условия

Чтобы использовать ссылки Rich Assistant, вам необходимо следующее:

Проект действий .
Ссылка на Ассистента включена для вашего действия.
(Необязательно) Для вашего действия включена привязка аккаунтов .

Местное развитие

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

Включите на свою страницу следующую библиотеку JavaScript, заменив <PROJECT_ID> идентификатором проекта Actions:
```
<script async
src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
</script>
```
Добавьте следующий HTML-тег где-нибудь на своей странице. При этом загружается встроенная кнопка «Попробуйте с Google Assistant»:
```
<google-assistant-link-group>
  
  <google-assistant-link href="{ASSISTANT_LINK_1}">
  </google-assistant-link>
  <google-assistant-link href="{ASSISTANT_LINK_2}">
  </google-assistant-link>
</google-assistant-link-group>
```
Примечание. Если пользователь Помощника не вошел в систему, первая ссылка Помощника запускает Помощника или перенаправляет пользователя на страницу Каталога Помощников для выполнения вашего действия.

Упреждающий запуск

Если вы хотите, чтобы поток ссылок с расширенными возможностями Ассистента запускался автоматически, когда пользователи впервые посещают вашу страницу, используйте тег <google-assistant-proactive-link> . Когда вы применяете этот тег, ссылка активируется без пользователей при первом посещении и без нажатия встроенной кнопки.

Добавьте id в тег группы ссылок Ассистента:

<google-assistant-link-group id="my-group">
  <!-- One or more <google-assistant-link> tags -->
  <google-assistant-link href="{ASSISTANT_LINK_1}">
  </google-assistant-link>
  <google-assistant-link href="{ASSISTANT_LINK_2}">
  </google-assistant-link>
</google-assistant-link-group>

Разместите тег <google-assistant-proactive-action-link> на своей веб-странице и присвойте его атрибуту groupId значение id :

<google-assistant-link-group id="my-group">
  <!-- One or more <google-assistant-link> tags -->
  <google-assistant-link href="{ASSISTANT_LINK_1}">
  </google-assistant-link>
  <google-assistant-link href="{ASSISTANT_LINK_2}">
  </google-assistant-link>
</google-assistant-link-group>

<google-assistant-proactive-link
groupId="my-group">
</google-assistant-proactive-link>

Развертывание

Ссылки Rich Assistant работают только для принадлежащих вам доменов, подтвержденных Google . При локальной разработке это требование обходит, имея доступ к проекту Actions, входя в свою учетную запись Google и устанавливая параметр запроса dev=true в теге скрипта.

  <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
  </script>

Чтобы развернуть свое действие с помощью расширенных ссылок Ассистента:

Зарегистрируйте свой общедоступный домен в консоли действий в разделе «Развертывание» > «Проверка бренда» > «Подключить сайт» .

Удалите из скрипта параметр запроса dev=true :

<script async
src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}">
</script>

Ограничения и лучшие практики

Чтобы URL-адрес ссылки Ассистента мог распространяться и на него можно было ссылаться за пределами каталога или других служб Google, применяются следующие ограничения и рекомендации:

Продолжайте поддерживать все ссылки вашего Ассистента. Если вы распространите ссылку Ассистента, которая позже сломается, ваш проект Actions может быть помечен как неработоспособный и удален.
Публикация ссылки означает, что вы поддерживаете запуск из ненадежных источников. Для любых связанных действий вы должны явно подтвердить это у пользователя, прежде чем предпринимать какие-либо реальные действия. Например, действие, которое отключает интеллектуальное бытовое устройство, должно предлагать пользователю вопрос: «Вы уверены, что хотите отключить $applianceName ?»
В этом контексте реальным действием является любое действие, которое влияет на службы, данные, устройства, сети, компьютеры или API пользователя. Например, отправка электронного письма, выполнение транзакции, изменение статуса умного домашнего устройства, создание подписки или обновление части контента.