Thông báo về các Hành động trong nhà thông minh

Thông báo cho phép tính năng tích hợp Cloud-to-cloud của bạn sử dụng Google Assistant để thông báo cho người dùng về các sự kiện hoặc thay đổi quan trọng liên quan đến thiết bị. Bạn có thể triển khai thông báo để cảnh báo người dùng về các sự kiện kịp thời trên thiết bị, chẳng hạn như khi có người ở cửa hoặc để báo cáo về thay đổi trạng thái thiết bị được yêu cầu, chẳng hạn như khi chốt khoá cửa đã được cài đặt thành công hoặc bị kẹt.

Tính năng tích hợp Cloud-to-cloud có thể gửi các loại thông báo sau cho người dùng:

• Thông báo chủ động: Cảnh báo cho người dùng về một sự kiện trên thiết bị smart home mà không cần người dùng yêu cầu trước, chẳng hạn như chuông cửa reo.

• Phản hồi tiếp theo: Thông báo xác nhận rằng yêu cầu lệnh thiết bị đã thành công hoặc không thành công, chẳng hạn như khi khoá cửa. Sử dụng các cảnh báo này cho các lệnh thiết bị cần thời gian để hoàn tất. Câu trả lời tiếp theo chỉ được hỗ trợ khi yêu cầu lệnh thiết bị được gửi từ loa thông minh và màn hình thông minh.

Assistant cung cấp các thông báo này cho người dùng dưới dạng thông báo trên loa thông minh và màn hình thông minh. Thông báo chủ động được tắt theo mặc định. Người dùng có thể bật hoặc tắt tất cả thông báo chủ động từ Google Home app (GHA).

Sự kiện kích hoạt thông báo

Khi sự kiện thiết bị xảy ra, phương thức thực hiện của bạn sẽ gửi yêu cầu thông báo đến Google. Các đặc điểm thiết bị mà tính năng tích hợp Cloud-to-cloud của bạn hỗ trợ sẽ xác định loại sự kiện thông báo có sẵn và dữ liệu bạn có thể đưa vào các thông báo đó.

Các đặc điểm sau đây hỗ trợ thông báo chủ động:

Các đặc điểm sau hỗ trợ câu trả lời tiếp theo:

Tất cả các loại thiết bị đều hỗ trợ thông báo cho các đặc điểm áp dụng.

Tạo thông báo cho tính năng tích hợp Cloud-to-cloud

Thêm thông báo vào quy trình tích hợp Cloud-to-cloud trong các giai đoạn sau:

1. Cho Google biết nếu thông báo được bật trong ứng dụng quản lý thiết bị smart home của bạn. Nếu người dùng bật hoặc tắt thông báo trong ứng dụng của bạn, hãy gửi yêu cầu SYNC để thông báo cho Google về thay đổi trên thiết bị.
2. Khi một sự kiện thiết bị hoặc thay đổi trạng thái có liên quan xảy ra và kích hoạt thông báo, hãy gửi yêu cầu thông báo bằng cách gọi API Report State reportStateAndNotification. Nếu trạng thái thiết bị thay đổi, bạn có thể gửi cả tải trọng trạng thái và tải trọng thông báo cùng nhau trong lệnh gọi Report State và Thông báo.

Các phần sau đây sẽ trình bày chi tiết hơn về những bước này.

Cho biết liệu thông báo có được bật trong ứng dụng của bạn hay không

Người dùng có thể chọn nhận hoặc không nhận thông báo chủ động bằng cách bật tính năng này trong GHA. Trong ứng dụng cho thiết bị smart home, bạn cũng có thể tuỳ ý thêm khả năng cho phép người dùng bật/tắt thông báo một cách rõ ràng từ thiết bị, chẳng hạn như từ phần cài đặt ứng dụng.

Cho Google biết rằng thông báo đã được bật cho thiết bị của bạn bằng cách thực hiện lệnh gọi Yêu cầu đồng bộ hoá để cập nhật dữ liệu thiết bị. Bạn nên gửi yêu cầu SYNC như thế này bất cứ khi nào người dùng thay đổi chế độ cài đặt này trong ứng dụng của bạn.

Trong phản hồi SYNC, hãy gửi một trong những thông tin cập nhật sau:

• Nếu người dùng bật thông báo một cách rõ ràng trong ứng dụng quản lý thiết bị hoặc nếu bạn không cung cấp tuỳ chọn bật/tắt, hãy đặt thuộc tính devices.notificationSupportedByAgent thành true.
• Nếu người dùng tắt thông báo một cách rõ ràng trong ứng dụng quản lý thiết bị, hãy đặt thuộc tính devices.notificationSupportedByAgent thành false.

Đoạn mã sau đây cho thấy một ví dụ về cách đặt phản hồi SYNC:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

Gửi yêu cầu thông báo đến Google

Để kích hoạt thông báo trên Assistant, phương thức thực hiện của bạn sẽ gửi một tải trọng thông báo đến Google Home Graph thông qua Report State và lệnh gọi API thông báo.

Bật Google HomeGraph API

1. Trong Google Cloud Console, hãy chuyển đến trang HomeGraph API.

   Chuyển đến trang HomeGraph API
2. Chọn dự án khớp với mã dự án smart home của bạn.
3. Nhấp vào BẬT.

Tạo khoá tài khoản dịch vụ

Làm theo các hướng dẫn sau để tạo khoá tài khoản dịch vụ từ Google Cloud Console:

1. Trong Google Cloud Console, hãy chuyển đến trang Tài khoản dịch vụ.

   Chuyển đến trang Tài khoản dịch vụ.

   Bạn có thể cần chọn một dự án trước khi được chuyển đến trang Tài khoản dịch vụ.

2. Nhấp vào addTạo tài khoản dịch vụ.

3. Trong trường Tên tài khoản dịch vụ, hãy nhập tên.

4. Trong trường Mã tài khoản dịch vụ, hãy nhập một mã nhận dạng.

5. Trong trường Mô tả tài khoản dịch vụ, hãy nhập nội dung mô tả.

6. Nhấp vào Tạo và tiếp tục.

7. Trong trình đơn thả xuống Role (Vai trò), hãy chọn Service Accounts (Tài khoản dịch vụ) > Service Account OpenID Connect Identity Token Creator (Trình tạo mã thông báo danh tính OpenID Connect của tài khoản dịch vụ).

8. Nhấp vào Tiếp tục.

9. Nhấp vào Xong.

10. Chọn tài khoản dịch vụ bạn vừa tạo trong danh sách tài khoản dịch vụ rồi chọn Quản lý khoá trong trình đơn more_vert Thao tác.

11. Chọn Thêm khoá > Tạo khoá mới.

12. Đối với Loại khoá, hãy chọn mục JSON.

13. Nhấp vào Tạo. Một tệp JSON chứa khoá của bạn sẽ được tải xuống máy tính.

Gửi thông báo

Thực hiện lệnh gọi yêu cầu thông báo bằng API devices.reportStateAndNotification. Yêu cầu JSON của bạn phải bao gồm một eventId, là mã nhận dạng duy nhất do nền tảng của bạn tạo cho sự kiện kích hoạt thông báo. eventId phải là một mã nhận dạng ngẫu nhiên và khác nhau mỗi khi bạn gửi yêu cầu thông báo.

Trong đối tượng notifications mà bạn truyền vào lệnh gọi API, hãy thêm một giá trị priority xác định cách hiển thị thông báo. Đối tượng notifications của bạn có thể bao gồm nhiều trường tuỳ thuộc vào đặc điểm của thiết bị.

Hãy làm theo một trong các đường dẫn sau để đặt tải trọng và gọi API:

• Gửi tải trọng thông báo chủ động
• Gửi tải trọng phản hồi tiếp theo

Gửi tải trọng thông báo chủ động

Để gọi API, hãy chọn một mục trong một trong các thẻ sau:

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});
    

// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Build device notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);
    

Gửi tải trọng phản hồi tiếp theo

Trọng tải cho phản hồi tiếp theo chứa trạng thái của yêu cầu, mã lỗi cho các lỗi sự kiện (nếu có) và followUpToken hợp lệ, được cung cấp trong yêu cầu ý định EXECUTE. Bạn phải sử dụng followUpToken trong vòng 5 phút để mã này vẫn hợp lệ và liên kết đúng cách phản hồi với yêu cầu ban đầu.

Đoạn mã sau đây cho thấy một ví dụ về tải trọng yêu cầu EXECUTE có trường followUpToken.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

Google sử dụng followUpToken để chỉ đưa ra thông báo trên thiết bị mà người dùng tương tác ban đầu, chứ không phát thông báo trên tất cả thiết bị của người dùng.

Để gọi API, hãy chọn một mục trong một trong các thẻ sau:

const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});
    

// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);
    

Ghi nhật ký

Thông báo hỗ trợ ghi nhật ký sự kiện như được nêu trong phần Ghi nhật ký trên đám mây cho Cloud-to-cloud. Các nhật ký này rất hữu ích cho việc kiểm thử và duy trì chất lượng thông báo trong Hành động của bạn.

Sau đây là giản đồ của một mục notificationLog:

Trường status bao gồm nhiều trạng thái có thể cho biết lỗi trong tải trọng thông báo. Một số tính năng trong số này có thể chỉ dùng được trên những Hành động chưa được phát hành chính thức.

Ví dụ về trạng thái:

Ngoài các trạng thái chung có thể áp dụng cho tất cả thông báo, trường status cũng có thể bao gồm các trạng thái dành riêng cho đặc điểm (nếu có, ví dụ: OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).