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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Общий синтаксис 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.

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

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

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

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

Что касается намерений пользователя, 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',
}

Параметры 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, вам необходимо следующее:

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

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

  1. Включите на свою страницу следующую библиотеку JavaScript, заменив <PROJECT_ID> идентификатором проекта Actions:

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
    </script>
    
  2. Добавьте следующий HTML-тег где-нибудь на своей странице. При этом загружается встроенная кнопка «Попробуйте с Google Assistant»:

    <google-assistant-link-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> . Когда вы применяете этот тег, ссылка активируется без пользователей при первом посещении и без нажатия встроенной кнопки.

  1. Добавьте 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>
    
  2. Разместите тег <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>

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

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

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

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

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

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

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