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

Thông báo cho phép Hành động smart home 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 đang ở ngoài cửa hoặc báo cáo về sự thay đổi trạng thái thiết bị theo yêu cầu, chẳng hạn như khi bu lông khoá cửa được tương tác thành công hoặc bị kẹt.

Hành động smart home 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ó 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: 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 lệnh thiết bị được gửi từ loa thông minh và màn hình thông minh.

Assistant gửi 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 mọi 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, quá trình thực hiện Hành động của bạn sẽ gửi một yêu cầu thông báo đến Google. Các đặc điểm thiết bị mà Hành động smart home hỗ trợ 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 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 Hành động nhà thông minh

Thêm thông báo vào Hành động smart home của bạn theo 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 Report State và lệnh gọi Thông báo.

Các phần sau đây sẽ trình bày chi tiết hơn về các 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 khả năng để người dùng bật/tắt các thông báo một cách rõ ràng qua thiết bị, chẳng hạn như qua 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ị 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 thiết lập và quản lý thiết bị phụ, 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 Google HomeGraph API

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

   Truy cập trang API HomeGraph
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ạo khoá tài khoản dịch vụ.

   Chuyển đến trang Tạo khoá tài khoản dịch vụ
2. Trong danh sách Tài khoản dịch vụ, hãy chọn Tài khoản dịch vụ mới.
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ã.

5. Trong danh sách Vai trò, hãy chọn Tài khoản dịch vụ > Người tạo mã thông báo tài khoản dịch vụ.

6. Đối với Loại khoá, hãy chọn JSON.

7. 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ộ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 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 để thiết lập 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 nối tiếp

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

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 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 đang 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, chọn một tuỳ chọn từ 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 Truy cập nhật ký sự kiện bằng tính năng Ghi nhật ký trê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).