Callbacks

É possível implementar os seguintes callbacks na ação de tela interativa:

onUpdate()

O callback onUpdate() transmite dados do webhook para seu app da Web para atualizar o app da Web adequadamente. Use esse callback apenas com o modelo de fulfillment do lado do servidor de desenvolvimento de tela interativa.

Para mais informações sobre onUpdate(), consulte Transmitir dados para atualizar o app da Web.

onTtsMark()

O callback onTtsMark() é chamado quando as tags <mark> personalizadas incluídas na linguagem de marcação de síntese de fala (SSML, na sigla em inglês) da sua resposta são lidas para o usuário durante a conversão de texto em voz (TTS, na sigla em inglês). É possível usar onTtsMark() nos modelos de desenvolvimento de fulfillment do lado do servidor e do cliente.

Nos snippets abaixo, onTtsMark() sincroniza a animação do app da Web com a saída de TTS correspondente. Quando a ação disser ao usuário "Desculpe, você perdeu", o app da Web soletra a palavra correta e mostra as letras para o usuário.

No exemplo a seguir, o gerenciador de webhook revealWord inclui uma marca personalizada na resposta para o usuário ter perdido o jogo:

JavaScript

…
app.handle('revealWord', conv => {
  conv.add(new Simple(`<speak>Sorry, you lost.<mark name="REVEAL_WORD"/> The word is ${conv.session.params.word}.</speak>`));
  conv.add(new Canvas());
});
…

O snippet de código a seguir registra o callback onTtsMark(), verifica o nome da marca e executa a função revealCorrectWord(), que atualiza o app da Web:

JavaScript

…
setCallbacks() {
    // declare Assistant Canvas Action callbacks
    const callbacks = {
        onTtsMark(markName) {
            if (markName === 'REVEAL_WORD') {
                // display the correct word to the user
                that.revealCorrectWord();
            }
        },
    }
    callbacks.onUpdate.bind(this);
}
…

onInputStatusChanged()

O callback onInputStatusChanged() notifica você quando o status de entrada muda na ação de tela interativa. As mudanças no status de entrada indicam quando o microfone abre e fecha ou quando o Google Assistente está processando uma consulta. Os eventos a seguir podem fazer com que o status de entrada mude:

  • O usuário que está falando com sua Ação
  • Usuário digitando um texto no app Pesquisa Google para Android (AGSA, na sigla em inglês)
  • O app da Web usando a API sendTextQuery() para enviar uma consulta de texto para a ação
  • Gravação de ações no armazenamento do Google Home e em outros eventos do Google Assistente

O principal caso de uso desse callback é sincronizar sua ação com as interações por voz do usuário. Por exemplo, se um usuário estiver jogando um jogo de tela interativa e abrir o microfone, você poderá pausar o jogo enquanto ele fala. Você também pode aguardar até que o microfone esteja aberto para enviar uma consulta de texto ao Google Assistente e garantir que ela seja recebida.

Essa API informa os seguintes status:

  • LISTENING: indica que o microfone está aberto.
  • IDLE: indica que o microfone está fechado.
  • PROCESSING: indica que o Google Assistente está executando uma consulta e o microfone está fechado.

A API informa o status de entrada para sua ação sempre que o status é alterado.

Embora qualquer transição entre estados seja possível, os seguintes fluxos são comuns:

  • IDLE>LISTENING>PROCESSING>IDLE: o usuário diz uma consulta, a consulta é processada e o microfone é fechado.
  • IDLE>PROCESSING>IDLE: o app da Web usa a API sendTextQuery() para enviar uma consulta de texto para a ação.
  • IDLE>LISTENING>IDLE: o usuário abre o microfone, mas não diz uma consulta.

Para usar esse recurso na sua Ação, adicione onInputStatusChanged() ao código do seu app da Web, conforme mostrado no snippet abaixo:

onInputStatusChanged(inputStatus) {
   console.log("The new input status is: ", inputStatus);
}

O callback onInputStatusChanged() transmite um único parâmetro de tipo enumerado, inputStatus. Você pode verificar esse valor para ver o status atual da entrada. O inputStatus pode ser LISTENING, PROCESSING ou IDLE.

Em seguida, adicione onInputStatusChanged() ao objeto callbacks para registrá-lo, conforme mostrado no snippet a seguir:

 /**
  * Register all callbacks used by the Interactive Canvas Action
  * executed during game creation time.
  */
 setCallbacks() {
   const that = this;
   // Declare the Interactive Canvas action callbacks.
   const callbacks = {
     onUpdate(data) {
       console.log('Received data', data);
     },
     onInputStatusChanged(inputStatus) {
       console.log("The new input status is: ", inputStatus);
     },
   };
   // Called by the Interactive Canvas web app once web app has loaded to
   // register callbacks.
   this.canvas.ready(callbacks);
 }
}