Mensajes del lienzo

Para retransmitir información a tu aplicación web, debes enviar una respuesta Canvas desde tu lógica de conversación. Una respuesta Canvas puede realizar cualquiera de las siguientes acciones:

• Renderizar la app web de pantalla completa en el dispositivo del usuario
• Pasa datos para actualizar la app web

En las siguientes secciones, se describe cómo mostrar una respuesta de Canvas para cada situación.

Habilitar Interactive Canvas

Debes configurar la acción de una forma específica para usar Interactive Canvas. Crear una acción que use Interactive Canvas requiere una configuración adicional en la Consola de Actions (y, para el SDK de Actions, debe modificar el archivo settings.yaml). Si deseas ver el procedimiento completo para crear y configurar una acción de Interactive Canvas con el SDK de Actions, consulta Cómo crear un proyecto.

Cuando uses Actions Builder, sigue estos pasos adicionales para habilitar Interactive Canvas:

1. Si no seleccionaste la tarjeta Juego en la pantalla What type of Action do you want to build?, haz clic en Implementar en la navegación superior. En Información adicional, selecciona la categoría Juegos y diversión. Haga clic en Guardar.
2. Haga clic en Develop, en la barra de navegación superior de la Consola de Actions.
3. Haz clic en Interactive Canvas en el panel de navegación izquierdo.
4. En ¿Deseas que tu acción use Interactive Canvas?, selecciona una de las siguientes opciones:
   • Habilita Interactive Canvas con entregas de webhook de servidor. Esta opción depende del webhook para acceder a ciertas funciones y, con frecuencia, usa onUpdate() a fin de pasar datos a la app web. Cuando se habilita, las coincidencias de intents se controlan en las escenas, y puedes optar por llamar al webhook antes de hacer la transición a otra escena o finalizar la conversación.
   • Habilita Interactive Canvas con entregas de clientes. Esta opción te permite mover la lógica de entrega de webhook a la aplicación web y limitar las llamadas de webhook a solo las funciones de conversación que lo requieran, como la vinculación de cuentas. Cuando se habilita, puedes usar expect() para registrar los controladores de intents en el lado del cliente.
5. Opcional: Ingresa la URL de tu aplicación web en el campo Establece la URL predeterminada de la aplicación web. Esta acción agrega a tu invocación principal una respuesta Canvas predeterminada con el campo URL.
6. Haz clic en Guardar.

Cuando uses el SDK de Actions, sigue estos pasos adicionales para habilitar Interactive Canvas:

1. Configura el campo category del archivo settings.yaml como GAMES_AND_TRIVIA para describir y ayudar a los usuarios a descubrir tu acción.
2. Establece el campo usesInteractiveCanvas en tu archivo settings.yaml en true.

Verifica la capacidad de la superficie

El framework de Interactive Canvas se ejecuta solo en dispositivos con Asistente integrado que proporcionan una interfaz visual, por lo que tu acción debe verificar la capacidad de INTERACTIVE_CANVAS en el dispositivo del usuario. Cuando defines mensajes en Actions Builder, puedes especificar una lista de capacidades del dispositivo en el campo selector del objeto candidates. El selector de mensajes selecciona el candidato del mensaje que sea más apropiado para la capacidad del dispositivo del usuario.

Para mostrar una respuesta Canvas, la lógica de tu acción debe hacer lo siguiente:

1. Comprueba que el dispositivo del usuario sea compatible con la función INTERACTIVE_CANVAS. De ser así, envíale una respuesta Canvas al usuario.
2. Si la capacidad de Interactive Canvas no está disponible, verifica si el dispositivo del usuario es compatible con la función RICH_RESPONSE. Si es así, envíale una respuesta enriquecida al usuario.
3. Si la función de respuesta enriquecida no está disponible, envíale una respuesta simple al usuario.

Los siguientes fragmentos muestran la respuesta adecuada según las capacidades del dispositivo del usuario:

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.');
}
  

Renderiza la app web

Una acción que usa Interactive Canvas incluye una app web con elementos visuales personalizados que envías a los usuarios como respuesta. Una vez que se renderiza la app web, los usuarios continúan interactuando con ella mediante voz, texto o acciones táctiles hasta que finaliza la conversación.

Tu primera respuesta de Canvas debe contener la URL de la aplicación web. Este tipo de respuesta de Canvas le indica al Asistente de Google que renderice la aplicación web en esa dirección en el dispositivo del usuario. Por lo general, envías la primera respuesta de Canvas inmediatamente después de que el usuario invoque tu acción. Cuando se carga la app web, se carga la biblioteca de Interactive Canvas y esta registra un controlador de devolución de llamada con la API de Interactive Canvas.

Puedes especificar la URL de tu aplicación web en Actions Builder, como se muestra en la siguiente captura de pantalla:

Si creas un mensaje que incluye una respuesta Canvas después de especificar la URL de la aplicación web, Actions Builder propaga automáticamente el campo URL de la respuesta Canvas. Para obtener más información sobre cómo configurar la URL de la aplicación web en la consola, consulta la sección Cómo habilitar Interactive Canvas.

Nota: Si especificas la URL de la aplicación web en Actions Builder, no se propagará automáticamente el campo de URL de la respuesta de Canvas en los mensajes que creaste antes.

En los siguientes fragmentos, se muestra cómo crear respuestas de Canvas que renderizan la aplicación web en Actions Builder y en tu webhook:

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

Pasa datos para actualizar la app web

Después de enviar la respuesta inicial de Canvas, puedes usar respuestas de Canvas adicionales para proporcionar actualizaciones a data, que la lógica personalizada de tu aplicación web utiliza para realizar cambios en ella. Cuando envías una respuesta de Canvas que pasa datos a la aplicación web, se producen los siguientes pasos:

1. Cuando se detecta una coincidencia con el intent dentro de una escena, se activa un evento y se envía una respuesta Canvas que contiene un campo data con una carga útil JSON.
2. El campo data se pasa a una devolución de llamada onUpdate y se usa para actualizar la aplicación web.

3. Tu acción de conversación puede enviar una respuesta Canvas nueva y proporcionar información en el campo data para enviar actualizaciones o cargar estados nuevos.

   Nota: Si el valor del campo url cambia en las respuestas de entrega posteriores, la app web se vuelve a cargar. Si se proporciona el mismo valor para url o si url se excluye como parte de una respuesta posterior, la app web existente se conserva en el dispositivo.

Puedes pasar datos a tu aplicación web de dos maneras:

• Con Actions Builder. Actions Builder propaga automáticamente el campo data en la respuesta de Canvas con los metadatos necesarios para actualizar la aplicación web.
• Con un webhook. Si tienes un webhook, puedes configurar una carga útil de datos personalizados para actualizar la aplicación web en tu respuesta de Canvas.

En las siguientes secciones, se describe cómo pasar datos a través de Actions Builder y de un webhook.

Cómo usar Actions Builder para pasar datos

Con Actions Builder, no necesitas definir un webhook para administrar los metadatos que se envían a tu aplicación web. En cambio, cuando configuras tu controlador de intents en la IU de Actions Builder, puedes incluir una respuesta de Canvas. Un campo data se propaga automáticamente con los metadatos necesarios para actualizar tu app web, como el nombre del intent, los parámetros capturados de la entrada del usuario y la escena actual.

Por ejemplo, el siguiente controlador de intents Guess indica que deseas incluir una respuesta Canvas:

YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true
    

JSON

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

De manera opcional, puedes agregar el siguiente fragmento al controlador del intent para enviar un mensaje TTS:

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

Actions Builder extiende automáticamente la respuesta de Canvas con metadatos para actualizar la aplicación web, como se muestra en los siguientes fragmentos. En este caso, el usuario adivinó la letra "a" en un juego de adivinanzas de palabras:

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

Esta respuesta actualiza tu aplicación web con la respuesta del usuario y pasa a la escena adecuada.

Usa tu webhook para pasar datos

Puedes configurar manualmente el campo data de las respuestas de Canvas en tu webhook con la información de estado necesaria para actualizar tu aplicación web. Este enfoque se recomienda si necesitas incluir una carga útil de data personalizada en una respuesta de Canvas, en lugar de pasar solo los metadatos típicos necesarios para actualizar la aplicación web.

En los siguientes fragmentos, se muestra cómo pasar datos en una respuesta Canvas de tu webhook:

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": ""
    }
  }
}
    

Lineamientos y restricciones

Cuando crees tu acción, ten en cuenta los siguientes lineamientos y restricciones para las respuestas de Canvas:

• Cada controlador de webhook en tu entrega debe incluir Canvas. Si la respuesta del webhook no incluye Canvas, se cierra la aplicación web.
• Solo debes incluir la URL de tu aplicación web en la primera respuesta de Canvas que envíes al usuario.
• La URL de respuesta Canvas debe ser válida y su protocolo debe ser https.
• La respuesta Canvas debe tener un tamaño de 50 KB o menos.