Czynności dotyczące rozmów zostały wycofane 13 czerwca 2023 r. Więcej informacji znajdziesz w artykule Wycofanie czynności konwersacyjnych.

Ta strona została przetłumaczona przez Cloud Translation API.

Switch to English

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.

Wygeneruj link dla Asystenta

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:

W Konsoli Actions kliknij Wdróż > Połączenia z Asystentem.
W polu Intencja wybierz intencję, dla której chcesz wygenerować link.
Włącz opcję Czy chcesz włączyć połączenie dla intencji intencji_name?.
(Opcjonalnie) W sekcji Parametry kampanii wpisz informacje, które chcesz dodatkowo rejestrować w linku jako parametry adresu URL.
(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.

Testuj linki 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:

Wygeneruj link do Asystenta w Konsoli Actions.
Wyślij do siebie link do Asystenta jako adres URL w e-mailu, wiadomości na czacie lub w innym formacie.
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.
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.

Parametry linku Asystenta

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

Specyfikacja adresu URL linku Asystenta

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.

Adresy URL linków Asystenta z intencjami wbudowanymi

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

Adresy URL linków Asystenta z zamiarami użytkownika

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',
}

Adresy URL linków Asystenta z parametrami UTM

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',
}

Rozszerzone linki Asystenta

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

Projekt Actions.
Link do Asystenta jest włączony do akcji.
(Opcjonalnie) Łączenie kont jest włączone dla akcji.

Programowanie lokalne

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

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>
```
Dodaj poniższy tag HTML w dowolnym miejscu strony. Spowoduje to wczytanie wbudowanego przycisku „Wypróbuj z Asystentem Google”:
```
<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>
```
Uwaga: jeśli użytkownik z Asystentem nie jest zalogowany, pierwszy link Asystenta spowoduje uruchomienie Asystenta lub przekierowanie użytkownika na stronę w katalogu Asystenta, do której należy akcja.

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.

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>

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:

Zarejestruj domenę publiczną w konsoli Actions w sekcji Wdróż > Weryfikacja marki > Podłącz witrynę.

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.