Conversational Actions were deprecated on June 13, 2023. For more information, see Conversational Actions sunset.

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

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

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

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

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

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

Создать ссылку на помощника

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

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

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

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

Ссылки на помощника по тестированию

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

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

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

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

Параметры ссылки помощника

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

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

Если вы явно не включили MAIN намерение в ссылке Помощника, Помощник соответствует основному намерению без каких-либо параметров, аналогично поведению для «Поговорить с 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`	Полное имя параметра намерения, указанное в пакете Action.
`$value`	Закодированное в URL значение типа, объявленного для `$param` в пакете Action.
`$utm_param`	Список одного или нескольких типов параметров UTM. Допустимые значения включают: `utm_source` , `utm_medium` , `utm_campaign` , `utm_term` и `utm_content` .
`$utm_value`	Строковое значение параметра UTM.

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

Если ссылка Ассистента содержит встроенное намерение (намерение начинается с actions.intent. ), Google Ассистент пытается извлечь любые встроенные параметры намерения в 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 отправляет вашему действию, когда пользователи нажимают на ссылку 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',
}

Ссылки на расширенный помощник

Ссылки Rich Assistant дают вам возможность увеличить количество обнаружений ваших действий на вашем веб-сайте с помощью 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.

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

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

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

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

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

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

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

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