Canvas 提示

如需将信息中继到您的 Web 应用,您必须从对话逻辑发送 Canvas 响应。Canvas 响应可以执行以下任一操作:

  • 在用户设备上呈现全屏 Web 应用
  • 传递数据以更新 Web 应用

以下部分介绍了如何针对每个场景返回 Canvas 响应。

启用 Interactive Canvas

您必须以特定方式配置 Action 才能使用 Interactive Canvas。要创建使用 Interactive Canvas 的 Action,需要在 Actions 控制台中进行其他配置(对于 Actions SDK,还需要修改 settings.yaml 文件)。如需了解使用 Actions SDK 创建和配置 Interactive Canvas Action 的完整过程,请参阅创建项目

使用 Actions Builder 时,请按照以下额外步骤启用 Interactive Canvas:

  1. 如果您未在 What type of Action do you want to build? 屏幕上选择 Game 卡片,请点击顶部导航栏中的 Deploy。在其他信息下,选择游戏与娱乐类别。 点击保存
  2. 点击 Actions 控制台顶部导航栏中的 Develop
  3. 点击左侧导航栏中的 Interactive Canvas
  4. Do you want your Action use Interactive Canvas? 下,选择以下选项之一:
    • 通过服务器 webhook 执行方式启用 Interactive Canvas。此选项依靠网络钩子来访问某些功能,并经常使用 onUpdate() 向 Web 应用传递数据。启用后,系统将在后台处理 intent 匹配,您可以选择在过渡到其他场景或结束对话之前调用网络钩子。
    • 通过客户端执行方式启用 Interactive Canvas。通过此选项,您可以将 webhook 执行方式逻辑移至 Web 应用,并将 webhook 调用限制为仅调用需要它的对话功能(例如帐号关联)。启用后,您可以使用 expect() 在客户端注册 intent 处理程序。
  5. 可选:在设置默认 Web 应用网址字段中输入您的 Web 应用网址。此操作会向 Main 调用添加包含网址字段的默认 Canvas 响应。
  6. 点击保存

使用 Actions SDK 时,请按照以下额外步骤启用 Interactive Canvas:

  1. settings.yaml 文件中的 category 字段设置为 GAMES_AND_TRIVIA,以便最准确地描述您的 Action,并帮助用户发现您的 Action。
  2. settings.yaml 文件中的 usesInteractiveCanvas 字段设置为 true

检查 surface 功能

Interactive Canvas 框架仅在提供视觉界面的 Google 助理设备上运行,因此您的 Action 需要检查用户设备上的 INTERACTIVE_CANVAS 功能。在 Actions Builder 中定义提示时,您可以在 candidates 对象的 selector 字段中指定设备功能列表。提示选择器选择最适合用户设备功能的候选提示。

如需返回 Canvas 响应,您的 Action 的逻辑应执行以下操作:

  1. 检查用户的设备是否支持 INTERACTIVE_CANVAS 功能。如果是,请向用户发送 Canvas 响应。
  2. 如果 Interactive Canvas 功能不可用,请检查用户的设备是否支持 RICH_RESPONSE 功能。如果支持,请改为向用户发送富响应
  3. 如果富响应功能不可用,请向用户发送简单响应

以下代码段会根据用户设备的功能返回适当的响应:

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

呈现 Web 应用

使用 Interactive Canvas 的 Action 包含一个 Web 应用,该应用具有您发送给用户的自定义视觉效果。Web 应用呈现后,用户即可继续通过语音、文字或触摸与它互动,直到对话结束。

您的第一个 Canvas 响应必须包含 Web 应用的网址。这种类型的 Canvas 响应会告知 Google 助理在用户设备上的相应地址呈现 Web 应用。通常,您会在用户调用您的 Action 后立即发送第一个 Canvas 响应。加载 Web 应用时,系统会加载 Interactive Canvas 库,然后 Web 应用会通过 Interactive Canvas API 注册回调处理程序。

您可以在 Actions Builder 中指定 Web 应用的网址,如以下屏幕截图所示:

如果您在指定 Web 应用网址后创建包含 Canvas 响应的提示,则 Actions Builder 会自动填充 Canvas 响应的网址字段。如需详细了解如何在控制台中设置 Web 应用网址,请参阅启用 Interactive Canvas 部分。

以下代码段展示了如何构建 Canvas 响应,以便在 Actions Builder 和网络钩子中呈现 Web 应用:

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

传递数据以更新 Web 应用

发送初始 Canvas 响应后,您可以使用其他 Canvas 响应为 data 提供更新,您的 Web 应用的自定义逻辑使用该更新对您的 Web 应用进行更改。当您发送将数据传递给 Web 应用的 Canvas 响应时,会执行以下步骤:

  1. 当 intent 在场景中匹配时,它会触发事件,然后系统会发送包含 data 字段且带有 JSON 载荷的 Canvas 响应作为响应。
  2. 系统会将 data 字段传递给 onUpdate 回调,并用于更新 Web 应用。
  3. 您的对话型 Action 可以发送新的 Canvas 响应并在 data 字段中提供信息,以发送新的更新或加载新状态。

您可以通过以下两种方式将数据传递到 Web 应用:

  • 使用 Actions Builder。Actions Builder 会使用必要的元数据自动填充 Canvas 响应中的 data 字段,以更新 Web 应用。
  • 使用 webhook。如果您有网络钩子,可以配置自定义数据载荷以在 Canvas 响应中更新 Web 应用。

以下部分介绍了如何通过 Actions Builder 和网络钩子传递数据。

使用 Actions Builder 传递数据

使用 Actions Builder 时,您无需定义网络钩子即可管理发送到 Web 应用的元数据。相反,在 Actions Builder 界面中配置 intent 处理程序时,您可以添加 Canvas 响应。data 字段会自动填充更新 Web 应用所需的元数据,例如 intent 名称、从用户输入中捕获的任何参数以及当前场景。

例如,以下 Guess intent 处理程序会指示您想要添加 Canvas 响应:

YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true
    

JSON

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

您可以选择将以下代码段附加到 intent 处理程序,以发送 TTS 消息:

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

Actions Builder 会自动使用元数据扩展 Canvas 响应,以更新 Web 应用,如以下代码段所示。在本示例中,用户在猜词游戏中猜对了字母“a”:

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

此响应会使用用户的回答和过渡到相应场景来更新您的 Web 应用。

使用网络钩子传递数据

您可以在 webhook 中手动配置 Canvas 响应的 data 字段,其中包含更新 Web 应用所需的状态信息。如果您需要在 Canvas 响应中添加自定义 data 载荷,而不是仅传递更新 Web 应用所需的典型元数据,则建议使用此方法。

以下代码段展示了如何在 webhook 的 Canvas 响应中传递数据:

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

准则和限制

构建 Action 时,请谨记以下与 Canvas 响应相关的准则和限制:

  • 执行方式中的每个 webhook 处理程序都必须包含 Canvas。如果网络钩子响应不包含 Canvas,您的 Web 应用会关闭。
  • 您只需在发送给用户的第一个 Canvas 响应中添加 Web 应用网址即可。
  • Canvas 响应网址应有效,且其协议必须为 https。
  • Canvas 响应的大小不得超过 50 KB。