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

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Thông báo cho phép tính năng tích hợp Cloud-to-cloud 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 thiết bị kịp thời, chẳng hạn như khi có người ở cửa hoặc để báo cáo về một thay đổi trạng thái thiết bị được yêu cầu, chẳng hạn như khi một chốt khoá cửa đã được kích hoạ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 đây cho người dùng:

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

• Phản hồi tiếp theo: Thông tin 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, ví dụ: khi khoá cửa. Hãy 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. Hệ thống chỉ hỗ trợ phản hồi tiếp theo khi các yêu cầu về 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. Theo mặc định, thông báo chủ động sẽ bị tắt. 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).

Các 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 hỗ trợ sẽ xác định những loại sự kiện thông báo có sẵn và dữ liệu mà 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 đây hỗ trợ phản hồ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 hiện có.

Tạo thông báo cho chế độ tích hợp Cloud-to-cloud

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

1. Cho Google biết liệu thông báo có được bật từ ứng dụng thiết bị smart home hay không. 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 đối với thiết bị.
2. Khi một sự kiện hoặc thay đổi trạng thái thiết bị 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ả 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 thông báo chủ động bằng cách bật tính năng này trong GHA. Trong ứng dụng dành cho thiết bị smart home, bạn cũng có thể tuỳ ý thêm tính 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 bạn đã bật thông báo cho thiết bị 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.

Trong phản hồi SYNC, hãy gửi một trong những nội dung 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 trên thiết bị của bạn 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 trên thiết bị, hãy đặt thuộc tính devices.notificationSupportedByAgent thành false.

Đoạn mã sau đây cho thấy 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 cho Google

Để kích hoạt thông báo trên Assistant, phương thức thực hiện đơn hàng sẽ gửi một gói dữ liệu 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 API Google HomeGraph

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.
3. Nhấp vào BẬT.

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

Làm theo 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 Vai trò, hãy chọn Tài khoản dịch vụ > Trình tạo mã thông báo nhận dạng 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 JSON.

13. Nhấp vào Tạo. Tệp JSON chứa khoá của bạn sẽ 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 eventId. Đây là mã nhận dạng duy nhất do nền tảng của bạn tạo ra 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 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 giá trị priority để xác định cách hiển thị thông báo. Đối tượng notifications 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 trọng tải và gọi API:

• Gửi gói dữ liệu 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 tuỳ chọn 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 sự kiện không thành công (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 chính xác phản hồi với yêu cầu ban đầu.

Đoạn mã sau đây cho thấy một tải trọng yêu cầu EXECUTE mẫu 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 ban đầu tương tác, chứ không phát đi trên tất cả thiết bị của người dùng.

Để gọi API, hãy chọn một tuỳ chọn 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ợ tính năng ghi nhật ký sự kiện như được nêu trong phần Ghi nhật ký trên đám mây cho giao thức từ đám mây đến đám mây. Các nhật ký này hữu ích cho việc kiểm thử và duy trì chất lượng thông báo trong Hành động.

Sau đây là giản đồ của mục nhập 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ố trong số này có thể chỉ có trên những Hành động chưa được phát hành công khai.

Sau đây là một số ví dụ về trạng thái:

Ngoài các trạng thái chung này 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).