Prośby dotyczące Canvas

Aby przekazać informacje do aplikacji internetowej, musisz wysłać odpowiedź Canvas z logiki konwersacyjnej. Odpowiedź Canvas może mieć jeden z tych zastosowań:

• Renderowanie pełnoekranowej aplikacji internetowej na urządzeniu użytkownika
• Przekazywanie danych, by zaktualizować aplikację internetową

Poniższe sekcje zawierają informacje o tym, jak zwrócić odpowiedź Canvas w każdym scenariuszu.

Włącz interaktywne kanwy

Aby korzystać z interaktywnego obszaru roboczego, musisz skonfigurować akcję w określony sposób. Utworzenie akcji korzystającej z interaktywnego obszaru roboczego wymaga dodatkowej konfiguracji w konsoli Actions (oraz w przypadku pakietu Actions SDK modyfikacji pliku settings.yaml). Pełną procedurę tworzenia i konfigurowania interaktywnej akcji Canvas za pomocą pakietu Actions SDK znajdziesz w sekcji Tworzenie projektu.

Jeśli korzystasz z Actions Builder, wykonaj te dodatkowe czynności, aby włączyć Interactive Canvas:

1. Jeśli na ekranie Jakie działanie chcesz utworzyć? nie została wybrana karta Gra, w górnym okienku nawigacyjnym kliknij Wdróż. W sekcji Informacje dodatkowe wybierz kategorię Gry i rozrywka. Kliknij Zapisz.
2. W górnym okienku nawigacyjnym Konsoli Actions kliknij Develop.
3. W menu nawigacyjnym po lewej stronie kliknij Interaktywny obszar roboczy.
4. W sekcji Czy chcesz, aby akcja używała interaktywnego obszaru roboczego? wybierz jedną z tych opcji:
   • Włącz interaktywną kreację Canvas z realizacją webhooka serwera. Ta opcja wymaga dostępu do niektórych funkcji webhooka i często wykorzystuje onUpdate() do przekazywania danych do aplikacji internetowej. Gdy ta opcja jest włączona, dopasowania intencji są obsługiwane w scenach. Możesz wywołać webhooka przed przejściem do innej sceny lub zakończeniem rozmowy.
   • Włączanie interaktywnego obszaru roboczego w ramach realizacji klienta. Ta opcja pozwala przenieść logikę realizacji webhooka do aplikacji internetowej i ograniczyć wywołania webhooka tylko do funkcji konwersacyjnych, które tego wymagają, takich jak łączenie kont. Gdy ta opcja jest włączona, możesz użyć expect(), aby zarejestrować moduły obsługi intencji po stronie klienta.
5. Opcjonalnie: wpisz adres URL aplikacji internetowej w polu Ustaw domyślny adres URL aplikacji internetowej. To działanie dodaje do wywołania głównego domyślną odpowiedź Canvas z polem adresu URL.
6. Kliknij Zapisz.

Jeśli korzystasz z pakietu Actions SDK, wykonaj te dodatkowe czynności, aby włączyć Interactive Canvas:

1. Ustaw w polu category w pliku settings.yaml wartość GAMES_AND_TRIVIA, aby jak najlepiej opisać akcję i ułatwić użytkownikom jej znalezienie.
2. W polu usesInteractiveCanvas w pliku settings.yaml ustaw wartość true.

Sprawdzanie możliwości platformy

Platforma Interactive Canvas działa tylko na urządzeniach z Asystentem, które udostępniają interfejs wizualny, dlatego akcja musi sprawdzić INTERACTIVE_CANVAS możliwość na urządzeniu użytkownika. Definiując prompty w Actions Builder, możesz określić listę możliwości urządzenia w polu selector obiektu candidates. Selektor promptu wybiera prompt, który najlepiej pasuje do możliwości urządzenia użytkownika.

Aby zwrócić odpowiedź Canvas, logika akcji powinna wyglądać tak:

1. Sprawdź, czy urządzenie użytkownika obsługuje funkcję INTERACTIVE_CANVAS. Jeśli tak, wyślij użytkownikowi odpowiedź Canvas.
2. Jeśli funkcja interaktywnego obszaru roboczego jest niedostępna, sprawdź, czy urządzenie użytkownika obsługuje tę funkcję RICH_RESPONSE. Jeśli tak się stanie, wyślij użytkownikowi odpowiedź rozszerzoną.
3. Jeśli funkcje rozszerzonych odpowiedzi są niedostępne, wyślij użytkownikowi prostą odpowiedź.

Poniższe fragmenty kodu zwracają odpowiednią odpowiedź na podstawie możliwości urządzenia użytkownika:

YAML

candidates:
  - selector:
      surface_capabilities:
        capabilities:
          - INTERACTIVE_CANVAS
    canvas:
      url: 'https://example.web.app'
  - selector:
      surface_capabilities:
        capabilities:
          - RICH_RESPONSE
    content:
      card:
        title: Card title
        text: Card Content
        image:
          url: 'https://example.com/image.png'
          alt: Alt text
        button:
          name: Link name
          open:
            url: 'https://example.com/'
  - first_simple:
      variants:
        - speech: Example simple response.
    

JSON

{
  "candidates": [
    {
      "selector": {
        "surface_capabilities": {
          "capabilities": [
            "INTERACTIVE_CANVAS"
          ]
        }
      },
      "canvas": {
        "url": "https://example.web.app"
      }
    },
    {
      "selector": {
        "surface_capabilities": {
          "capabilities": [
            "RICH_RESPONSE"
          ]
        }
      },
      "content": {
        "card": {
          "title": "Card title",
          "text": "Card Content",
          "image": {
            "url": "https://example.com/image.png",
            "alt": "Alt text"
          },
          "button": {
            "name": "Link name",
            "open": {
              "url": "https://example.com/"
            }
          }
        }
      }
    },
    {
      "first_simple": {
        "variants": [
          {
            "speech": "Example simple response."
          }
        ]
      }
    }
  ]
}

    

Node.js

const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");
if (supportsInteractiveCanvas) {
  // Respond with a Canvas response
  conv.add(new Canvas({
    url: 'https://example.web.app',
  }));
} else if (supportsRichResponse) {
  // Respond with a rich response
  conv.add(new Card({
    title: 'Card title',
    image: new Image({
      url: 'https://example.com/image.png',
      alt: 'Alt text',
    }),
    button: new Link({
      name: 'Link name',
      open: {
        url: 'https://example.com/',
      },
    }),
  }));
} else {
  // Respond with a simple response
  conv.add('Example simple response.');
}
  

Renderowanie aplikacji internetowej

Akcja wykorzystująca interaktywną przestrzeń roboczą obejmuje aplikację internetową z dostosowanymi wizualizacjami, które wysyłasz użytkownikom w odpowiedzi. Po wyrenderowaniu aplikacji internetowej użytkownicy mogą z niej korzystać za pomocą głosu, tekstu lub dotyku, dopóki rozmowa nie zostanie zakończona.

Pierwsza odpowiedź Canvas musi zawierać adres URL aplikacji internetowej. Ten typ odpowiedzi Canvas informuje Asystenta Google, że ma on renderować aplikację internetową pod tym adresem na urządzeniu użytkownika. Zwykle pierwszą odpowiedź Canvas wysyła użytkownik zaraz po wywołaniu akcji przez użytkownika. Po wczytaniu aplikacji internetowej wczyta się biblioteka interaktywnego obszaru roboczego, a aplikacja internetowa zarejestruje moduł obsługi wywołania zwrotnego za pomocą interfejsu Interactive Canvas API.

Możesz podać adres URL swojej aplikacji internetowej w Actions Builder, jak pokazano na tym zrzucie ekranu:

Jeśli po podaniu adresu URL aplikacji internetowej utworzysz prompt zawierający odpowiedź Canvas, narzędzie Actions Builder automatycznie wypełnia pole URL odpowiedzi Canvas. Więcej informacji o ustawianiu adresu URL aplikacji internetowej w konsoli znajdziesz w sekcji Włączanie interaktywnego obszaru roboczego.

Uwaga: określenie adresu URL aplikacji internetowej w Actions Builder nie spowoduje automatycznego wypełnienia pola adresu URL odpowiedzi Canvas w utworzonych wcześniej promptach.

Z podanych niżej fragmentów kodu dowiesz się, jak tworzyć odpowiedzi Canvas, które renderują aplikację internetową zarówno w Actions Builder, jak i w webhooku:

YAML

candidates:
  - first_simple:
       variants:
         - speech: >-
             Welcome! Do you want me to change color or pause spinning? You can
             also tell me to ask you later.
     canvas:
       url: 'https://your-web-app.com'
    

JSON

{
  "candidates": [
    {
      "first_simple": {
        "variants": [
          {
            "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later."
          }
        ]
      },
      "canvas": {
        "url": "https://your-web-app.com"
      }
    }
  ]
}
    

Node.js

app.handle('welcome', (conv) => {
  conv.add('Welcome! Do you want me to change color or pause spinning? ' +
    'You can also tell me to ask you later.');
  conv.add(new Canvas({
    url: `https://your-web-app.com`,
  }));
});
    

JSON

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later.",
      "text": "Welcome! Do you want me to change color or pause spinning? You can also tell me to ask you later."
    },
    "canvas": {
      "data": [],
      "suppressMic": false,
      "url": "https://your-web-app.com"
    }
  }
}
    

Przekazywanie danych, by zaktualizować aplikację internetową

Po wysłaniu początkowej odpowiedzi Canvas możesz użyć dodatkowych odpowiedzi Canvas, aby zaktualizować data, których niestandardowa logika Twojej aplikacji internetowej używa do wprowadzania zmian w aplikacji internetowej. Gdy wyślesz odpowiedź Canvas, która przekazuje dane do aplikacji internetowej, wykonywane są te czynności:

1. Dopasowanie intencji w scenie powoduje wywołanie zdarzenia, a odpowiedź Canvas zawierająca pole data z ładunkiem JSON jest następnie wysyłana z powrotem.
2. Pole data jest przekazywane do wywołania zwrotnego onUpdate i używane do aktualizowania aplikacji internetowej.

3. Akcja związana z rozmową może wysłać nową odpowiedź Canvas i podać informacje w polu data, aby wysłać nowe aktualizacje lub wczytać nowe stany.

   Uwaga: jeśli wartość pola url zmieni się w kolejnych odpowiedziach dotyczących realizacji, aplikacja internetowa zostanie ponownie załadowana. Jeśli podana zostanie ta sama wartość parametru url lub url zostanie wykluczona w kolejnej odpowiedzi, istniejąca aplikacja internetowa zostanie zachowana na urządzeniu.

Dane do aplikacji internetowej możesz przekazywać na 2 sposoby:

• Za pomocą Actions Builder. Actions Builder automatycznie wypełnia pole data w odpowiedzi Canvas metadanymi niezbędnymi do zaktualizowania aplikacji internetowej.
• Za pomocą webhooka Jeśli masz webhooka, możesz skonfigurować niestandardowy ładunek danych, aby zaktualizować aplikację internetową w odpowiedzi Canvas.

W sekcjach poniżej opisano, jak przekazywać dane przez kreatora Actions i przez webhooka.

Przekazywanie danych za pomocą Actions Builder

Dzięki Actions Builder nie musisz definiować webhooka do zarządzania metadanymi wysyłanymi do Twojej aplikacji internetowej. Zamiast tego podczas konfigurowania modułu obsługi intencji w interfejsie Actions Builder możesz dołączyć odpowiedź Canvas. Pole data jest automatycznie wypełniane metadanymi niezbędnymi do aktualizacji aplikacji internetowej, np. nazwą intencji, parametrami przechwyconymi z danych wejściowych użytkownika i bieżącą sceną.

Na przykład ten moduł obsługi intencji Guess wskazuje, że chcesz dołączyć odpowiedź Canvas:

YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true
    

JSON

{
  "candidates": [
    {
      "canvas": {
        "send_state_data_to_canvas_app": true
      }
    }
  ]
}
    

Aby wysłać wiadomość TCP, możesz opcjonalnie dołączyć do modułu obsługi intencji ten fragment:

...
  - first_simple:
      variants:
        - speech: Optional message.

Actions Builder automatycznie rozszerza odpowiedź Canvas o metadane, aby zaktualizować aplikację internetową, jak pokazano w poniższych fragmentach. W tym przypadku użytkownik odgadł literę „a” w grze w zgadywanie słów:

YAML

candidates:
  - canvas:
      data:
        - google:
            intent:
              params:
                letter:
                  resolved: a
                  original: a
              name: guess
            scene: Game
      sendStateDataToCanvasApp: true
    

JSON

{
  "candidates": [
    {
      "canvas": {
        "data": [
          {
            "google": {
              "intent": {
                "params": {
                  "letter": {
                    "resolved": "a",
                    "original": "a"
                  }
                },
                "name": "guess"
              },
              "scene": "Game"
            }
          }
        ],
        "sendStateDataToCanvasApp": true
      }
    }
  ]
}
    

Ta odpowiedź aktualizuje aplikację internetową przy użyciu odpowiedzi użytkownika i przechodzi do odpowiedniego sceny.

Przekazywanie danych za pomocą webhooka

Możesz ręcznie skonfigurować pole data odpowiedzi Canvas w webhooku, podając informacje o stanie niezbędnym do aktualizacji aplikacji internetowej. Jest to zalecane, jeśli chcesz uwzględnić w odpowiedzi Canvas niestandardowy ładunek data, zamiast przekazywać tylko typowe metadane potrzebne do aktualizacji aplikacji internetowej.

Te fragmenty kodu pokazują, jak przekazywać dane w odpowiedzi Canvas w webhooku:

Node.js

app.handle('start_spin', (conv) => {
  conv.add(`Ok, I'm spinning. What else?`);
  conv.add(new Canvas({
    data: {
      command: 'SPIN',
      spin: true,
    },
  }));
});
    

JSON

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Ok, I'm spinning. What else?",
      "text": "Ok, I'm spinning. What else?"
    },
    "canvas": {
      "data": {
        "command": "SPIN",
        "spin": true
      },
      "suppressMic": false,
      "url": ""
    }
  }
}
    

Wytyczne i ograniczenia

Podczas tworzenia akcji pamiętaj o tych wytycznych i ograniczeniach dotyczących odpowiedzi Canvas:

• Każdy moduł obsługi webhooka w realizacji musi zawierać element Canvas. Jeśli odpowiedź webhooka nie zawiera parametru Canvas, aplikacja internetowa zostanie zamknięta.
• Adres URL aplikacji internetowej musisz umieścić tylko w pierwszej odpowiedzi Canvas wysłanej do użytkownika.
• Adres URL odpowiedzi Canvas powinien być prawidłowy, a jego protokół musi zaczynać się od HTTPS.
• Rozmiar odpowiedzi Canvas nie może przekraczać 50 KB.