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

Thông báo cho phép chế độ tích hợp Cloud-to-cloud sử dụng Google Assistant để giao tiếp với 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ề một 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 gài thành công hoặc bị kẹt.

Chế độ 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 smart home trên thiết bị mà không có bất kỳ 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 báo xác nhận rằng yêu cầu lệnh thiết bị đã thành công hay thất bại, ví dụ: khi khoá cửa. Sử dụng các cảnh báo này cho những lệnh đối với thiết bị cần có thời gian để hoàn tất. Chỉ 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 thì mới hỗ trợ các câu trả lời tiếp theo.

Assistant cung cấp những thông báo này cho người dùng dưới dạng thông báo trên màn hình thông minh và loa 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 các sự kiện trên thiết bị xảy ra, dịch vụ thực hiện yêu cầu của bạn sẽ gửi một yêu cầu thông báo đến Google. Các đặc điểm của thiết bị mà chế độ tích hợp Cloud-to-cloud của bạn hỗ trợ sẽ xác định những loại sự kiện thông báo có sẵn và dữ liệu bạn có thể đưa vào những 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 áp dụng.

Tạo thông báo cho hoạt động tích hợp Đám mây với đám mây

Thêm thông báo vào chế độ 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 của bạn 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 trên thiết bị.
2. Khi một sự kiện hoặc thay đổi trạng thái có liên quan trên thiết bị xảy ra và kích hoạt mộ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à 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 phần GHA. Trong ứng dụng dành cho thiết bị smart home, bạn cũng có thể tuỳ ý thêm khả năng để 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ư trong 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 Request SYNC để 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 thiết bị của bạn hoặc nếu bạn không cung cấp lựa 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 thiết bị của bạn, 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, dịch vụ thực hiện đơn hàng của bạn 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 Notification API.

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 có mã dự án smart home phù hợp.
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 một 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 Nội dung 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 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ụ mà 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 Hành động more_vert.

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. 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 có eventId. Đây là một 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 trong lệnh gọi API, hãy thêm giá trị priority để xác định cách trình bày 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 tải trọng 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 lựa 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

Tải trọng cho một 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 về ý định EXECUTE. Bạn phải sử dụng followUpToken trong vòng 5 phút để giữ cho mã này hợp lệ và liên kết đúng 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ỉ xuất 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ả các thiết bị của người dùng.

Để gọi API, hãy chọn một lựa 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ợ 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 Thao tác của bạn.

Sau đây là giản đồ của một 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ố tính năng trong số này có thể chỉ có trên những Thao tác chưa được ra mắt cho người dùng thực.

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

Ngoài những 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).