Linki Asystenta

Możesz wygenerować adres URL, który będzie bezpośrednio prowadzić do określonej intencji akcji. Użytkownicy, którzy klikną link Asystenta (wcześniej nazywany linkami do działania) w przeglądarce internetowej lub mobilnej, zostaną przekierowani do Asystenta na urządzeniu, gdzie wchodzą w bezpośrednią interakcję z akcją.

Linki Asystenta różnią się od linków internetowych do katalogu, które kierują użytkownika na stronę akcji w katalogu Asystenta.

Oto kilka sytuacji, w których linki Asystenta mogą być przydatne:

  • Udostępnianie użytkownikom instrukcji głosowych w witrynie z instrukcjami.
  • Łączenie użytkowników z obsługą klienta na stronie pomocy.
  • połączenie użytkowników z zamiarem dokonania aktualizacji, co umożliwi im wyrażenie zgody na przyszłe aktualizacje.

Linki do Asystenta możesz generować z poziomu projektu w Konsoli Actions. Linki do Asystenta są dostępne we wszystkich kanałach wdrażania (alfa, beta i produkcyjnej). Jeśli na przykład link do Asystenta jest włączony w wersji alfa akcji, jest on dostępny dla testerów wersji alfa.

Aby wygenerować adres URL działania, wykonaj te czynności:

  1. W Konsoli Actions kliknij Wdróż > Połączenia z Asystentem.
  2. W polu Intencja wybierz intencję, dla której chcesz wygenerować link.
  3. Włącz opcję Czy chcesz włączyć połączenie dla intencji intencji_name?.
  4. (Opcjonalnie) W sekcji Parametry kampanii wpisz informacje, które chcesz dodatkowo rejestrować w linku jako parametry adresu URL.
  5. (Opcjonalnie) Wpisz Tytuł linku. W tym tytule opisz, co robi akcja. Jeśli na przykład akcja ogranicza użytkownikowi proces transakcji, by kupić bilety na koncert, tytuł linku może wyglądać tak: „kup bilety na koncert”.

Po wpisaniu informacji możesz wyświetlić i skopiować wygenerowany adres URL lub wygenerowany fragment kodu do linku Asystenta. Jeśli chcesz skierować użytkowników do tej akcji, użyj linku Asystenta.

Linki Asystenta możesz testować w przypadku dowolnej intencji (głównej lub niestandardowej, z parametrami lub bez) za pomocą symulatora lub na urządzeniu.

Aby przetestować link Asystenta na urządzeniu, wykonaj te czynności:

  1. Wygeneruj link do Asystenta w Konsoli Actions.
  2. Wyślij do siebie link do Asystenta jako adres URL w e-mailu, wiadomości na czacie lub w innym formacie.
  3. Na urządzeniu z Asystentem zaloguj się w Asystencie za pomocą tego samego konta, które zostało użyte do utworzenia projektu w Actions.
  4. Na tym samym urządzeniu kliknij link do Asystenta, który został przez Ciebie wysłany.

Po potwierdzeniu, że funkcja połączenia z Asystentem działa zgodnie z oczekiwaniami, musisz ponownie wdrożyć akcję, aby udostępnić link użytkownikom.

Linki Asystenta mogą zawierać w adresie URL intencję i parametry. W sekcji Parametry kampanii możesz dodać parametry kampanii.

Gdy link Asystenta nie zawiera dodatkowych parametrów, Asystent Google łączy się z intencją MAIN (actions.intent.MAIN) akcji w taki sposób:

  • Jeśli nie masz wyraźnie włączonej intencji MAIN w linku do Asystenta, Asystent dopasowuje główną intencję bez żadnych parametrów, podobnie jak w przypadku polecenia „Porozmawiaj z aplikacją app_name”.
  • Jeśli wyraźnie włączysz intencję MAIN, Asystent przekaże parametry do akcji.

Oto przykład adresu URL linku Asystenta z użyciem intencji MAIN bez dodatkowych parametrów:

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

Ogólna składnia adresu URL linku Asystenta jest taka:

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

Parametry adresu URL, które możesz ustawić, zostały opisane w tej tabeli:

Parametr URL Opis
$action_id Identyfikator numeryczny akcji.
$intent Pełna nazwa intencji wbudowanej lub intencji użytkownika.
$param Pełna nazwa parametru intencji określonego w pakiecie akcji.
$value Zakodowana w adresie URL wartość typu zadeklarowanego dla atrybutu $param w pakiecie akcji.
$utm_param Lista co najmniej jednego typu parametru UTM. Prawidłowe wartości to utm_source, utm_medium, utm_campaign, utm_term i utm_content.
$utm_value Wartość ciągu znaków parametru UTM.

Jeśli link Asystenta zawiera intencję wbudowaną (intencja rozpoczyna się od actions.intent.), Asystent Google próbuje wyodrębnić wszelkie wbudowane parametry intencji w adresie URL i przekaże je do akcji. Wszelkie parametry, których Asystent nie rozumie, ponieważ wbudowane parametry intencji są usuwane.

W przypadku akcji dotyczących rozmów Asystent wysyła te parametry do Twojej realizacji w ramach wiadomości AppRequest.

Z przykładu poniżej dowiesz się, jak określić adres URL linku Asystenta, który zawiera intencję wbudowaną z pojedynczym parametrem intencji:

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

W przypadku intencji użytkownika Asystent Google wyodrębnia tylko parametry zdefiniowane przez akcję w ramach intencji i odrzuca pozostałe.

Z przykładu poniżej dowiesz się, jak określić adres URL linku Asystenta zawierającego intencję użytkownika:

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

W przypadku powyższego przykładowego adresu URL w AppRequest Asystent dodaje obiekt JSON w ten sposób:

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

Parametry monitora UTM to ciągi znaków, które Asystent Google wysyła do Twojej akcji, gdy użytkownik kliknie link do Asystenta. Informacje zawarte w tych ciągach możesz później wykorzystać na potrzeby analiz.

Asystent przesyła do akcji parametry monitora UTM:

  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

Z tego przykładu dowiesz się, jak określić adres URL linku Asystenta z parametrami monitora UTM:

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

Do przykładowego adresu URL powyżej Asystent dodaje te argumenty w wiadomości 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',
}

Dzięki linkom do rozszerzonych elementów Asystenta możesz zwiększyć widoczność akcji w Twojej witrynie za pomocą pliku help.js. Użytkownicy mogą wypróbować Twoją akcję, a także połączyć swoje konto Google z Twoją usługą za pomocą funkcji łączenia kont.

Gdy użytkownik wejdzie na Twoją stronę, zobaczy przycisk „Wypróbuj z Asystentem Google”, który uruchomi proces tworzenia linku do Asystenta z elementami rozszerzonymi.

Włączenie łączenia kont dla akcji umożliwia użytkownikom jej dostęp do akcji na dowolnym urządzeniu z Asystentem. Dodatkowo użytkownicy mogą połączyć swoje konto z Twoją usługą ze swoim kontem Google, co pozwala korzystać z bardziej spersonalizowanych funkcji.

W przypadku łączenia kont linki Asystenta z elementami rozszerzonymi korzystają z adresu URL autoryzacji ustawionego w Twoim projekcie w Konsoli Actions. Więcej informacji znajdziesz w dokumentacji łączenia kont.

Wymagania wstępne

Aby korzystać z linków Asystenta rozszerzonych, musisz mieć:

Programowanie lokalne

Aby umieścić w swojej witrynie rozszerzony link do Asystenta, wykonaj te czynności:

  1. Dodaj do swojej strony tę bibliotekę JavaScript, zastępując <PROJECT_ID> identyfikatorem projektu Actions:

    <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
    </script>
    
  2. Dodaj poniższy tag HTML w dowolnym miejscu strony. Spowoduje to wczytanie wbudowanego przycisku „Wypróbuj z Asystentem Google”:

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

Proaktywne aktywatory

Jeśli chcesz, aby rozszerzony link do Asystenta uruchamiał się automatycznie, gdy użytkownicy po raz pierwszy odwiedzają Twoją stronę, użyj tagu <google-assistant-proactive-link>. Gdy zastosujesz ten tag, link aktywuje się bez kliknięcia użytkownika podczas pierwszej wizyty, a on sam nie kliknie wbudowanego przycisku.

  1. Dodaj id do tagu grupy połączeń Asystenta:

    <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. Umieść na swojej stronie tag <google-assistant-proactive-action-link> i ustaw jego atrybut groupId na 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>
    

Wdrażanie

Linki Asystenta z elementami rozszerzonymi działają tylko w Twoich domenach i zweryfikowanych w Google. W przypadku tworzenia lokalnego to wymaganie można obejść przez dostęp do projektu w Actions, zalogowanie się na konto Google i ustawienie parametru zapytania dev=true w tagu skryptu.

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

Aby wdrożyć akcję za pomocą rozszerzonych linków Asystenta:

  1. Zarejestruj domenę publiczną w konsoli Actions w sekcji Wdróż > Weryfikacja marki > Podłącz witrynę.
  2. Usuń parametr zapytania dev=true ze skryptu:

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

Ograniczenia i sprawdzone metody

Aby adres URL linku Asystenta można było rozpowszechniać i odwoływać się do niego poza katalogiem lub innymi usługami Google, obowiązują te ograniczenia i sprawdzone metody:

  • Nadal obsługuj wszystkie linki do Asystenta. Jeśli rozpowszechnisz link Asystenta, który później ulegnie awarii, Twój projekt Actions może zostać oznaczony jako niesprawny i usunięty.
  • Opublikowanie linku oznacza, że obsługujesz aktywatory z niezaufanych źródeł. W przypadku połączonych akcji musisz wyraźnie skonsultować się z użytkownikiem przed podjęciem jakichkolwiek działań. Na przykład akcja, która wyłącza urządzenie inteligentny dom, powinna zapytać użytkownika: „Czy na pewno chcesz wyłączyć usługę $applianceName?”

    W tym kontekście rzeczywiste działanie to dowolne działanie, które wpływa na usługi, dane, urządzenia, sieci, komputery lub interfejsy API użytkownika. Dotyczy to na przykład wysyłania e-maili, realizowania transakcji, zmiany stanu inteligentnego urządzenia domowego, utworzenia subskrypcji lub aktualizacji materiałów.