Kể từ ngày 13 tháng 6 năm 2023, Hành động trò chuyện không còn được dùng nữa. Để biết thêm thông tin, hãy xem phần Hành động trò chuyện ngừng hoạt động.

Trang này được dịch bởi Cloud Translation API.

Câu lệnh trên Canvas

Để chuyển tiếp thông tin đến ứng dụng web, bạn phải gửi phản hồi Canvas từ logic trò chuyện. Phản hồi Canvas có thể thực hiện một trong những thao tác sau:

Hiển thị ứng dụng web toàn màn hình trên thiết bị của người dùng
Truyền dữ liệu để cập nhật ứng dụng web

Các phần sau đây mô tả cách trả về phản hồi Canvas cho từng trường hợp.

Bật Canvas tương tác

Bạn phải định cấu hình Hành động của mình theo một cách cụ thể để sử dụng Canvas tương tác. Việc tạo một Hành động sử dụng Canvas tương tác yêu cầu phải định cấu hình bổ sung trong bảng điều khiển Actions (và đối với SDK Hành động, hãy sửa đổi tệp settings.yaml). Để xem quy trình đầy đủ để tạo và định cấu hình Thao tác Canvas tương tác bằng SDK Thao tác, hãy xem phần Tạo dự án.

Khi sử dụng Trình tạo thao tác, hãy làm theo các bước bổ sung sau để bật Canvas tương tác:

Nếu bạn không chọn thẻ Trò chơi trên màn hình Bạn muốn xây dựng loại hành động nào?, hãy nhấp vào Deploy (Triển khai) trong thanh điều hướng trên cùng. Trong Thông tin bổ sung, hãy chọn danh mục Trò chơi và thú vị. Nhấp vào Lưu.
Nhấp vào Phát triển trong thanh điều hướng trên cùng của bảng điều khiển Actions.
Nhấp vào Canvas tương tác trong bảng điều hướng bên trái.
Trong phần Bạn có muốn Hành động của mình sử dụng Canvas tương tác không?, hãy chọn một trong các tuỳ chọn sau:
- Bật Canvas tương tác với phương thức thực hiện webhook của máy chủ. Tuỳ chọn này dựa vào webhook để truy cập một số tính năng nhất định và thường sử dụng onUpdate() để truyền dữ liệu vào ứng dụng web. Khi được bật, các lượt so khớp ý định sẽ được xử lý trong các cảnh và bạn có thể chọn gọi webhook trước khi chuyển sang một cảnh khác hoặc kết thúc cuộc trò chuyện.
- Bật Canvas tương tác với phương thức thực hiện ứng dụng. Tuỳ chọn này cho phép bạn di chuyển logic thực hiện webhook sang ứng dụng web và giới hạn lệnh gọi webhook chỉ ở các tính năng trò chuyện cần đến nó, chẳng hạn như liên kết tài khoản. Khi bật, bạn có thể sử dụng expect() để đăng ký trình xử lý ý định ở phía máy khách.
Không bắt buộc: Nhập URL ứng dụng web vào trường Đặt URL ứng dụng web mặc định. Thao tác này sẽ thêm phản hồi Canvas mặc định với trường URL vào lệnh gọi chính.
Nhấp vào Lưu.

Khi sử dụng SDK Hành động, hãy làm theo các bước bổ sung sau để bật Canvas tương tác:

Đặt trường category trong tệp settings.yaml thành GAMES_AND_TRIVIA để mô tả và giúp người dùng khám phá Hành động của bạn một cách chính xác nhất.
Đặt trường usesInteractiveCanvas trong tệp settings.yaml thành true.

Kiểm tra khả năng của bề mặt

Khung Canvas tương tác chỉ chạy trên các thiết bị có Trợ lý có cung cấp giao diện trực quan, vì vậy, Hành động của bạn cần kiểm tra chức năng INTERACTIVE_CANVAS trên thiết bị của người dùng. Khi xác định lời nhắc trong Trình tạo hành động, bạn có thể chỉ định danh sách các chức năng của thiết bị trong trường selector của đối tượng candidates. Bộ chọn lời nhắc sẽ chọn đề xuất lời nhắc phù hợp nhất với khả năng của thiết bị của người dùng.

Để trả về phản hồi Canvas, logic của Hành động phải hoạt động như sau:

Kiểm tra để đảm bảo rằng thiết bị của người dùng có hỗ trợ tính năng INTERACTIVE_CANVAS. Nếu có, hãy gửi cho người dùng phản hồi Canvas.
Nếu tính năng Canvas tương tác không hoạt động, hãy kiểm tra xem thiết bị của người dùng có hỗ trợ tính năng RICH_RESPONSE hay không. Nếu có, hãy gửi cho người dùng một phản hồi chi tiết.
Nếu không có tính năng phản hồi đa dạng thức, hãy gửi cho người dùng một phản hồi đơn giản.

Các đoạn mã sau đây trả về phản hồi phù hợp dựa trên khả năng của thiết bị của người dùng:

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

Kết xuất ứng dụng web

Hành động sử dụng Canvas tương tác bao gồm một ứng dụng web có hình ảnh tuỳ chỉnh mà bạn gửi cho người dùng dưới dạng phản hồi. Sau khi ứng dụng web hiển thị, người dùng sẽ tiếp tục tương tác với ứng dụng đó thông qua giọng nói, văn bản hoặc thao tác chạm cho đến khi cuộc trò chuyện kết thúc.

Phản hồi Canvas đầu tiên phải chứa URL của ứng dụng web. Loại phản hồi Canvas này sẽ yêu cầu Trợ lý Google hiển thị ứng dụng web tại địa chỉ đó trên thiết bị của người dùng. Thông thường, bạn sẽ gửi phản hồi Canvas đầu tiên ngay sau khi người dùng gọi Hành động. Khi ứng dụng web tải, thư viện Canvas tương tác sẽ tải và ứng dụng web sẽ đăng ký một trình xử lý gọi lại bằng Interactive Canvas API.

Bạn có thể chỉ định URL của ứng dụng web trong Trình tạo hành động, như trong ảnh chụp màn hình sau:

Nếu bạn tạo một lời nhắc chứa phản hồi Canvas sau khi chỉ định URL của ứng dụng web, Trình tạo hành động sẽ tự động điền sẵn trường URL của phản hồi Canvas. Để biết thêm thông tin về cách thiết lập URL của ứng dụng web trong bảng điều khiển, hãy xem phần Bật Canvas tương tác.

Các đoạn mã sau đây cho biết cách tạo các phản hồi Canvas để hiển thị ứng dụng web trong cả Trình tạo hành động và webhook của bạn:

Hàm 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"
    }
  }
}

Truyền dữ liệu để cập nhật ứng dụng web

Sau khi gửi phản hồi Canvas ban đầu, bạn có thể sử dụng các phản hồi Canvas bổ sung để cung cấp nội dung cập nhật cho data. Logic tuỳ chỉnh của ứng dụng web sẽ dùng để thực hiện các thay đổi đối với ứng dụng web. Khi bạn gửi phản hồi Canvas để truyền dữ liệu đến ứng dụng web, các bước sau sẽ diễn ra:

Khi được so khớp trong một cảnh, ý định sẽ kích hoạt một sự kiện, rồi phản hồi Canvas chứa trường data có tải trọng JSON sẽ được gửi lại dưới dạng phản hồi.
Trường data được truyền đến lệnh gọi lại onUpdate và dùng để cập nhật ứng dụng web.
Hành động trò chuyện có thể gửi một phản hồi Canvas mới và cung cấp thông tin trong trường data để gửi nội dung cập nhật mới hoặc tải trạng thái mới.

Lưu ý: Nếu giá trị của trường url thay đổi trong các phản hồi phương thức thực hiện tiếp theo, thì ứng dụng web sẽ tải lại. Nếu bạn cung cấp cùng một giá trị cho url hoặc nếu url bị loại trừ trong phản hồi tiếp theo, thì ứng dụng web hiện có sẽ được lưu giữ trên thiết bị.

Bạn có thể chuyển dữ liệu đến ứng dụng web của mình theo 2 cách:

Với Trình tạo hành động. Trình tạo hành động sẽ tự động điền trường data trong phản hồi Canvas bằng siêu dữ liệu cần thiết để cập nhật ứng dụng web.
Khi có webhook. Nếu có một webhook, bạn có thể định cấu hình một tải trọng dữ liệu tuỳ chỉnh để cập nhật ứng dụng web trong phản hồi của Canvas.

Các phần sau đây mô tả cách truyền dữ liệu thông qua Trình tạo hành động và thông qua webhook.

Sử dụng Trình tạo hành động để truyền dữ liệu

Với Trình tạo hành động, bạn không cần xác định webhook để quản lý siêu dữ liệu gửi đến ứng dụng web. Thay vào đó, khi định cấu hình trình xử lý ý định trong Giao diện người dùng Trình tạo hành động, bạn có thể thêm phản hồi Canvas. Trường data được tự động điền sẵn siêu dữ liệu cần thiết để cập nhật ứng dụng web, chẳng hạn như tên ý định, mọi tham số được thu thập từ hoạt động đầu vào của người dùng và cảnh hiện tại.

Ví dụ: trình xử lý ý định Guess sau đây cho biết rằng bạn muốn đưa vào một phản hồi Canvas:

Hàm YAML

candidates:
  - canvas:
      send_state_data_to_canvas_app: true

JSON

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

Bạn có thể tuỳ ý thêm đoạn mã sau đây vào trình xử lý ý định để gửi tin nhắn TTS:

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

Trình tạo hành động sẽ tự động mở rộng phản hồi Canvas bằng siêu dữ liệu để cập nhật ứng dụng web, như minh hoạ trong các đoạn mã sau. Trong trường hợp này, người dùng đã đoán chữ cái "a" trong một trò chơi đoán từ:

Hàm 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
      }
    }
  ]
}

Phản hồi này cập nhật ứng dụng web của bạn bằng câu trả lời của người dùng và chuyển đổi sang cảnh thích hợp.

Sử dụng webhook của bạn để chuyển dữ liệu

Bạn có thể tự thiết lập trường data của phản hồi Canvas trong webhook với thông tin trạng thái cần thiết để cập nhật ứng dụng web. Bạn nên sử dụng phương pháp này nếu cần đưa một tải trọng data tuỳ chỉnh vào phản hồi Canvas thay vì chỉ truyền siêu dữ liệu thông thường cần thiết để cập nhật ứng dụng web.

Các đoạn mã sau đây cho biết cách truyền dữ liệu trong phản hồi Canvas trong 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": ""
    }
  }
}

Nguyên tắc và hạn chế

Hãy lưu ý các nguyên tắc và quy định hạn chế sau đây đối với phản hồi Canvas khi tạo Hành động:

Mỗi trình xử lý webhook trong phương thức thực hiện của bạn phải bao gồm Canvas. Nếu phản hồi webhook không bao gồm Canvas, ứng dụng web của bạn sẽ đóng lại.
Bạn chỉ cần đưa URL của ứng dụng web vào phản hồi Canvas đầu tiên gửi cho người dùng.
URL phản hồi Canvas phải hợp lệ và giao thức của URL phải là https.
Phản hồi Canvas phải có kích thước từ 50 KB trở xuống.