Intencje wbudowane (Dialogflow)

Intencja wbudowana to unikalny identyfikator, który informuje Asystenta Google, że akcja może zrealizować konkretną kategorię żądań użytkownika. Oto kilka przykładów zapytań użytkowników, które Asystent dopasowuje do intencji wbudowanych:

  • Wbudowana intencja „Zagraj w grę”: „OK Google, Zagraj w grę pamięciową”
  • Wbudowana intencja „Uzyskaj horoskop”: „OK Google. Sprawdź mój horoskop”

Podczas Wykrywanie akcji Asystent może używać metadanych dotyczących akcji, w tym określonych przez Ciebie intencji wbudowanych, aby polecać ją użytkownikom. Aby zminimalizować ilość przesyłanych danych w obie strony, Asystent próbuje też skanować parametry zapytań użytkownika i przekazywać je do akcji.

Pełną listę intencji wbudowanych obsługiwanych przez Asystenta, w tym ich parametry i przykładowe zapytania użytkowników, znajdziesz w dokumentacji intencji wbudowanych.

Integracja intencji wbudowanych

W zależności od tego, jak tworzysz akcję, możesz zintegrować intencje wbudowane na różne sposoby.

Dialogflow

Jeśli do tworzenia akcji używasz Dialogflow, możesz dołączyć w obrazie intencję wbudowaną z poziomu konsoli Dialogflow.

Aby dołączyć wbudowaną intencję przy użyciu Dialogflow, wykonaj te czynności:

  1. Otwórz konsolę Dialogflow, wybierz agenta i przejdź do ekranu Intents (Intencje).
  2. Utwórz lub wybierz intencję wyzwalaną przez agenta, gdy otrzyma konkretną intencję wbudowaną. Otwórz sekcję Zdarzenia i kliknij Dodaj zdarzenie.

    Rysunek 1. Dodawanie zdarzenia Dialogflow w konsoli Dialogflow.
  3. W polu Zdarzenia wpisz nazwę wbudowanego zdarzenia intencji (na przykład actions_intent_PLAY_GAME).

    Rysunek 2. Dołączenie wbudowanej intencji do agenta w konsoli Dialogflow.
  4. Kliknij Zapisz.

Actions SDK

Jeśli do tworzenia akcji używasz pakietu SDK Actions, musisz określić mapowanie między intencjami wbudowanymi a działaniami w pakiecie Action.

Aby dołączyć intencję wbudowaną za pomocą pakietu Actions SDK, wykonaj te czynności:

  1. Określ intencję wbudowaną w polu nazwy w definicji Działanie.
  2. Prześlij pakiet działań do projektu Actions za pomocą narzędzia gactions zgodnie z opisem w artykule Omówienie pakietu SDK Actions.

Na przykład ten fragment kodu pokazuje, jak dodać intencję wbudowaną CHECK_AIR_QUALITY:

{
   "actions":[
      {
         "description":"Default Welcome Intent",
         "name":"MAIN",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.MAIN"
         }
      },
      {
         "description":"Check Air Quality",
         "name":"CHECK_AIR_QUALITY",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.CHECK_AIR_QUALITY"
         }
      }
   ],
   "conversations":{
      "conversation_1":{
         "name":"conversation_1",
         "url":"https://example.com/fulfillment",
         "fulfillmentApiVersion":2
      }
   }
}

Obsługuj wbudowane parametry intencji

Gdy akcja jest wywoływana za pomocą intencji wbudowanej, realizacja może otrzymać dodatkowe parametry. Schemat intencji definiuje nazwy parametrów i ich typy jako typy podstawowe lub encje schema.org. Aby wyświetlić schemat intencji wbudowanych w akcje rozmowy, zapoznaj się z informacjami o intencjach wbudowanych.

Parametry intencji wbudowanych są opcjonalne. Asystent wypełnia parametry wartościami, jeśli można je wyodrębnić z wywołania intencji wbudowanej przez użytkownika.

Na przykład schemat intencji wbudowanej actions.intent.CHECK_AIR_QUALITY definiuje 4 parametry opcjonalne:

Nazwa parametru Typ
attributes Wartość ciągu znaków.
location Obiekt schema.org/Place.
temporalCoverage Obiekt schema.org/Duration.
timeIndicator EnumeratedDuration (rozszerzenie Google).

Poniższy fragment kodu zawiera przykładowy żądanie webhooka rozmowy (JSON), gdy użytkownik wywołuje akcję, mówiąc „Jaka będzie jutro jakość powietrza w San Francisco?”:

"inputs":[
      {
         "intent":"actions.intent.CHECK_AIR_QUALITY",
         "rawInputs":[
            {
               "inputType":"VOICE",
               "query":"what is the air quality in san francisco tomorrow"
            }
         ],
         "arguments":[
            {
               "name":"location",
               "structuredValue":{
                  "geo":{
                     "longitude":-122.41941550000001,
                     "latitude":37.7749295
                  },
                  "@context":"https://schema.org",
                  "@type":"Place",
                  "name":"san francisco"
               }
            },
            {
               "name":"temporalCoverage",
               "rawText":"2018-04-25",
               "textValue":"2018-04-25"
            }
         ]
      }
   ]

W tym przykładzie parametry przyjmują następujące wartości:

  • Parametr location zawiera wartość schema.org/Place dla „Kraków”.
  • Parametr temporalCoverage zawiera wartość schema.org/Duration dla jutrzejszej daty względem czasu wywołania.
  • Nie ma wartości parametrów attributes i timeIndicator, ponieważ wyrażenie wywołania użytkownika nie zawierało takich informacji.

Jeśli używasz biblioteki klienta Actions on Google dla Node.js, możesz pobrać wartości parametrów, tak jak w tym fragmencie:

app.intent('actions.intent.CHECK_AIR_QUALITY', (conv) => {
  const attributes = conv.arguments.get('attributes');
  const location = conv.arguments.get('location');
  const temporal_coverage = conv.arguments.get('temporalCoverage');
  Const time_indicator = conv.arguments.get('timeIndicator')

  // Your Action logic. If you need to use any of the parameter values,
  // you should check first that it is defined. Arguments.get returns
  // undefined if it can't find a value for a parameter.

});

Testowanie integracji z intencjami wbudowanymi

Aby przetestować integrację, wykonaj te czynności:

  1. Otwórz symulator Actions z włączoną akcją testową lub otwórz Asystenta na urządzeniu.
  2. Wypowiedz lub wpisz zapytanie powiązane z tą intencją wbudowaną. Na przykład: „Chcę w coś zagrać”.
  3. W wyświetlonym oknie wyboru aplikacji znajdź akcję.
  4. Wybierz aplikację, aby wysłać do niej intencję.
Rysunek 3. Okno wyboru działania wyświetlane
na podstawie wbudowanego wyrażenia intencji.
Rysunek 4. Wywoływanie akcji dołączonej do intencji wbudowanej.

Sprawdzone metody korzystania z intencji wbudowanych

Gdy korzystasz z intencji wbudowanych, postępuj zgodnie z tymi sprawdzonymi metodami:

  • Zmapuj wbudowane intencje na określone działania: gdy określona intencja wbudowana wywoła akcję, przekieruj użytkownika do jej konkretnej intencji i funkcji w jak najmniejszym zakresie. Jeśli np. akcja obsługuje intencję wbudowaną PLAY_GAME i otrzyma tę intencję, należy natychmiast przekierować użytkownika do jej funkcji gry. Nie pytaj użytkownika ponownie, czy chce zagrać w grę.
  • Obsługuj parametry intencji wbudowanych: korzystaj z wartości wbudowanych parametrów intencji, które Asystent wysyła do Twojej realizacji. Unikaj ponownego proszenia użytkownika o podanie tych wartości.