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.

Kontynuuj tworzenie po stronie klienta lub serwera

Gdy znasz już podstawy, możesz ulepszyć i dostosować akcję za pomocą metod typowych dla Canvas. Podczas tworzenia projektu w Actions możesz wybrać akcję za pomocą modelu realizacji klienta lub modelu realizacji po stronie serwera. Więcej informacji o tych opcjach znajdziesz w artykule Włączanie interaktywnego obszaru roboczego.

Jeśli wybierzesz opcję modelu realizacji klienta, możesz użyć w akcji:

Wszystkie interfejsy API wymienione w sekcji Tworzenie z realizacją po stronie klienta.
Wszystkie interfejsy API wymienione w sekcji Tworzenie z realizacją po stronie serwera.

Uwaga: w przypadku realizacji po stronie klienta zalecamy wywoływanie webhooka tylko w przypadku funkcji innych niż Canvas, które go wymagają, takich jak łączenie kont.
Wywołanie zwrotne usługi onTtsMark()

Jeśli wybierzesz opcję modelu realizacji serwera, możesz użyć w akcji:

Wszystkie interfejsy API wymienione w sekcji Tworzenie z realizacją po stronie serwera.
Wywołania zwrotne

Niektórych interfejsów Interactive Canvas API nie zalecamy używania z konkretnym modelem realizacji. W tabeli poniżej znajdziesz interfejsy API włączone po wybraniu opcji realizacji klienta oraz informacje o tym, czy są one zalecane w przypadku poszczególnych modeli lub odradzane w ich przypadku:

Nazwa interfejsu API	Obsługiwany w modelu realizacji serwera?	Obsługiwany w modelu realizacji klienta
`sendTextQuery()`	Tak	Obsługiwane, ale niezalecane (aby dowiedzieć się więcej, zobacz sendtextQuery())
`outputTts()`	Tak	Tak
`triggerScene()`	Nie	Tak
`createIntentHandler(), expect(), clearExpectations(), prompt()`	Nie	Tak
`createNumberSlot(),createTextSlot, createConfirmationSlot, createOptionsSlot()`	Nie	Tak
`setHomeParam(), getHomeParam(), setUserParam(), getUserParam()`	Nie	Tak

Poniżej wyjaśniamy, jak wdrożyć interfejsy API dla klienta i modeli realizacji po stronie serwera w działaniu interaktywnego obszaru roboczego.

Twórz z realizacją po stronie klienta

W swojej logice aplikacji internetowej możesz zaimplementować te interfejsy Interactive Canvas API:

`outputTts()`

Ten interfejs API umożliwia zamianę tekstu na mowę z urządzenia bez wysyłania statycznego promptu z Actions Builder ani wywoływania webhooka. Jeśli nie jest wymagana żadna logika po stronie serwera powiązana z użyciem zamiany tekstu na mowę, możesz użyć polecenia outputTts() po stronie klienta, aby pominąć przejście na serwer i szybciej odpowiedzieć użytkownikom.

outputTts()Po stronie klienta może zakłócać lub anulować zamianę tekstu na mowę po stronie serwera. Możesz uniknąć zakłóceń działania zamiany tekstu na mowę po stronie serwera, podejmując następujące działania:

Unikaj wywoływania funkcji outputTts() na początku sesji. Zamiast tego w pierwszej kolejności konwersacji używaj zamiany tekstu na mowę po stronie serwera.
Unikaj wywoływania pod numer outputTts() kolejno bez interwencji użytkownika.

Ten fragment kodu pokazuje, jak używać outputTts() do odczytywania zamiany tekstu na mowę po stronie klienta:

interactiveCanvas.outputTts(
      '<speak>This is an example response.</speak>', true);

Możesz też użyć właściwości outputTts() z onTtsMark(), aby umieścić znaczniki SSML w sekwencji tekstu. Użycie polecenia onTtsMark() powoduje synchronizację animacji lub stanu gry w określonych punktach ciągu tekstowego SSML (TS), jak widać w tym fragmencie:

interactiveCanvas.outputTts(
      '<speak>Speak as <mark name="number" /> number <break time="700ms"/>' +
      '<say-as interpret-as="cardinal">12345</say-as> <break time="300ms"/> ' +
      'Speak as <mark name="digits" /> digits <break time="700ms"/>' +
      '<say-as interpret-as="characters">12345</say-as></speak>', true);

W poprzednim przykładzie 2 znaczniki dostosowujące Twoją odpowiedź są wysyłane do aplikacji internetowej za pomocą zamiany tekstu na mowę.

Obsługa realizacji intencji po stronie klienta

W modelu realizacji serwera dla interaktywnego obszaru roboczego wszystkie intencje muszą być obsługiwane przez webhooka, co zwiększa opóźnienie akcji. Zamiast wywoływać webhooka, możesz obsługiwać realizację intencji w aplikacji internetowej.

Do obsługi intencji po stronie klienta możesz używać tych interfejsów API:

createIntentHandler(): metoda, która pozwala definiować w kodzie aplikacji internetowej moduły obsługi intencji dla intencji niestandardowych zdefiniowanych w Actions Builder.
expect(): metoda, która aktywuje lub rejestruje moduł obsługi intencji, aby użytkownik mógł dopasować intencję.
clearExpectations(): metoda, która spełnia oczekiwania dotyczące wszystkich aktualnie aktywowanych intencji, dzięki czemu nie można dopasować intencji, nawet jeśli użytkownik wypowiada wypowiedź pasującą do intencji.
deleteHandler(): metoda, która wyłącza poszczególne moduły obsługi intencji, dzięki czemu nie można dopasować intencji.

Za pomocą tych interfejsów API możesz selektywnie aktywować lub wyłączać intencje związane z różnymi stanami działania interaktywnego obszaru roboczego. Aby aktywować te intencje, musisz użyć elementu expect() w ramach modułu obsługi intencji.

Aktywowanie modułów obsługi intencji

Aktywowanie modułu obsługi intencji to proces dwuetapowy. Najpierw określ intencję w Actions Builder. Następnie, aby umożliwić dopasowanie intencji, musisz wywołać expect() w module obsługi intencji.

Aby skonfigurować i aktywować moduł obsługi intencji po stronie klienta, wykonaj te czynności:

Otwórz projekt w Konsoli Actions i dodaj intencję niestandardową.
Obok opcji Czy to jest intencja globalna? wybierz Tak.

Uwaga: intencje tworzone w Actions Builder i aktywowane po stronie klienta muszą być skonfigurowane jako intencje globalne.
Skonfiguruj intencję i kliknij Zapisz.

Zdefiniuj moduł obsługi intencji w logice aplikacji internetowej, jak w tym fragmencie:

/**
* Define handler for intent.
*/
const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
  matchedIntent => {
    console.log("Intent match handler to reserve a table was triggered!");
  });

/**
* Define handler for intent with an argument.
*/
const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
  matchedIntent => {
    const numberOfPeople = matchedIntent.getIntentArg('numberOfPeople');
    console.log(`Intent match handler to reserve a table for ${number of people} was triggered!`);
  });

Wywołaj metodę expect(), aby zarejestrować moduł obsługi intencji, jak pokazano w tym fragmencie:

/**
* Define handler for intent and expect() it.
*/
const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
  matchedIntent => {
    console.log("Intent match handler to reserve a table was triggered!");
  });
var handler = interactiveCanvas.expect(bookTableIntent);

Wyłącz moduły obsługi intencji

Po zdefiniowaniu modułu obsługi intencji możesz w razie potrzeby aktywować lub dezaktywować intencję dla swojej akcji. Gdy wywołujesz expect(), aby aktywować intencję, zwracasz obiekt z metodą deleteHandler(), której możesz użyć do wyłączenia nowo utworzonego modułu obsługi. Definicja modułu obsługi intencji istnieje nawet wtedy, gdy intencja nie jest obecnie aktywna, więc w razie potrzeby możesz ponownie aktywować intencję.

Aby wyłączyć moduł obsługi intencji, wywołaj w nim funkcję deleteHandler(), jak pokazano w tym fragmencie:

    /**
    * Define handler for intent and expect() it.
    */
    const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
      matchedIntent => {
        console.log("Intent match handler to reserve a table was triggered!");
      });
    var handler = interactiveCanvas.expect(bookTableIntent);
    
    // Delete the handler for `bookTableIntent`.
    handler.deleteHandler();

Możesz wywołać expect(), aby ponownie dodać wyłączony moduł obsługi intencji, tak jak w tym fragmencie:

    // Re-add the `bookTableIntent` handler.
    handler = interactiveCanvas.expect(bookTableIntent);

Aby zbiorczo wyłączyć intencje, możesz użyć metody clearExpectations(), która wyłącza wszystkie aktualnie aktywowane intencje. Z tego fragmentu dowiesz się, jak sprecyzować oczekiwania wszystkich modułów obsługi intencji:

interactiveCanvas.clearExpectations();

Obsługa wypełniania przedziałów po stronie klienta

Zamiast dodawać wypełnienie przedziałów do sceny w Actions Builder, możesz obsługiwać wypełnianie przedziałów bezpośrednio w aplikacji internetowej.

Aby obsługiwać wypełnianie przedziałów po stronie klienta, musisz najpierw utworzyć przedział za pomocą jednego z tych interfejsów API:

createNumberSlot(callback, hints): metoda umożliwiająca definiowanie przedziałów numerycznych w kodzie aplikacji internetowej. Służy do proszenia użytkownika o podanie numeru.
createTextSlot(callback, hints): metoda umożliwiająca definiowanie boksu tekstowego w kodzie aplikacji internetowej. Służy do proszenia użytkownika o wpisanie słowa.
createConfirmationSlot(callback, hints): metoda umożliwiająca zdefiniowanie boksu potwierdzenia w kodzie aplikacji internetowej. Służy do proszenia użytkownika o potwierdzenie (tak/nie).
createOptionsSlot(options, callback, hints): metoda umożliwiająca zdefiniowanie boksu opcji w kodzie aplikacji internetowej. Służy do proszenia użytkownika o wybranie opcji z listy wstępnie zdefiniowanych.

Podczas tworzenia boksu możesz opcjonalnie zdefiniować triggerHints, czyli słowa kluczowe ulepszające system rozumienia języka naturalnego (NLU) dla działania. Powinny to być krótkie słowa, które użytkownik może podać podczas wypełniania boksu. Na przykład słowem kluczowym triggerHints w przypadku boksu liczbowego może być years. Gdy w rozmowie użytkownik odpowie na pytanie o wiek, używając odpowiedzi „Mam trzydzieści lat”, akcja z większym prawdopodobieństwem rozpozna, że użytkownik prawidłowo wypełnia miejsce.

Po utworzeniu boksu możesz poprosić użytkownika o wypełnienie go za pomocą interfejsu API prompt:

prompt(tts, slot): metoda, która wyświetla użytkownikowi przekształcenie tekstu na mowę z prośbą o wypełnienie oczekiwanego przedziału.

Wywołanie prompt() zwraca obietnicę ze stanem i wartością wypełnionego przedziału.

Utwórz przedział czasowy

Przedział numerowy pozwala użytkownikowi poprosić użytkownika o podanie numeru w trakcie rozmowy. Więcej informacji o wypełnianiu przedziałów znajdziesz w sekcji Wypełnianie przedziałów w dokumentacji Actions Builder.

Aby poprosić użytkownika o wypełnienie boksu liczbowego po stronie klienta, wykonaj te czynności:

Wywołaj metodę createNumberSlot(), aby utworzyć numer telefonu w logice aplikacji internetowej:

/**
 * Create number slot.
 */
const triggerHints = { associatedWords: ['guess number', 'number'] };
const slot = interactiveCanvas.createNumberSlot(
  number => {
    console.log(`Number guessed: ${number}.`);
  }, triggerHints);

Wywołaj metodę prompt(), aby wyświetlić użytkownikowi prośbę o przypisanie boksu i obsługiwać wartość boksu ze zwróconej obietnicy, tak jak w tym fragmencie:

const promptPromise = interactiveCanvas.prompt(
  { text: 'What number am I thinking of between 1 and 10?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: 5, status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

Utwórz boks tekstowy

Boksy tekstowe umożliwiają wyświetlenie użytkownikowi prośby o wyraz w trakcie rozmowy. Więcej informacji o wypełnianiu przedziałów znajdziesz w sekcji Wypełnianie przedziałów w dokumentacji Actions Builder.

Aby poprosić użytkownika o wypełnienie boksu tekstowego po stronie klienta, wykonaj te czynności:

Wywołaj metodę createTextSlot(), aby utworzyć boks tekstowy w logice aplikacji internetowej:

/**
 * Create text slot.
 */
const triggerHints = { associatedWords: ['favorite color', 'color'] };
const slot = interactiveCanvas.createTextSlot(
  text => {
    console.log(`Favorite color: ${text}.`);
  }, triggerHints);

Wywołaj metodę prompt(), aby wyświetlić użytkownikowi prośbę o przypisanie boksu i obsługiwać wartość boksu ze zwróconej obietnicy, tak jak w tym fragmencie:

const promptPromise = interactiveCanvas.prompt(
  { text: 'What is your favorite color?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: "red", status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

Utwórz przedział potwierdzenia

Przedział potwierdzenia umożliwia wyświetlenie użytkownikowi prośby o potwierdzenie (użytkownik może odpowiedzieć „Tak” lub „Nie”, aby wypełnić miejsce). Więcej informacji o wypełnianiu przedziałów znajdziesz w sekcji Wypełnianie przedziałów w dokumentacji Actions Builder.

Aby poprosić użytkownika o wypełnienie boksu potwierdzenia po stronie klienta, wykonaj te czynności:

Wywołaj metodę createConfirmationSlot(), aby utworzyć przedział potwierdzenia w logice aplikacji internetowej:

/**
 * Create confirmation slot (boolean).
 */
const triggerHints = { associatedWords: ['user confirmation', 'confirmation'] };
const slot = interactiveCanvas.createConfirmationSlot(
  yesOrNo => {
    console.log(`Confirmation: ${yesOrNo}`);
  }, triggerHints);

Wywołaj metodę prompt(), aby wyświetlić użytkownikowi prośbę o przypisanie boksu i obsługiwać wartość boksu ze zwróconej obietnicy, tak jak w tym fragmencie:

const promptPromise = interactiveCanvas.prompt(
  { text: 'Do you agree to the Terms of Service?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: true, status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

Utwórz przedział opcji

Przedział opcji umożliwia wyświetlenie użytkownikowi prośby o wybranie z listy wstępnie zdefiniowanych opcji. Więcej informacji o wypełnianiu przedziałów znajdziesz w sekcji Wypełnianie przedziałów w dokumentacji Actions Builder.

Aby poprosić użytkownika o wypełnienie boksu opcji po stronie klienta, wykonaj te czynności:

Wywołaj metodę createOptionsSlot(), aby utworzyć przedział opcji w logice aplikacji internetowej:

/**
 * Create options slot (list selection).
 */
const triggerHints = { associatedWords: ['select fruit', 'choose fruit'] };
// Define selectable options
const options = [{
  key: 'apple',
  synonyms: ['apple', 'large apple', 'gala apple'],
}, {
  key: 'banana',
  synonyms: ['banana', 'green banana', 'plantain'],
}];
const slot = interactiveCanvas.createOptionsSlot(
  options,
  selectedOption => {
    console.log(`You have selected ${selectedOption} as your fruit.`);
  }, triggerHints);

Wywołaj metodę prompt(), aby wyświetlić użytkownikowi prośbę o przypisanie boksu i obsługiwać wartość boksu ze zwróconej obietnicy, tak jak w tym fragmencie:

const promptPromise = interactiveCanvas.prompt(
  { text: 'Would you like a banana or an apple?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: 'apple', status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

`triggerScene()`

Interfejs triggerScene() API umożliwia przejście do innej sceny w działaniu interaktywnego obszaru roboczego od realizacji po stronie klienta. Dzięki triggerScene() możesz też przejść z realizacji po stronie klienta na realizację po stronie serwera, gdy użytkownik potrzebuje dostępu do sceny systemowej w Actions Builder, która wymaga webhooka. Możesz np. wywołać funkcję triggerScene(), gdy użytkownik chce połączyć swoje konto lub otrzymywać powiadomienia. Następnie możesz powrócić z tej sceny do realizacji po stronie klienta, używając prompta Canvas.

Ten fragment kodu pokazuje, jak wdrożyć triggerScene() w akcji:

interactiveCanvas.triggerScene('SceneName').then((status) => {
  console.log("sent the request to trigger scene.");
}).catch(e => {
  console.log("Failed to trigger a scene.");
})

Pamięć dla domu i użytkownika w kliencie

Zamiast używać webhooka do pobierania i ustawiania wartości pamięci domowej i pamięci użytkownika, możesz wywoływać interfejsy API po stronie klienta, aby obsługiwać pamięć domową i pamięć użytkownika w Twojej aplikacji internetowej. Aplikacja internetowa może używać tych zapisanych wartości w wielu sesjach (np. w komunikatach i warunkach) i w razie potrzeby ma dostęp do wartości związanych z konkretnym gospodarstwem domowym lub użytkownikiem. Korzystanie z tych interfejsów API może zmniejszyć opóźnienia w działaniu interaktywnego obszaru roboczego, ponieważ nie trzeba już wywoływać webhooka w celu uzyskania i ustawienia wartości miejsca na dane.

Przechowywanie danych na stronie głównej i w aplikacji internetowej podlega tym samym ogólnym zasadom co miejsce na dane we webhooku. Więcej informacji o miejscu na dane na stronie głównej i przez użytkownika znajdziesz w dokumentacji dotyczącej miejsca na dane w domu i miejsca na dane użytkownika.

Magazynowanie w domu po stronie klienta

Miejsce na dane w domu umożliwia przechowywanie wartości dotyczących domowników na podstawie wykresu głównego i jest współdzielone przez wszystkie sesje domowników. Jeśli na przykład użytkownik gra w grę Interactive Canvas w domu, wynik gry może być przechowywany w pamięci domowej, a inni domownicy mogą kontynuować grę z zapisanym wynikiem.

Aby akcja obsługiwała domową pamięć masową, wykonaj te czynności:

W konsoli Actions wybierz Wdróż > Informacje o katalogu > Informacje dodatkowe.
Zaznacz pole Tak w sekcji Czy Twoje akcje używają pamięci domowej?

Aby zapisać wartość w pamięci podręcznej w aplikacji internetowej, wywołaj metodę setHomeParam(), jak w tym fragmencie:

interactiveCanvas.setHomeParam('familySize',  10).then(
      result => {
        console.log('Set home param success');
      },
      fail => {
        console.error(err);
      });

Aby odczytać w aplikacji internetowej wartość z pamięci domowej, wywołaj metodę getHomeParam(), jak pokazano w tym fragmencie:

interactiveCanvas.getHomeParam('familySize').then(
      value => {
        console.log(JSON.stringify(result));
      },
      err => {
        console.error(err);
      }
  );

Aby wyczyścić całe dotychczasowe miejsce na dane, wywołaj metodę resetHomeParam(), jak pokazano w tym fragmencie:

interactiveCanvas.resetHomeParam();

Pamięć użytkownika po stronie klienta

W pamięci użytkownika możesz przechowywać wartości parametrów dla konkretnego, zweryfikowanego użytkownika w wielu sesjach. Jeśli na przykład użytkownik gra w grę, wynik gry może być zapisywany dla tego użytkownika. Podczas kolejnej sesji rozgrywki użytkownik może kontynuować grę z takim samym wynikiem.

Aby zapisać wartość w pamięci użytkownika w aplikacji internetowej, wywołaj metodę setUserParam(), jak w tym fragmencie kodu:

interactiveCanvas.setUserParam('color',  'blue').then(
      result => {
        console.log('Set user param success');
      },
      err => {
        console.error(err);
      });

Aby odczytać wartość z pamięci użytkownika w aplikacji internetowej, wywołaj metodę getUserParam(), jak pokazano w tym fragmencie:

interactiveCanvas.getUserParam('color').then(
      value => {
        console.log(JSON.stringify(result));
      },
      err => {
        console.error(err);
      }
  );

Aby wyczyścić całe dotychczasowe miejsce na dane użytkownika, wywołaj metodę resetUserParam(), jak pokazano w tym fragmencie:

interactiveCanvas.resetUserParam();

`setCanvasState()`

Metoda setCanvasState() umożliwia wysyłanie danych o stanie z interaktywnej aplikacji internetowej Canvas do realizacji i powiadamia Asystenta o zaktualizowaniu stanu aplikacji. Aplikacja internetowa wysyła swój zaktualizowany stan jako obiekt JSON.

Wywołanie metody setCanvasState() nie wywołuje intencji. Jeśli po wywołaniu funkcji setCanvasState() zostanie wywołana funkcja sendTextQuery() lub zapytanie użytkownika pasuje do intencji w rozmowie, dane ustawione w funkcji setCanvasState() w poprzednim kroku rozmowy są dostępne w kolejnych sekwencjach rozmowy.

Ten fragment kodu używa uprawnienia setCanvasState() do ustawiania danych stanu Canvas:

JavaScript

this.action.canvas.setCanvasState({ score: 150 })

Referencyjny stan obszaru roboczego z webhooka

Do zapisanych wartości stanu Canvas możesz się odwoływać w kodzie realizacji. Aby odwołać się do wartości, użyj składni conv.context.canvas.state.KEY, gdzie KEY to klucz podany podczas ustawiania wartości stanu Canvas.

Jeśli na przykład wcześniej zapisałeś dużą wartość wyniku gry w stanie Canvas jako parametr score, odwołaj się do tej wartości za pomocą conv.context.canvas.state.score, aby uzyskać dostęp do tej wartości podczas realizacji:

Node.js

app.handle('webhook-name', conv => {
    console.log(conv.context.canvas.state.score);
})

Stan obszaru roboczego odwołania w promptach

W prompcie możesz się odwoływać do zapisanych wartości stanu Canvas. Aby odwołać się do wartości, użyj składni $canvas.state.KEY, gdzie KEY to klucz podany podczas ustawiania wartości stanu Canvas.

Jeśli na przykład wcześniej zapisałeś dużą wartość wyniku gry w stanie Canvas jako parametr score, odwoływanie się do tej wartości za pomocą $canvas.state.score, aby uzyskać dostęp do tej wartości w prompcie:

JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Your high score is $canvas.state.score."
      }]
    }
  }]
}

Stan obszaru roboczego odwołania do warunków

W warunkach możesz się też odwoływać do zapisanych wartości stanu Canvas. Aby odwołać się do wartości, użyj składni canvas.state.KEY, gdzie KEY to klucz podany podczas ustawiania wartości stanu Canvas.

Jeśli na przykład wcześniej zapisałeś dużą wartość wyniku gry w stanie Canvas jako parametr score i chcesz ją porównać z wartością 999 w warunku, możesz odwołać się do przechowywanej wartości w warunku za pomocą funkcji canvas.state.score. Wyrażenie warunku wygląda tak:

Składnia warunku

canvas.state.score >= 999

`sendTextQuery()`

Metoda sendTextQuery() wysyła zapytania tekstowe do akcji dotyczącej konwersacji, aby automatycznie dopasować intencję. W tym przykładzie użyto sendTextQuery() do ponownego uruchomienia gry z trójkątem, gdy użytkownik kliknie przycisk. Gdy użytkownik kliknie przycisk „Uruchom ponownie grę”, sendTextQuery() wysyła zapytanie tekstowe pasujące do intencji Restart game i zwraca obietnicę. Ta obietnica daje SUCCESS, jeśli intencja zostanie aktywowana, lub BLOCKED, jeśli nie jest. Ten fragment kodu odpowiada intencji i obsługuje przypadki powodzenia i niepowodzenia obietnicy:

JavaScript

…
/**
* Handle game restarts
*/
async handleRestartGame() {
    console.log(`Request in flight`);
    this.button.texture = this.button.textureButtonDisabled;
    this.sprite.spin = false;
    const res = await this.action.canvas.sendTextQuery('Restart game');
    if (res.toUpperCase() !== 'SUCCESS') {
        console.log(`Request in flight: ${res}`);
        return;
    }
    console.log(`Request in flight: ${res}`);
    this.button.texture = this.button.textureButtonDisabled;
    this.sprite.spin = false;
}
…

Jeśli obietnica daje wynik SUCCESS, moduł obsługi webhooka Restart game wysyła odpowiedź Canvas do Twojej aplikacji internetowej:

JavaScript

…
app.handle('restart', conv => {
  conv.add(new Canvas({
    data: {
      command: 'RESTART_GAME'
    }
  }));
});
…

Ta odpowiedź Canvas aktywuje wywołanie zwrotne onUpdate(), które wykonuje kod z poniższego fragmentu kodu RESTART_GAME:

JavaScript

…
RESTART_GAME: (data) => {
    this.scene.button.texture = this.scene.button.textureButton;
    this.scene.sprite.spin = true;
    this.scene.sprite.tint = 0x00FF00; // green
    this.scene.sprite.rotation = 0;
},
…

Tworzenie z realizacją po stronie serwera

W swoim webhooku możesz zaimplementować te interfejsy Interactive Canvas API:

Włącz tryb pełnoekranowy

Domyślnie aplikacje internetowe interaktywnej aplikacji Canvas zawierają u góry ekranu nagłówek z nazwą akcji. Możesz użyć enableFullScreen, aby usunąć nagłówek i zastąpić go tymczasowym komunikatem, który pojawi się na ekranie wczytywania. Umożliwi to użytkownikowi korzystanie z trybu pełnoekranowego podczas interakcji z akcją. Komunikat zawiera wyświetlaną nazwę akcji, nazwę dewelopera i instrukcje jej zamknięcia. Kolor powiadomienia zmienia się w zależności od tego, co użytkownik wybierze jako motyw na urządzeniu.

**Rysunek 1.** Toast na ekranie wczytywania akcji.

Jeśli użytkownik często wchodzi w interakcję z akcją, komunikat tego typu tymczasowo przestaje się pojawiać na ekranie wczytywania. Jeśli użytkownik przez jakiś czas nie wejdzie z nią w interakcję, po jej uruchomieniu ponownie wyświetli się komunikat.

Tryb pełnoekranowy możesz włączyć w webhooku lub w statycznej podpowiedzi w Actions Builder.

Aby włączyć tryb pełnoekranowy we właściwościach webhooka, wykonaj te czynności:

W polu enableFullScreen ustaw wartość true w pierwszej odpowiedzi canvas zwróconej przez webhooka w sesji. Ten fragment to przykładowa implementacja przy użyciu biblioteki klienta w środowisku Node.js:

 const { conversation, Canvas } = require('@assistant/conversation');
 const functions = require('firebase-functions');

 const app = conversation();

 app.handle('invocation_fullscreen', conv => {
   conv.add(new Canvas(
     {
       url: 'https://example-url.com',
       enableFullScreen: true
     }));
 });

 exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

Aby włączyć tryb pełnoekranowy w statycznej podpowiedzi w Actions Builder, wykonaj te czynności:

Otwórz projekt w Konsoli Actions.
Na pasku nawigacyjnym kliknij Develop (Programuj) i otwórz prompt zawierający pierwszą odpowiedź canvas.

Ustaw wartość enable_full_screen na true, jak pokazano w tym fragmencie:

 {
  "candidates": [
    {
      "canvas": {
        "url": "https://example-url.com",
        "enable_full_screen": true
      }
    }
  ]
}

`continueTtsDuringTouch`

Domyślnie, gdy użytkownik dotknie ekranu podczas korzystania z interaktywnego obszaru roboczego, zamiana tekstu na mowę zatrzyma odtwarzanie. Możesz włączyć zamianę tekstu na mowę po dotknięciu ekranu continueTtsDuringTouch. Tego zachowania nie można włączać ani wyłączać w tej samej sesji.

Możesz to zrobić w webhooku lub w statycznym promptie w Actions Builder.

Aby włączyć zamianę tekstu na mowę po kliknięciu przez użytkownika ekranu webhooka, wykonaj te czynności:

W polu continueTtsDuringTouch ustaw wartość true w pierwszej odpowiedzi canvas zwróconej przez webhooka w sesji. Ten fragment to przykładowa implementacja przy użyciu biblioteki klienta w środowisku Node.js:

const { conversation, Canvas } = require('@assisant/conversation');
const functions = require('firebase-functions');

const app = conversation();

app.handle('intent-name', conv => {
  conv.add(new Canvas(
    {
      url: 'https://example-url.com',
      continueTtsDuringTouch: true
    }));
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

Aby włączyć zamianę tekstu na mowę po kliknięciu przez użytkownika ekranu w statycznym komunikacie w Actions Builder, wykonaj te czynności:

Otwórz projekt w Konsoli Actions.
Na pasku nawigacyjnym kliknij Develop (Programuj) i otwórz prompt z pierwszą odpowiedzią canvas.

Ustaw wartość continue_tts_during_touch na true, jak pokazano w tym fragmencie:

  {
   "candidates": [
     {
       "canvas": {
         "url": "https://example-url.com",
         "continue_tts_during_touch": true
       }
     }
   ]
 }