Tworzenie interaktywnego działania w obszarze roboczym dla Asystenta Google za pomocą Actions Builder

1. Przegląd

Actions on Google to platforma dla programistów, która umożliwia tworzenie oprogramowania rozszerzającego funkcjonalność Asystenta Google, wirtualnego asystenta osobistego Google, na ponad miliardzie urządzeń, w tym na inteligentnych głośnikach, telefonach, w samochodach, telewizorach, słuchawkach i innych. Użytkownicy rozmawiają z Asystentem Google, aby wykonywać różne czynności, np. kupować produkty spożywcze lub zamawiać przejazdy. Pełną listę dostępnych obecnie funkcji znajdziesz w katalogu akcji. Jako deweloper możesz używać Actions on Google do łatwego tworzenia i zarządzania atrakcyjnymi i przydatnymi interakcjami głosowymi między użytkownikami a Twoją usługą zewnętrzną.

Te ćwiczenia to zaawansowany moduł przeznaczony dla osób, które mają już pewne doświadczenie w tworzeniu działań na potrzeby Asystenta Google. Jeśli nie masz doświadczenia w tworzeniu Actions on Google, zapoznaj się z platformą, wykonując wprowadzające Codelabs ( poziom 1 i poziom 2). Te moduły przeprowadzą Cię przez szereg funkcji, które pomogą Ci rozszerzyć funkcjonalność działania i zwiększyć liczbę odbiorców.

W tym ćwiczeniu w Codelabs użyjesz interaktywnego płótna, czyli platformy opartej na Asystencie Google, aby dodać grę na pełnym ekranie do akcji dotyczącej rozmów. Gra to interaktywna aplikacja internetowa, którą Asystent wysyła użytkownikowi w odpowiedzi na jego zapytanie. Użytkownik może następnie grać w tę grę, używając poleceń głosowych lub tekstowych na inteligentnych wyświetlaczach i urządzeniach mobilnych z Androidem.

Zamiast tworzyć całą grę od podstaw, wdrażasz częściowo gotową grę o nazwie Snow Pal i dodajesz logikę gry w miarę postępów w tym samouczku. Snow Pal to odmiana tradycyjnej gry Wisielec. W grze wyświetla się kilka pustych miejsc reprezentujących słowo, a Ty zgadujesz litery, które Twoim zdaniem mogą się w nim znajdować. Z każdą błędną odpowiedzią Twój Śnieżny Przyjaciel będzie się trochę bardziej roztapiać. Wygrywasz, jeśli odgadniesz słowo, zanim Twój śnieżny przyjaciel całkowicie się roztopi.

Rysunek 1. częściowo ukończona gra Snow Pal,

Co utworzysz

W tym module utworzysz działanie, które korzysta z platformy Interactive Canvas. Twoja akcja będzie mieć te funkcje:

Gra słowna na pełnym ekranie, w którą użytkownicy mogą grać za pomocą głosu.
przycisk, który użytkownicy mogą nacisnąć, aby rozpocząć grę;
przycisk, który użytkownicy mogą nacisnąć, aby ponownie zagrać w grę;

Po ukończeniu tego ćwiczenia Twoja gotowa akcja będzie miała następujący przebieg rozmowy:

Asystent: Welcome to Snow Pal! Would you like to start playing the game?

Użytkownik: Yes.

Asystent: Try guessing a letter in the word or guessing the word.

Użytkownik: I guess the letter E.

Asystent: Let's see if your guess is there...E is right. Right on! Good guess.

Użytkownik zgaduje kolejne litery lub całe słowo, dopóki gra się nie skończy.

Czego się nauczysz

Jak tworzyć i wdrażać działania na platformie Interactive Canvas
Jak aktualizować grę słowną na podstawie głosu i danych wejściowych użytkownika
Przekazywanie danych do aplikacji internetowej za pomocą różnych metod
Jak debugować działanie Interactive Canvas

Czego potrzebujesz

Wymagania wstępne dotyczące tego laboratorium obejmują:

przeglądarka internetowa, np. Google Chrome;
wybrane środowisko IDE lub edytor tekstu;
Node.js, npm i git zainstalowane na komputerze.

Aby zrozumieć kod użyty w tych ćwiczeniach z programowania, zalecamy znajomość JavaScript (ES6).

Opcjonalnie: pobieranie pełnego przykładowego kodu

W tym ćwiczeniu utworzysz przykładową aplikację krok po kroku, zaczynając od niepełnej wersji. Jeśli wolisz, możesz też pobrać gotowy przykład z repozytorium GitHub.

2. Wprowadzenie do Interactive Canvas

Interactive Canvas to platforma oparta na Asystencie Google, która umożliwia dodawanie do akcji konwersacyjnych wizualizacji i animacji na pełnym ekranie.

Akcja korzystająca z platformy Interactive Canvas działa podobnie do zwykłej akcji dotyczącej rozmów. Działanie Interactive Canvas ma jednak dodatkową możliwość wysyłania odpowiedzi na urządzenie, które otwiera aplikację internetową na pełnym ekranie.

Użytkownik przekazuje dane wejściowe do aplikacji internetowej za pomocą głosu lub dotyku, dopóki rozmowa się nie zakończy.

Rysunek 2. Akcja utworzona za pomocą platformy Interactive Canvas.

W tym laboratorium projekt jest podzielony na 3 główne części:

Aplikacja internetowa: pliki aplikacji internetowej zawierają kod elementów wizualnych i animacji aplikacji, a także logikę aktualizowania aplikacji na podstawie danych wejściowych użytkownika.
Akcja konwersacyjna: akcja konwersacyjna zawiera logikę rozmowy, która rozpoznaje, przetwarza i odpowiada na dane wejściowe użytkownika.
Webhook: webhook obsługuje logikę gry. W tym samouczku możesz traktować webhook jako serwer gry.

W każdej sekcji tego samouczka modyfikujesz aplikację internetową, akcję konwersacyjną i webhooka, aby dodać funkcje do akcji Interactive Canvas.

Ogólnie działanie konwersacyjne, webhook i aplikacja internetowa w działaniu Snow Pal działają w ten sposób:

Aplikacja konwersacyjna prosi użytkownika o zgadnięcie litery w słowie lub całego słowa.
Użytkownik mówi „I guess the letter i” (Zgaduję literę i) do aplikacji internetowej Snow Pal na wyświetlaczu inteligentnym.
Dane wejściowe użytkownika są kierowane do akcji dotyczącej rozmów, która jest zdefiniowana w projekcie w narzędziu Actions Builder lub pakiecie SDK Actions.
Działanie konwersacyjne przetwarza dane wejściowe użytkownika i w zależności od nich wywołuje logikę w webhooku, która aktualizuje aplikację internetową, lub wysyła metadane, aby bezpośrednio zaktualizować aplikację internetową.
Aplikacja internetowa aktualizuje się, aby pokazać, gdzie w słowie znajduje się litera, a użytkownik jest proszony o ponowne zgadnięcie.

Więcej informacji o działaniu Interactive Canvas znajdziesz w sekcji Poznaj infrastrukturę Interactive Canvas. Teraz, gdy znasz już podstawy, możesz zacząć konfigurować środowisko na potrzeby tego ćwiczenia.

3. Skonfiguruj

Sprawdzanie ustawień uprawnień Google

Aby przetestować działanie utworzone w tym module, musisz włączyć niezbędne uprawnienia, aby symulator w konsoli Actions mógł uzyskać do niego dostęp. Aby włączyć uprawnienia, wykonaj te czynności:

Otwórz Zarządzanie aktywnością.
W razie potrzeby zaloguj się na konto Google.
Włącz te uprawnienia:

Aktywność w internecie i aplikacjach
W sekcji Aktywność w internecie i aplikacjach zaznacz pole Uwzględnij historię Chrome i aktywność na stronach, urządzeniach i w aplikacjach, które używają usług Google.

Instalowanie interfejsu wiersza poleceń gactions

W tym laboratorium kodowym użyjesz narzędzia interfejsu wiersza poleceń gactions do synchronizowania projektu działań między konsolą Actions a lokalnym systemem plików.

Aby zainstalować gactions CLI, postępuj zgodnie z instrukcjami w sekcji Instalowanie narzędzia wiersza poleceń gactions.

Instalowanie interfejsu wiersza poleceń Firebase

Interfejs wiersza poleceń Firebase umożliwia wdrażanie projektu działania w Cloud Functions i hostowanie aplikacji internetowej.

W tym laboratorium używamy npm do instalowania wiersza poleceń Firebase. Zainstaluj npm, który zwykle jest dostarczany z Node.js.

Aby zainstalować lub uaktualnić interfejs CLI, otwórz terminal i uruchom to polecenie: npm

npm install -g firebase-tools

Aby sprawdzić, czy interfejs CLI został zainstalowany prawidłowo, uruchom to polecenie:

firebase --version

Sprawdź, czy wersja wiersza poleceń Firebase to 8 lub nowsza, aby mieć dostęp do wszystkich najnowszych funkcji wymaganych w Cloud Functions. Jeśli nie, uruchom npm install -g firebase-tools, aby przeprowadzić uaktualnienie.

Aby zalogować się w Firebase, uruchom to polecenie:

firebase login

Podczas logowania się w Firebase używaj tego samego konta Google, którego użyto do utworzenia projektu działań.

Klonowanie repozytorium

W tej sekcji sklonujesz pliki potrzebne do tego ćwiczenia. Aby uzyskać te pliki, wykonaj te czynności:

Otwórz terminal i przejdź do katalogu, w którym zwykle przechowujesz projekty związane z kodowaniem. Jeśli nie masz takiego katalogu, przejdź do katalogu domowego.
Aby sklonować to repozytorium, uruchom w terminalu to polecenie:

git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs

Otwórz katalog start/. To repozytorium zawiera te ważne katalogi, z którymi będziesz pracować:

public/: ten katalog zawiera kod HTML, CSS i JavaScript aplikacji internetowej.
sdk/custom/: ten katalog zawiera logikę Twojej akcji konwersacyjnej (sceny, intencje i typy).
sdk/webhooks/: Ten katalog to webhook, który zawiera logikę gry.

Rysunek 3. Struktura start kodu katalogu.

4. Konfigurowanie projektu w Actions

W tej sekcji utworzysz i skonfigurujesz projekt Actions, wypchniesz kod ze sklonowanego repozytorium do konsoli Actions za pomocą interfejsu gactions CLI oraz wdrożysz aplikację internetową i webhook.

Tworzenie projektu w Actions

Projekt w Actions jest kontenerem dla Twojej akcji. Aby utworzyć projekt działań na potrzeby tego laboratorium, wykonaj te czynności:

Otwórz konsolę Actions.
Kliknij Nowy projekt.
Wpisz nazwę projektu, np. canvas-codelab. Ta nazwa jest przeznaczona do użytku wewnętrznego. Później możesz ustawić zewnętrzną nazwę projektu.

Kliknij Utwórz projekt.
Na ekranie Jakiego rodzaju działanie chcesz utworzyć? wybierz kartę Gra.
Kliknij Dalej.
Wybierz kartę Pusty projekt.
Kliknij Rozpocznij tworzenie.

Zapisywanie identyfikatora projektu dla działania

Identyfikator projektu to unikalny identyfikator Twojej działania. Identyfikator projektu będzie potrzebny w kilku krokach tego ćwiczenia.

Aby pobrać identyfikator projektu, wykonaj te czynności:

W konsoli Czynności kliknij 3 kropki w pionie > Ustawienia projektu.

Skopiuj identyfikator projektu.

Powiązywanie konta rozliczeniowego

Aby wdrożyć realizację w dalszej części tego samouczka za pomocą Cloud Functions, musisz powiązać konto rozliczeniowe z projektem w Google Cloud. Jeśli masz już konto rozliczeniowe, możesz pominąć te kroki.

Aby powiązać konto rozliczeniowe z projektem, wykonaj te czynności:

Otwórz stronę rozliczeń Google Cloud Platform.
Kliknij Dodaj konto rozliczeniowe lub Utwórz konto.
Podaj dane karty.
Kliknij Rozpocznij bezpłatny okres próbny lub Prześlij i włącz płatności.
Otwórz stronę rozliczeń Google Cloud.
Kliknij kartę Moje projekty.
Kliknij 3 kropki > Zmień rozliczenia.
W menu wybierz skonfigurowane konto rozliczeniowe.
Kliknij Ustaw konto.

Aby uniknąć obciążenia konta opłatami, wykonaj czynności opisane w sekcji Zwalnianie miejsca w projekcie.

Wdrażanie aplikacji internetowej

W tej sekcji wdrożysz aplikację internetową (grę Snow Pal) za pomocą wiersza poleceń Firebase. Po wdrożeniu możesz pobrać adres URL aplikacji internetowej i sprawdzić, jak gra wygląda w przeglądarce.

Aby wdrożyć aplikację internetową, wykonaj te czynności:

W terminalu przejdź do katalogu start/.
Uruchom to polecenie, zastępując {PROJECT_ID} identyfikatorem projektu:

firebase deploy --project {PROJECT_ID} --only hosting

Po kilku minutach powinna pojawić się ikona "Deploy complete!", co oznacza, że aplikacja internetowa Snow Pal została pomyślnie wdrożona w Firebase.

Aby wyświetlić grę Snow Pal w przeglądarce, wykonaj te czynności:

Pobierz adres URL hostingu podany w danych wyjściowych terminala. Adres URL powinien mieć format https://<PROJECT_ID>.web.app

Wklej adres URL w przeglądarce. Powinien pojawić się ekran początkowy gry Snow Pal z przyciskiem Rozpocznij grę:

Dodawanie adresu URL aplikacji internetowej i identyfikatora projektu do projektu w Actions

Następnie dodaj adres URL aplikacji internetowej i identyfikator projektu do pliku actions.intent.MAIN.yaml. Dodanie adresu URL aplikacji internetowej informuje działanie konwersacyjne, na który adres URL ma wysyłać dane, a dodanie identyfikatora projektu w settings.yaml umożliwia przesyłanie pobranych plików do właściwego projektu w konsoli Actions.

Aby dodać adres URL aplikacji internetowej i identyfikator projektu:

Otwórz plik start/sdk/custom/global/actions.intent.MAIN.yaml w edytorze tekstu.
W polu URL zastąp ciąg zastępczy adresem URL aplikacji internetowej.
Otwórz plik start/sdk/settings/settings.yaml w edytorze tekstu.
W polu projectId zastąp ciąg znaków identyfikatorem projektu.

Przesyłanie projektu do Konsoli Actions

Aby zaktualizować Konsolę Actions za pomocą projektu lokalnego, musisz przesłać projekt Actions do Konsoli Actions. W tym celu wykonaj następujące czynności:

Przejdź do katalogu sdk:

cd sdk/

Aby skopiować konfigurację lokalnego systemu plików do konsoli Actions, uruchom to polecenie:

gactions push

Wdrażanie webhooka

Po uruchomieniu polecenia gactions push zaimportowano początkowy kod webhooka do konsoli Actions. W pozostałej części tego laboratorium możesz edytować kod webhooka w konsoli Actions. W tym momencie możesz wdrożyć webhooka z konsoli Actions.

Aby wdrożyć webhooka, wykonaj te czynności:

W Konsoli Actions na pasku nawigacyjnym kliknij Rozwijaj.
Na pasku nawigacyjnym kliknij kartę Webhook.
Kliknij Wdróż realizację.

Udostępnienie i wdrożenie realizacji przez Cloud Functions może potrwać kilka minut. Powinien zostać wyświetlony komunikat Trwa wdrażanie funkcji w Cloud Functions.... Gdy kod zostanie wdrożony, komunikat zmieni się na Wdrożenie funkcji w Cloud Functions jest aktualne.

Testowanie w symulatorze

Na tym etapie działanie jest połączone z aplikacją internetową. Możesz użyć symulatora konsoli Actions, aby sprawdzić, czy aplikacja internetowa pojawia się po wywołaniu działania.

Aby przetestować działanie, wykonaj te czynności:

Na pasku nawigacyjnym konsoli Actions kliknij Testuj.
Wpisz Talk to Snow Pal sample w polu Input (Dane wejściowe) i naciśnij Enter.
Wpisz Yes w polu Input (Dane wejściowe) i naciśnij Enter. Możesz też kliknąć Rozpocznij grę.

Nie masz jeszcze skonfigurowanej logiki zgadywania litery lub słowa, więc jeśli zgadniesz słowo lub literę, otrzymasz odpowiedź „...Nieprawidłowo. Próbuj dalej. Wygląda na to, że musimy dodać więcej funkcji, aby to działało prawidłowo”.

5. Poznaj infrastrukturę Interactive Canvas

W tym projekcie funkcjonalność jest podzielona na 3 główne komponenty: działanie konwersacyjne, aplikację internetową i webhook. Pamiętaj, że jest to jeden z modeli konfiguracji działania. Został on tak zorganizowany, aby podkreślić główną funkcjonalność interaktywnego płótna.

W kolejnych sekcjach znajdziesz więcej informacji o tym, jak działanie konwersacyjne, webhook i aplikacja internetowa współpracują ze sobą, a także o innych ważnych elementach Interactive Canvas.

Akcja dotycząca rozmowy

Komponent działania konwersacyjnego w Twoim działaniu odpowiada za rozpoznawanie danych wejściowych użytkownika, ich przetwarzanie i wysyłanie do odpowiedniej sceny, w której tworzona jest odpowiedź dla użytkownika. Jeśli na przykład użytkownik powie „Zgaduję literę e” w grze Snow Pal, Twoja akcja konwersacyjna wyodrębni literę jako parametr intencji i przekaże ją do odpowiedniej logiki gry, która określi, czy zgadywanie jest prawidłowe, i odpowiednio zaktualizuje aplikację internetową. Możesz wyświetlać i modyfikować tę logikę konwersacyjną w narzędziu Actions Builder, czyli internetowym środowisku IDE w konsoli Actions. Na zrzucie ekranu poniżej widać fragment działania konwersacyjnego w narzędziu Actions Builder:

Rysunek 4. Wizualizacja Main invocation w kreatorze działań.

Ten zrzut ekranu pokazuje Main invocation Twojej akcji, która jest dopasowywana, gdy użytkownicy wypowiadają frazę taką jak „OK Google, porozmawiaj z wersją demonstracyjną Snow Pal”. Gdy użytkownik wywoła Twoją czynność, Main invocation wyśle prompt z odpowiedzią canvas, która zawiera adres URL Twojej aplikacji internetowej.

Pierwsza odpowiedź canvas w Twojej czynności musi zawierać adres URL aplikacji internetowej. Ta odpowiedź informuje Asystenta, że ma wyświetlić aplikację internetową pod tym adresem na urządzeniu użytkownika. Dodatkowe odpowiedzi canvas w Kreatorze działań mogą zawierać pole send_state_data_to_canvas_app ustawione na true. To pole wysyła nazwę intencji i wartości parametrów do aplikacji internetowej, gdy intencja zostanie dopasowana, a aplikacja internetowa aktualizuje się na podstawie tych danych z danych wejściowych użytkownika.

Webhook

W tym samouczku webhook zawiera logikę gry (możesz traktować go jako serwer gry). Logika gry obejmuje elementy takie jak określanie, czy odpowiedź użytkownika jest prawidłowa, czy nie, lub czy użytkownik wygrał, czy przegrał, oraz tworzenie odpowiedzi na podstawie wyniku. Webhooka możesz zmodyfikować w narzędziu Actions Builder.

Gdy działanie musi wykonać logikę gry, narzędzie Actions Builder wywołuje webhooka. Na przykład intencja guess w scenie Game wywołuje webhooka do modułu obsługi guess, który następnie wykonuje logikę, aby określić, czy odpowiedź użytkownika jest prawidłowa. Webhook może zawierać Canvas odpowiedzi w elementach obsługi, które są mapowane na pliki aplikacji internetowej, i odpowiednio aktualizować sieć.

Aplikacja internetowa

Rysunek 5. Graficzna prezentacja interakcji między działaniem konwersacyjnym, webhookiem i aplikacją internetową w działaniu Interactive Canvas.

Pliki aplikacji internetowej zawierają kod elementów wizualnych i animacji aplikacji, a także logikę aktualizowania aplikacji na podstawie danych wejściowych użytkownika. Pliki aplikacji internetowej możesz modyfikować w edytorze tekstu, a zmiany wdrażać za pomocą interfejsu wiersza poleceń Firebase.

Komunikacja między akcją dotyczącą rozmów a aplikacją internetową

Musisz włączyć komunikację między działaniem konwersacyjnym a aplikacją internetową, aby aplikacja internetowa mogła się aktualizować na podstawie danych wejściowych użytkownika. Jeśli np. użytkownik powie „Zgaduję literę f”,

Działanie konwersacyjne musi przekazać aplikacji internetowej literę f, aby mogła ona odpowiednio się zaktualizować. Aby przekazać dane wejściowe użytkownika z działania konwersacyjnego do aplikacji internetowej, musisz wczytać interfejs Interactive Canvas API.

Skrypt tego interfejsu API jest zawarty w pliku /public/index.html, który jest głównym plikiem HTML gry Snow Pal. Ten plik określa wygląd interfejsu i sposób jego wczytywania w kilku skryptach:

index.html

<!-- Load Assistant Interactive Canvas API -->
 <script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>

Aby zaktualizować aplikację internetową na podstawie danych wprowadzonych przez użytkownika, musisz też zarejestrować i skonfigurować wywołania zwrotne w pliku aplikacji internetowej. Wywołania zwrotne umożliwiają aplikacji internetowej odpowiadanie na informacje lub żądania z działania konwersacyjnego.

W /public/js/action.js jest wstępnie skonfigurowana klasa o nazwie Action, która służy do deklarowania i rejestrowania wywołań zwrotnych. Klasa Action jest otoką interfejsu Interactive Canvas API. Gdy aplikacja internetowa zostanie utworzona za pomocą funkcji create() w scene.js, utworzona zostanie nowa instancja Action i wywołana zostanie funkcja setCallbacks(), jak pokazano w tym fragmencie kodu:

scene.js

// Set Assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register Assistant Action callbacks.
this.assistant.setCallbacks();

Funkcja setCallbacks() jest zdefiniowana w klasie Action modułu /public/js/action.js. Ta funkcja deklaruje wywołania zwrotne i rejestruje je w interfejsie Interactive Canvas API podczas tworzenia gry:

  setCallbacks() {
    // Declare the Interactive Canvas Action callbacks.
    const callbacks = {
      onUpdate: (data) => {
     ...
    // Called by the Interactive Canvas web app once web app has loaded to
    // register callbacks.
    this.canvas.ready(callbacks);
  }

Funkcja setCallbacks() deklaruje wywołanie zwrotne onUpdate(), które jest wywoływane za każdym razem, gdy wysyłasz odpowiedź Canvas.

W następnej sekcji opisujemy, jak skonfigurowano konkretny kod tego projektu, aby przekazywać dane z działania konwersacyjnego do aplikacji internetowej.

Aktualizowanie aplikacji internetowej na podstawie danych wprowadzonych przez użytkownika

W tym ćwiczeniu użyjesz mapy poleceń, aby zaktualizować aplikację internetową na podstawie danych wprowadzonych przez użytkownika. Na przykład, gdy w scenie Welcome zostanie dopasowany zamiar start_game, do aplikacji internetowej zostanie wysłana odpowiedź canvas zawarta w prompcie. onUpdate() analizuje metadane z odpowiedzi canvas i wywołuje polecenie START_GAME, które z kolei wywołuje funkcję start() w scene.js i aktualizuje aplikację internetową, aby rozpocząć nową sesję gry.

Funkcja start() w scene.js wywołuje też funkcję updateCanvasState(), która używa metody setCanvasState() do dodawania danych o stanie, do których webhook może uzyskać dostęp.

Metoda updateCanvasState() jest wywoływana na końcu każdego polecenia (będziesz dodawać te polecenia w trakcie tego samouczka) i aktualizuje stan aplikacji internetowej. Za każdym razem, gdy wywoływana jest funkcja updateCanvasState(), wartości displayedWord i incorrectGuesses są aktualizowane na podstawie bieżącego stanu:

scene.js

...
  updateCanvasState() {
    window.interactiveCanvas.setCanvasState({
      correctWord: this.word.text,
      displayedWord: this.word.displayText.text,
      incorrectGuesses: this.incorrectGuesses,
    });

Zaktualizowany stan jest następnie dostępny w kolejnej turze rozmowy. Dostęp do tego stanu w webhooku możesz uzyskać za pomocą parametru conv.context.canvas.state, jak pokazano w tym fragmencie kodu:

index.js

...
  let displayedWord = conv.context.canvas.state.displayedWord;
...

6. Dodawanie funkcji zgadywania

W tej sekcji dodasz do akcji funkcję guess, która umożliwia użytkownikowi zgadywanie liter w słowie lub całego słowa.

Akcja dotycząca rozmowy

W sekcji Testuj w symulatorze pojawiła się odpowiedź „Wygląda na to, że musimy dodać więcej funkcji, aby to działało prawidłowo”. Teraz możesz usunąć ten prompt w konsoli Actions, aby wywoływać tylko webhook (w scenie Game intencja guess jest już skonfigurowana tak, aby po dopasowaniu wywoływać webhook).

Aby usunąć statyczny prompt, gdy zostanie dopasowany zamiar guess, wykonaj te czynności:

W konsoli Actions kliknij Sceny na pasku nawigacyjnym.
Kliknij Gra, aby przejść do sceny Game.
W sekcji Obsługa intencji użytkownika kliknij Gdy przypuszczenie jest zgodne. Odznacz Wysyłaj prompty, aby usunąć prompta.
Kliknij Zapisz.

Webhook

W tej sekcji zaktualizujesz webhooka o logikę, która mapuje prawidłową lub nieprawidłową odpowiedź użytkownika na logikę w pliku aplikacji internetowej, która następnie odpowiednio aktualizuje aplikację internetową. guess Obsługa intencji jest już skonfigurowana w webhooku, więc wystarczy, że dodasz Canvas odpowiedzi na tę intencję, aby wywołać logikę, która aktualizuje aplikację internetową.

Aby zaktualizować webhooka, wykonaj te czynności:

W konsoli Actions na pasku nawigacyjnym kliknij Webhook.
Dodaj ten kod do pliku index.js pod modułem obsługi guess:

index.js (sekcja A):

// Add Section A `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'CORRECT_ANSWER',
    displayedWord: displayedWord
  },
}));

index.js (sekcja B):

// Add Section B `conv.add(new Canvas({` content here.
conv.add(new Canvas({
  data: {
    command: 'INCORRECT_ANSWER',
  },
}));

Kliknij Zapisz realizację.
Kliknij Wdróż realizację. Po zakończeniu wdrażania pojawi się komunikat Wdrożenie funkcji Cloud Function jest aktualne.

Aplikacja internetowa

Możesz teraz skonfigurować aplikację internetową tak, aby obsługiwała polecenia CORRECT_ANSWER i INCORRECT_ANSWER.

Otwórz public/js/action.js w edytorze tekstu.
Zaktualizuj aplikację internetową, aby obsługiwała polecenia CORRECT_ANSWER i INCORRECT_ANSWER:

action.js (sekcja C):

// Add Section C `CORRECT_ANSWER: (params) => {` content here.
      CORRECT_ANSWER: (params) => {
        this.gameScene.correctAnswer(params);
      },
      INCORRECT_ANSWER: (params) => {
        this.gameScene.incorrectAnswer();
      },

Aby zaktualizować aplikację internetową, uruchom to polecenie:

firebase deploy --project {PROJECT_ID} --only hosting

Testowanie działania w symulatorze

Na tym etapie Twoja akcja może rozpoznać, czy odpowiedź jest prawidłowa, i odpowiednio zaktualizować aplikację internetową.

Aby przetestować działanie, wykonaj te czynności:

Na pasku nawigacyjnym kliknij Test.
Wpisz Talk to Snow Pal sample w polu Input (Dane wejściowe) i naciśnij Enter.
Wpisz Yes w polu Input (Dane wejściowe) i naciśnij Enter. Możesz też kliknąć przycisk Tak.
Wpisz literę, którą chcesz odgadnąć, w polu Input i naciśnij Enter.

Zrozumienie kodu

W poprzedniej sekcji dodaliśmy kod, który umożliwia użytkownikom zgadywanie liter w grze i wyświetlanie tych zgadywań w słowie lub w Snow Pal. Ogólnie rzecz biorąc, wywołanie webhooka w Kreatorze działań następuje po dopasowaniu guess intencji. Przekazuje ono dane do aplikacji internetowej, aby ją odpowiednio zaktualizować. Jeśli np. użytkownik odgadnie literę w grze Snow Pal, która występuje w słowie, aplikacja internetowa zaktualizuje się, aby wyświetlić literę we właściwym miejscu w słowie.

W przypadku działań korzystających z Interactive Canvas ogólny przepływ danych z webhooka do aplikacji internetowej jest następujący:

Dane wejściowe użytkownika pasują do intencji, która zawiera odpowiedź Canvas.
Działanie konwersacyjne lub webhook wysyła Canvas odpowiedź, która wywołuje wywołanie zwrotne onUpdate().
onUpdate() Wywołanie zwrotne jest powiązane z niestandardową logiką, która odpowiednio aktualizuje aplikację internetową.

W tym konkretnym projekcie kod działa w ten sposób:

Gdy użytkownik ma zamiar guess, Actions Builder wyodrębnia literę z danych wejściowych użytkownika jako parametr.
Narzędzie Actions Builder wywołuje w webhooku funkcję obsługi guess, która zawiera logikę określającą, czy zgadywana przez użytkownika litera występuje w słowie.
Procedura obsługi guess zawiera 2 odpowiedzi Canvas – jedną, która jest wykonywana, gdy litera jest prawidłowa, i drugą, która jest wykonywana, gdy litera jest nieprawidłowa. Każda odpowiedź Canvas przekazuje do aplikacji internetowej odpowiednie dane (polecenie CORRECT_ANSWER lub INCORRECT_ANSWER).
Dane zawarte w polu data odpowiedzi Canvas są przekazywane do metody onUpdate() w action.js. onUpdate() wywołuje odpowiednie polecenie w mapowaniu poleceń w scene.js.
Mapa poleceń jest mapowana na funkcje correctAnswer() i incorrectAnswer() w scene.js. Te funkcje odpowiednio aktualizują aplikację internetową, aby odzwierciedlać zgadywanie użytkownika, i wywołują funkcję setCanvasState(), aby wysyłać dane o stanie z aplikacji internetowej do webhooka.

7. Dodawanie funkcji wygranej/przegranej

W tej sekcji dodasz do działania funkcje wygranej i przegranej, w tym logikę, która określa, czy użytkownik wygrał czy przegrał, oraz logikę aktualizującą obraz aplikacji internetowej na podstawie wyniku użytkownika.

Akcja dotycząca rozmowy

Funkcja obsługująca wygraną lub przegraną użytkownika zostanie skonfigurowana w intencji guess, więc nie musisz przeprowadzać żadnej dodatkowej konfiguracji w Actions Builder.

Webhook

W tej sekcji zaktualizujesz webhooka o logikę, która obsługuje sytuacje, w których użytkownik wygrał lub przegrał grę, i odpowiada logice aplikacji internetowej, która aktualizuje grę o odpowiedni ekran wygranej lub przegranej.

Aby zaktualizować webhooka, wykonaj te czynności:

W konsoli Actions na pasku nawigacyjnym kliknij Webhook.
Dodaj ten kod do pliku index.js pod modułem obsługi guess:

index.js (sekcja D):

// Add Section D `if (userHasWon)` content here.
    if (userHasWon) {
      conv.add(`<speak>Let's see if your guess is there...<break
        time='2500ms'/> ${guess} is right. That spells ${correctWord}!  
        ${randomArrayItem(WIN_RESPONSES)}</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'WIN_GAME',
          displayedWord: displayedWord
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (sekcja E):

// Add Section E `}` here.
}

index.js (sekcja F):

// Add Section F `Check if the user has exceeded the maximum` content here.
// Check if the user has exceeded the maximum amount of max guesses allowed.
    const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
    if (userHasLost) {
      conv.add(`<speak>Let's see if your guess is there...<break
      time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'LOSE_GAME',
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (sekcja G):

// Add Section G `}` here.
}

Kliknij Zapisz realizację.
Kliknij Wdróż realizację. Po zakończeniu wdrażania pojawi się komunikat Wdrożenie funkcji Cloud Function jest aktualne.

W tym miejscu dodano 2 Canvas odpowiedzi z poleceniami WIN_GAME i LOSE_GAME, które będą obsługiwać sytuacje, gdy użytkownicy wygrają lub przegrają grę. W następnej sekcji dodasz funkcję, która aktualizuje aplikację internetową w zależności od tego, czy użytkownik wygrał, czy przegrał.

Aplikacja internetowa

Możesz teraz skonfigurować aplikację internetową tak, aby aktualizowała się w zależności od tego, czy użytkownik wygrał czy przegrał. Aby zaktualizować aplikację internetową, wykonaj te czynności:

Otwórz public/js/action.js w edytorze tekstu.
Zaktualizuj aplikację internetową, aby obsługiwała polecenia WIN_GAME i LOSE_GAME:

action.js (sekcja H):

// Add Section H `WIN_GAME: (params) => {` content here.
      WIN_GAME: (params) => {
        this.gameScene.winGame(params);
      },
      LOSE_GAME: (params) => {
        this.gameScene.loseGame();
      },

Aby zaktualizować aplikację internetową, uruchom to polecenie:

firebase deploy --project {PROJECT_ID} --only hosting

Testowanie działania w symulatorze

Na tym etapie Twoja akcja może obsługiwać sytuacje, w których użytkownik wygrywa lub przegrywa, i wyświetlać odpowiedni ekran dla każdego wyniku.

Aby przetestować działanie, wykonaj te czynności:

Na pasku nawigacyjnym konsoli Actions kliknij Testuj.
Wpisz Talk to Snow Pal sample w polu Input (Dane wejściowe) i naciśnij Enter.
Wpisz Yes w polu Input (Dane wejściowe) i naciśnij Enter. Możesz też kliknąć przycisk Rozpocznij grę.
Odgaduj litery i słowa, aż wygrasz lub przegrasz.

Jeśli poprosisz o ponowne odtworzenie, otrzymasz komunikat, że niezbędna funkcja nie została jeszcze dodana. W kolejnej sekcji dodasz tę funkcję.

Zrozumienie kodu

Funkcja wygranej i przegranej działa tak samo jak funkcja zgadywania – użytkownik dopasowuje intencję guess, a webhook ocenia jego odpowiedź. Jeśli użytkownik odgadnie liczbę, kod sprawdzi, czy wygrał. Jeśli tak, do aplikacji internetowej zostanie wysłane polecenie WIN_GAME. Jeśli użytkownik się pomyli, kod sprawdzi, czy przegrał. Jeśli tak, do aplikacji internetowej zostanie wysłane polecenie LOSE_GAME. Te polecenia wywołują funkcje winGame() i loseGame() w scene.js, które aktualizują aplikację internetową, aby wyświetlić ekran zwycięstwa lub porażki, oraz aktualizują stan gry.

8. Dodawanie funkcji ponownego odtwarzania

W tej sekcji dodasz funkcję, która umożliwi użytkownikowi rozpoczęcie nowej gry przez wypowiedzenie „Zagraj jeszcze raz” lub kliknięcie przycisku Zagraj jeszcze raz w aplikacji internetowej. W Actions Builder zmodyfikuj intencję play_again, aby wysyłać odpowiedź canvas, która odpowiednio aktualizuje aplikację internetową, i dodaj logikę, która wywołuje intencję play_again, gdy użytkownik kliknie przycisk Zagraj jeszcze raz.

Akcja dotycząca rozmowy

Podczas testowania działania w poprzedniej sekcji, jeśli spróbujesz ponownie zagrać w grę, pojawi się ten komunikat: „To świetnie, ale tę funkcję dodamy w późniejszej sekcji. Na razie po prostu zresetuj działanie”. Możesz teraz usunąć ten prompt i zastąpić go promptem, który odpowiada użytkownikowi, gdy poprosi o kolejną grę („OK, oto kolejna gra!”), i zawiera odpowiedź canvas, która uruchamia nową grę w aplikacji internetowej.

Aby zaktualizować prompt, gdy użytkownik chce zagrać ponownie:

W konsoli Actions kliknij menu Scena.
Kliknij scenę Gra.
W sekcji Obsługa intencji użytkownika kliknij Gdy zostanie dopasowana intencja play_again.
Zastąp prompt tym tekstem:

candidates:
  - first_simple:
      variants:
        - speech: 'Okay, here''s another game!' 
    canvas:
      sendStateDataToCanvasApp: true

Kliknij Zapisz.

Webhook

W tym laboratorium kodowania webhook zarządza logiką gry. Funkcja ponownego odtwarzania nie wymaga żadnej weryfikacji logicznej, więc nie musisz wywoływać webhooka. Zamiast tego możesz wysłać canvasodpowiedź bezpośrednio z Actions Builder, aby przekazać niezbędne dane do aplikacji internetowej (skonfigurowano to w poprzedniej sekcji).

Aplikacja internetowa

Możesz teraz modyfikować pliki aplikacji internetowej, aby odpowiednio je aktualizować, gdy użytkownik poprosi o ponowne odtworzenie. Aby dodać tę funkcję, wykonaj te czynności:

Otwórz public/js/action.js w edytorze tekstu.
Zaktualizuj aplikację internetową, aby obsługiwała polecenie PLAY_AGAIN:

action.js (sekcja I):

// Add Section I `PLAY_AGAIN: (params) => {` content here.
      PLAY_AGAIN: (params) => {
        this.gameScene.start();
      },

Otwórz public/js/scene.js w edytorze tekstu.
Zaktualizuj aplikację internetową, aby rozpoczynała nową sesję gry, gdy użytkownik kliknie przycisk „Zagraj jeszcze raz”:

scene.js (sekcja J):

// Add Section J `sendTextQuery` content here.
     window.interactiveCanvas.sendTextQuery('Play again');

Aby zaktualizować aplikację internetową, uruchom to polecenie:

firebase deploy --project {PROJECT_ID} --only hosting

Testowanie działania w symulatorze

Twoja czynność może teraz rozpocząć nową sesję gry, gdy użytkownik powie „Zagraj jeszcze raz” lub kliknie przycisk Zagraj jeszcze raz.

Aby przetestować działanie, wykonaj te czynności:

Na pasku nawigacyjnym kliknij Test.
Wpisz Talk to Snow Pal sample w polu Input (Dane wejściowe) i naciśnij Enter.
Wpisz Yes w polu Input (Dane wejściowe) i naciśnij Enter. Możesz też kliknąć przycisk Rozpocznij grę.
Odgaduj litery i słowa, aż wygrasz lub przegrasz.
Wpisz Play again w polu Input (Dane wejściowe) i naciśnij Enter. Możesz też kliknąć przycisk Zagraj ponownie.

Zrozumienie kodu

Podczas testowania działania możesz rozpocząć nową grę za pomocą głosowego wprowadzania tekstu („Zagraj jeszcze raz”) lub dotykowego wprowadzania danych (kliknij przycisk Zagraj jeszcze raz).

W przypadku opcji wprowadzania głosowego, gdy użytkownik powie „Zagraj jeszcze raz” lub podobne polecenie, zostanie dopasowany zamiar play_again i do kolejki promptów zostanie dodany prompt („OK, oto kolejna gra!”). Odpowiedź canvas zawarta w prompcie wysyła do aplikacji internetowej nazwę intencji i inne metadane. Nazwa intencji jest przekazywana do wywołania zwrotnego onUpdate(), które mapuje odpowiednie polecenie PLAY_AGAIN na mapę poleceń w action.js. Polecenie PLAY_AGAIN wywołuje funkcję start() w scene.js i aktualizuje aplikację internetową o nową sesję gry.

W przypadku opcji dotykowego wprowadzania danych używasz sendTextQuery(), czyli interfejsu Interactive Canvas API, który umożliwia wywoływanie intencji za pomocą dotykowego wprowadzania danych, aby przycisk działał.

W tym laboratorium kodowania użyjesz sendTextQuery(), aby wywołać intencję play_again, gdy użytkownik kliknie przycisk Zagraj jeszcze raz. Argument Play again pasuje do frazy treningowej w intencji play_again i wywołuje tę intencję w taki sam sposób, jak użytkownik mówiący „Zagraj jeszcze raz”. Intencja play_again wywołuje logikę, która aktualizuje aplikację internetową i rozpoczyna nową sesję gry.

9. Aktualizowanie wbudowanej intencji PLAY_GAME

W tej sekcji zaktualizujesz PLAY_GAME intencję wbudowaną.

Wbudowana intencja PLAY_GAME umożliwia użytkownikom wywoływanie Twojej akcji, gdy wysyłają ogólne żądanie, np. „Chcę zagrać w grę”.

Kod źródłowy zawiera wbudowaną intencję PLAY_GAME, która znajduje się w lokalizacji /sdk/custom/global/actions.intent.PLAY_GAME.yaml. W konsoli w sekcji Wywołanie jest to odzwierciedlone jako PLAY_GAME, jak pokazano na tym zrzucie ekranu:

Aby umożliwić użytkownikom wywoływanie działania za pomocą tej intencji wbudowanej, musisz dodać do intencji wbudowanej PLAY_GAME odpowiedź canvas z adresem URL aplikacji internetowej. W tym celu wykonaj następujące czynności:

W konsoli Actions kliknij PLAY_GAME na pasku nawigacyjnym.
Zaktualizuj prompt, aby zawierał adres URL aplikacji internetowej, jak pokazano w tym fragmencie kodu:

candidates:
  - canvas:
      url: 'https://<PROJECT_ID>.web.app'

Kliknij Zapisz.

Testowanie działania w symulatorze

Twoja Akcja obsługuje teraz intencję wbudowaną PLAY_GAME.

Aby przetestować działanie, wykonaj te czynności:

Na pasku nawigacyjnym kliknij Test.
Kliknij Testowanie obsługi intencji wbudowanych.
Kliknij Invoke Action (Wywołaj działanie).

Działanie powinno zostać wywołane w symulatorze.

10. Dodatek: rozwiązywanie problemów z działaniem Interactive Canvas

Z tej sekcji dowiesz się, jak debugować akcję Interactive Canvas, gdy nie działa ona prawidłowo. Projekt Snow Pal jest dostarczany z nakładką debugowania, którą możesz włączyć. Nakładka wyświetla wszystkie dane wyjściowe console.log() i console.error() w prawym dolnym rogu ekranu, jak pokazano na tym zrzucie ekranu:

Aby włączyć tę nakładkę, otwórz plik /public/css/main.css i dodaj komentarz do wiersza display: none !important;, jak pokazano w tym fragmencie kodu:

main.css

.debug {
 display: flex;
 flex-direction: column;

/* Comment below to view debug overlay */
/* display: none !important; */

 width: 500px;
 height: 150px;
 right: 0;
 bottom: 0;
 position: absolute;
}

Zwolnij miejsce w projekcie [zalecane]

Aby uniknąć ewentualnych opłat, zalecamy usunięcie projektów, których nie zamierzasz używać. Aby usunąć projekty utworzone w tym laboratorium, wykonaj te czynności:

Aby usunąć projekt Google Cloud i zasoby, wykonaj czynności opisane w sekcji Wyłączanie (usuwanie) projektów.

Opcjonalnie: aby natychmiast usunąć projekt z Konsoli Actions, wykonaj czynności opisane w sekcji Usuwanie projektu. Jeśli nie wykonasz tego kroku, Twój projekt zostanie automatycznie usunięty po około 30 dniach.

11. Gratulacje!

Ukończono wprowadzające ćwiczenie z Interactive Canvas i masz już umiejętności niezbędne do utworzenia własnej akcji Interactive Canvas.

Czego się dowiedziałeś(-aś)

Jak tworzyć, wdrażać i testować działanie Interactive Canvas
Jak używać odpowiedzi Canvas do aktualizowania aplikacji internetowej
Jak ulepszać działania za pomocą różnych metod, np. sendTextQuery() i setCanvasState()
Jak debugować działanie

Więcej informacji

Więcej informacji o Interactive Canvas znajdziesz w tych materiałach:

Dokumentacja Interactive Canvas: oficjalna dokumentacja Actions on Google dotycząca Interactive Canvas.
Przykładowy interaktywny Canvas: kod prostej gry w interaktywnym Canvasie, która umożliwia obracanie trójkąta i modyfikowanie jego kolorów.
Portal gier: wskazówki dotyczące tworzenia gier na Asystenta Google.

Ankieta dotycząca opinii

Zanim wyjdziesz, wypełnij krótką ankietę dotyczącą Twoich wrażeń.