Mensajes del lienzo

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

  • Renderiza 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 tu acción de una manera específica para usar Interactive Canvas. Para crear una acción que use Interactive Canvas, se requiere configuración adicional en la Consola de Actions (y, para el SDK de Actions, modificaciones en 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 Qué tipo de acción quieres compilar?, haz clic en Implementar en la barra de navegación superior. En Información adicional, selecciona la categoría Juegos y diversión. Haga clic en Guardar.
  2. En la barra de navegación superior de la Consola de Actions, haz clic en Develop.
  3. Haz clic en Interactive Canvas en el panel de navegación izquierdo.
  4. En Do you want your Action to use Interactive Canvas?, selecciona una de las siguientes opciones:
    • Habilita Interactive Canvas con la entrega de webhooks de servidor. Esta opción se basa en el webhook para acceder a ciertas funciones y usa onUpdate() con frecuencia para pasar datos a la app web. Cuando se habilita, las coincidencias de intents se controlan en escenas y puedes llamar al webhook antes de pasar a otra escena o finalizar la conversación.
    • Habilita Interactive Canvas con la entrega 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 las funciones de conversación que la requieren, como la vinculación de cuentas. Cuando se habilita, puedes usar expect() para registrar los controladores de intents del lado del cliente.
  5. Opcional: Ingresa la URL de la aplicación web en el campo Establece la URL predeterminada de la aplicación web. Esta acción agrega una respuesta Canvas predeterminada con el campo de URL a tu invocación principal.
  6. Haz clic en Guardar.

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

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

Cómo verificar la capacidad de la plataforma

El framework de Interactive Canvas solo se ejecuta 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 elige la opción de mensaje más adecuada para la capacidad del dispositivo del usuario.

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

  1. Verifica que el dispositivo del usuario sea compatible con la función INTERACTIVE_CANVAS. Si es así, envía al usuario una respuesta Canvas.
  2. Si la función Interactive Canvas no está disponible, verifica si el dispositivo del usuario es compatible con la función RICH_RESPONSE. Si es así, envía una respuesta enriquecida al usuario.
  3. Si la función de respuesta enriquecida no está disponible, envía 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 imágenes personalizadas que envías a los usuarios como respuesta. Una vez que se renderiza la app web, los usuarios siguen interactuando con ella mediante voz, texto o controles táctiles hasta que termine la conversación.

Tu primera respuesta Canvas debe contener la URL de la app web. Este tipo de respuesta Canvas le indica a 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 invoca tu acción. Cuando se carga la app web, se carga la biblioteca de Interactive Canvas y la app web 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 app web, Actions Builder propaga automáticamente el campo de URL de la respuesta Canvas. Si quieres obtener más información para configurar la URL de la aplicación web en la consola, consulta la sección Habilitar Interactive Canvas.

En los siguientes fragmentos, se muestra cómo construir respuestas de Canvas que renderizan la aplicación web en Actions Builder y 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 Canvas, puedes usar respuestas Canvas adicionales para proporcionar actualizaciones de data, que la lógica personalizada de tu app web usa para realizar cambios en tu app web. Cuando envías una respuesta Canvas que pasa datos a la app web, se producen los siguientes pasos:

  1. Cuando el intent coincide dentro de una escena, activa un evento y, luego, se envía una respuesta Canvas que contiene un campo data con una carga útil JSON como respuesta.
  2. El campo data se pasa a una devolución de llamada onUpdate y se usa para actualizar la app 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 nuevas o cargar estados nuevos.

Puedes pasar datos a tu app web de dos maneras:

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

En las siguientes secciones, se describe cómo pasar datos mediante Actions Builder y 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 app web. En su lugar, cuando configuras el controlador de intents en la IU de Actions Builder, puedes incluir una respuesta Canvas. Un campo data se completa automáticamente con los metadatos necesarios para actualizar tu app web, como el nombre del intent, cualquier parámetro capturado de la entrada del usuario y la escena actual.

Por ejemplo, el siguiente controlador de intent 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 de forma automática la respuesta Canvas con metadatos para actualizar la app web, como se muestra en los siguientes fragmentos. En este caso, el usuario adivinó la letra "a" en un juego de adivinación 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 realiza la transición a la escena adecuada.

Usa tu webhook para pasar datos

Puedes configurar de forma manual el campo data de las respuestas de Canvas en tu webhook con la información de estado necesaria para actualizar tu aplicación web. Se recomienda este enfoque si necesitas incluir una carga útil de data personalizada en una respuesta de Canvas, en lugar de solo pasar 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 en 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

Ten en cuenta los siguientes lineamientos y restricciones para las respuestas de Canvas cuando compiles tu acción:

  • Cada controlador de webhook en tu entrega debe incluir Canvas. Si la respuesta de webhook no incluye Canvas, se cierra la aplicación web.
  • Solo debes incluir la URL de la aplicación web en la primera respuesta Canvas que le 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.