Prośby dotyczące Canvas

Aby przekazać informacje do aplikacji internetowej, musisz wysłać odpowiedź Canvas z logiki konwersacyjnej. Odpowiedź Canvas może wykonać jedną z tych czynności:

• Renderowanie pełnoekranowej aplikacji internetowej na urządzeniu użytkownika
• Przekazywanie danych w celu aktualizowania aplikacji internetowej

W sekcjach poniżej opisujemy, jak zwrócić odpowiedź Canvas w przypadku każdego z nich

Włącz interaktywny obszar roboczy

Aby korzystać z interaktywnego obszaru roboczego, musisz w określony sposób skonfigurować akcję. Utworzenie akcji korzystającej z interaktywnego obszaru roboczego wymaga dodatkowych w Konsoli Actions (a w przypadku pakietu SDK Actions – modyfikacja settings.yaml). Aby zapoznać się z pełną procedurą tworzenia konfigurowania akcji interaktywnego obszaru roboczego za pomocą zestawu SDK Actions, zobacz Utwórz projekt.

Jeśli używasz Actions Builder, wykonaj te dodatkowe czynności, aby włączyć aplikację interaktywną Płótno:

1. Jeśli nie została wybrana karta Gra w menu Typ działania który chcesz skompilować?, w menu nawigacyjnym u góry kliknij Wdróż. W sekcji Dodatkowe informacje wybierz Gry kategorii zabawy. Kliknij Zapisz.
2. Kliknij Develop (Rozbuduj) w górnym okienku w Konsoli Actions.
3. W menu po lewej stronie kliknij Interaktywny obszar roboczy.
4. W sekcji Czy chcesz, by akcja używała interaktywnego obszaru roboczego?, wybierz jedną z tych opcji: następujące:
   • Włącz realizację webhooka serwera Interactive Canvas z realizacją webhooka serwera. Ta opcja korzysta z webhooka do uzyskiwania dostępu do pewnych funkcji i często używa onUpdate(), aby przekazać dane do aplikacji internetowej. Gdy ta opcja jest włączona, dopasowania intencji są obsługiwane w scenach i przed przejściem możesz wywołać webhooka. przejście do innej sceny lub zakończenie rozmowy.
   • Włącz interaktywny obszar roboczy z obsługą realizacji klienta. Ta opcja umożliwia przenieść logikę realizacji webhooka do aplikacji internetowej oraz ograniczyć webhooka będzie wywoływać tylko te funkcje konwersacyjne, które go wymagają, takich jak połączenie kont. Gdy ta opcja jest włączona, możesz używać aplikacji expect() do: możesz zarejestrować moduły obsługi intencji po stronie klienta.
5. Opcjonalnie: wpisz URL aplikacji internetowej w polu Ustaw domyślny URL aplikacji internetowej. . To działanie dodaje domyślną odpowiedź Canvas z polem adresu URL do do wywołania głównego.
6. Kliknij Zapisz.

Jeśli używasz pakietu Actions SDK, wykonaj te dodatkowe czynności, aby włączyć wersję interaktywną Płótno:

1. W polu category w pliku settings.yaml ustaw wartość GAMES_AND_TRIVIA. jak najlepiej opisać Akcję i pomóc użytkownikom ją odkryć.
2. W polu usesInteractiveCanvas w pliku settings.yaml ustaw wartość true.

Sprawdź możliwości powierzchni

Platforma Interactive Canvas działa tylko na urządzeniach z Asystentem, które zapewniają interfejs graficzny, więc akcja musi sprawdzić, czy INTERACTIVE_CANVAS capability na urządzeniu użytkownika. Gdy zdefiniujesz prompty w Actions Builder, możesz podać listę możliwości urządzenia w polu selector funkcji candidates obiekt. Selektor promptów wybiera najbardziej odpowiednią propozycję dostosowane do możliwości urządzenia użytkownika.

Aby zwracana odpowiedź Canvas, logika akcji powinna:

1. Sprawdź, czy urządzenie użytkownika obsługuje funkcję INTERACTIVE_CANVAS. Jeśli Jeśli tak, wyślij użytkownikowi odpowiedź Canvas.
2. Jeśli funkcja Interactive Canvas jest niedostępna, sprawdź, czy użytkownik to urządzenie obsługuje funkcję RICH_RESPONSE. Jeśli tak, wyślij użytkownikowi odpowiedzi sformatowanej.
3. Jeśli opcja odpowiedzi rozszerzonych jest niedostępna, wyślij użytkownikowi wiadomość prostą odpowiedź.

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

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.
    

{
  "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."
          }
        ]
      }
    }
  ]
}

    

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 Interactive Canvas zawiera aplikację internetową ze treści wizualne, które wysyłasz użytkownikom w odpowiedzi. Po wyrenderowaniu aplikacji internetowej użytkownicy i używaj go za pomocą głosu, tekstu lub dotyku, aż rozmowa została zakończona.

Pierwsza odpowiedź Canvas musi zawierać adres URL aplikacji internetowej. Ten typ Odpowiedź Canvas informuje Asystenta Google, że ma wyrenderować aplikację internetową pod tym adresem na urządzeniu użytkownika. Zwykle wysyłasz pierwszą Canvas odpowiedź natychmiast po wywołaniu akcji przez użytkownika. Po wczytaniu aplikacji internetowej Wczytuje się biblioteka Interaktywna Canvas, a aplikacja internetowa rejestruje moduł obsługi wywołań zwrotnych. za pomocą interfejsu Interactive Canvas API.

W Actions Builder możesz określić adres URL swojej aplikacji internetowej, tak jak w komponencie następujący zrzut ekranu:

Jeśli utworzysz prompt zawierający odpowiedź Canvas po określeniu aplikacji internetowej, Actions Builder automatycznie wypełnia pole adresu URL w odpowiedzi Canvas. Więcej informacje o ustawianiu adresu URL aplikacji internetowej w konsoli znajdziesz Włącz interaktywny obszar roboczy.

Te fragmenty kodu pokazują, jak tworzyć odpowiedzi Canvas, które renderują aplikację internetową w Actions Builder oraz w webhooku:

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'
    

{
  "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"
      }
    }
  ]
}
    

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`,
  }));
});
    

{
  "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 w celu aktualizowania aplikacji internetowej

Po wysłaniu pierwszej odpowiedzi Canvas możesz użyć dodatkowych Canvas odpowiedzi na potrzeby aktualizacji danych typu data, z których korzysta niestandardowa logika aplikacji internetowej aby wprowadzić zmiany w aplikacji internetowej. Jeśli wyślesz odpowiedź Canvas, która zostanie zatwierdzona do aplikacji internetowej, wykonaj te czynności:

1. Dopasowanie intencji w ramach sceny powoduje wywołanie zdarzenia i odpowiedzi Canvas zawierające pole data z ładunkiem JSON jest następnie odsyłane jako odpowiedź.
2. Pole data jest przekazywane do wywołania zwrotnego onUpdate i używane do aktualizowania aplikacji internetowej.

3. Akcja związana z rozmowami może wysłać nową odpowiedź Canvas i przekazać informacje w data do wysyłania nowych aktualizacji lub wczytywania nowych stanów.

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

• za pomocą Actions Builder, Narzędzie do tworzenia działań automatycznie wypełnia pole data w odpowiedź Canvas z metadanymi niezbędnymi do zaktualizowania aplikacji internetowej.
• Za pomocą webhooka Jeśli masz webhooka, możesz skonfigurować dane niestandardowe w celu zaktualizowania aplikacji internetowej w odpowiedzi Canvas.

W sekcjach poniżej opisano, jak przekazywać dane za pomocą Actions Builder oraz webhooka.

Przekazywanie danych za pomocą Actions Builder

Dzięki Actions Builder nie musisz definiować webhooka do zarządzania metadanymi wysyłane do aplikacji internetowej. Zamiast tego, gdy skonfigurujesz moduł obsługi intencji w tabeli interfejsu kreatora działań, możesz uwzględnić odpowiedź Canvas. O Pole data jest automatycznie wypełniane metadanymi wymaganymi do aktualizacji aplikacji internetowej, takich jak nazwa intencji, wszelkie parametry przechwycone z danych wejściowych użytkownika, i bieżącą scenę.

Na przykład ten moduł obsługi intencji Guess wskazuje, że chcesz uwzględnić funkcję Canvas odpowiedź:

candidates:
  - canvas:
      send_state_data_to_canvas_app: true
    

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

Opcjonalnie możesz dołączyć ten fragment do modułu obsługi intencji, aby wysyłać Wiadomość TTS:

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

Actions Builder automatycznie rozszerza odpowiedź Canvas z metadanymi na zaktualizuj aplikację internetową w sposób pokazany poniżej. W tym przypadku użytkownik odgadł(a) literę „a” np. podczas zgadywania słów.

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

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

Ta odpowiedź aktualizuje Twoją aplikację internetową o odpowiedź użytkownika i przenosi ją do odpowiednią scenę.

Używanie webhooka do przekazywania danych

Pole data w Canvas odpowiedziach możesz ręcznie skonfigurować w webhooku z informacjami o stanie niezbędnymi do aktualizacji aplikacji internetowej. To podejście zalecane, jeśli w odpowiedzi Canvas musisz uwzględnić niestandardowy ładunek data zamiast przekazywać tylko typowe metadane potrzebne do zaktualizowania aplikacji internetowej.

Z tych fragmentów kodu dowiesz się, jak przekazywać dane w odpowiedzi Canvas w webhook:

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

{
  "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

Pamiętaj o tych wskazówkach i ograniczeniach dotyczących odpowiedzi typu Canvas podczas tworzenia akcji:

• Każdy moduł obsługi webhooka w ramach realizacji musi zawierać element Canvas. Jeśli webhook odpowiedź nie zawiera parametru Canvas, aplikacja internetowa zostaje zamknięta.
• Wystarczy, że w pierwszej odpowiedzi na Canvas podasz adres URL aplikacji internetowej który wysyłasz użytkownikowi.
• Adres URL odpowiedzi Canvas powinien być prawidłowy, a jego protokołem musi być https.
• Rozmiar odpowiedzi Canvas nie może przekraczać 50 KB.