การแจ้งเตือนสำหรับการดำเนินการในบ้านอัจฉริยะ

การแจ้งเตือนช่วยให้การผสานรวม Cloud-to-cloud ของคุณใช้ Google Assistant เพื่อสื่อสารกับผู้ใช้เกี่ยวกับเหตุการณ์หรือการเปลี่ยนแปลงที่สำคัญเกี่ยวกับอุปกรณ์ได้ คุณสามารถใช้การแจ้งเตือนเพื่อแจ้งเตือนผู้ใช้เกี่ยวกับเหตุการณ์ของอุปกรณ์ที่เกิดขึ้นอย่างทันท่วงที เช่น เมื่อมีคนอยู่ที่ประตู หรือเพื่อรายงานการเปลี่ยนแปลงสถานะอุปกรณ์ที่ขอ เช่น เมื่อกลอนล็อกประตูทำงานสำเร็จหรือติดขัด

การผสานรวม Cloud-to-cloud ของคุณสามารถส่งการแจ้งเตือนประเภทต่อไปนี้ให้แก่ผู้ใช้ได้

• การแจ้งเตือนเชิงรุก: แจ้งเตือนผู้ใช้เกี่ยวกับเหตุการณ์ของอุปกรณ์ smart home โดยที่ผู้ใช้ไม่ได้ส่งคำขอไปยังอุปกรณ์ก่อน เช่น เสียงกริ่งประตู

• การตอบกลับเพื่อติดตามผล: การยืนยันว่าคำขอคำสั่งอุปกรณ์สำเร็จหรือล้มเหลว เช่น เมื่อล็อกประตู ใช้การแจ้งเตือนเหล่านี้สำหรับคำสั่งอุปกรณ์ที่ใช้เวลาดำเนินการนาน ระบบจะรองรับการตอบกลับเพื่อติดตามผลก็ต่อเมื่อมีการส่งคำขอคำสั่งอุปกรณ์จากลำโพงอัจฉริยะและจออัจฉริยะเท่านั้น

Assistant จะส่งการแจ้งเตือนเหล่านี้ให้ผู้ใช้เป็นประกาศในลำโพงอัจฉริยะและจออัจฉริยะ การแจ้งเตือนเชิงรุกจะปิดอยู่โดยค่าเริ่มต้น ผู้ใช้สามารถเปิดหรือปิดการแจ้งเตือนเชิงรุกทั้งหมดจาก Google Home app (GHA) ได้

เหตุการณ์ที่ทริกเกอร์การแจ้งเตือน

เมื่อเกิดเหตุการณ์ในอุปกรณ์ การดำเนินการของคุณจะส่งคำขอการแจ้งเตือนไปยัง Google ลักษณะของอุปกรณ์ที่การผสานรวม Cloud-to-cloud ของคุณรองรับจะเป็นตัวกำหนดประเภทของเหตุการณ์การแจ้งเตือนที่พร้อมใช้งานและข้อมูลที่คุณสามารถรวมไว้ในการแจ้งเตือนเหล่านั้น

ลักษณะต่อไปนี้รองรับการแจ้งเตือนเชิงรุก

ลักษณะต่อไปนี้รองรับคำตอบแบบติดตามผล

อุปกรณ์ทุกประเภทจะรองรับการแจ้งเตือนสำหรับลักษณะที่เกี่ยวข้อง

สร้างการแจ้งเตือนสำหรับการผสานรวมระบบคลาวด์กับคลาวด์

เพิ่มการแจ้งเตือนไปยังการผสานรวม Cloud-to-cloud ในขั้นตอนต่อไปนี้

1. ระบุให้ Google ทราบหากมีการเปิดใช้การแจ้งเตือนจากแอปจัดการอุปกรณ์ smart home ของคุณ หากผู้ใช้เปิดหรือปิดการแจ้งเตือนในแอป ให้ส่งคำขอ SYNC เพื่อแจ้งให้ Google ทราบถึงการเปลี่ยนแปลงของอุปกรณ์
2. เมื่อเกิดเหตุการณ์หรือการเปลี่ยนแปลงสถานะของอุปกรณ์ที่เกี่ยวข้องซึ่งทริกเกอร์การแจ้งเตือน ให้ส่งคำขอการแจ้งเตือนโดยเรียกใช้ API Report State reportStateAndNotification หากสถานะอุปกรณ์มีการเปลี่ยนแปลง คุณสามารถส่งทั้งเพย์โหลดสถานะและการแจ้งเตือนพร้อมกันในการเรียกใช้ Report State และการแจ้งเตือน

ส่วนต่อไปนี้จะอธิบายขั้นตอนเหล่านี้โดยละเอียดยิ่งขึ้น

ระบุว่ามีการเปิดใช้การแจ้งเตือนในแอปหรือไม่

ผู้ใช้เลือกได้ว่าต้องการรับการแจ้งเตือนเชิงรุกหรือไม่โดยเปิดใช้ฟีเจอร์นี้ในGHA ในแอปสำหรับอุปกรณ์ smart home คุณยังสามารถเพิ่มความสามารถให้ผู้ใช้สลับการแจ้งเตือนจากอุปกรณ์อย่างชัดเจนได้ด้วย เช่น จากการตั้งค่าแอป

แจ้งให้ Google ทราบว่ามีการเปิดใช้การแจ้งเตือนสำหรับอุปกรณ์ของคุณโดยทำการเรียก Request SYNC เพื่ออัปเดตข้อมูลอุปกรณ์ คุณควรส่งคำขอ SYNC เช่นนี้ทุกครั้งที่ผู้ใช้เปลี่ยนการตั้งค่านี้ในแอปของคุณ

ในการตอบกลับ SYNC ให้ส่งข้อมูลอัปเดตอย่างใดอย่างหนึ่งต่อไปนี้

• หากผู้ใช้เปิดการแจ้งเตือนอย่างชัดแจ้งในแอปจัดการอุปกรณ์ หรือหากคุณไม่มีตัวเลือกเปิด/ปิด ให้ตั้งค่าพร็อพเพอร์ตี้ devices.notificationSupportedByAgent เป็น true
• หากผู้ใช้ปิดการแจ้งเตือนอย่างชัดแจ้งในแอปจัดการอุปกรณ์ ให้ตั้งค่าพร็อพเพอร์ตี้ devices.notificationSupportedByAgent เป็น false

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างวิธีตั้งค่าการตอบกลับ SYNC

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

ส่งคำขอการแจ้งเตือนไปยัง Google

หากต้องการทริกเกอร์การแจ้งเตือนใน Assistant Fulfillment จะส่งเพย์โหลดการแจ้งเตือนไปยัง Google Home Graph ผ่านการเรียก API Report State และ Notification API

เปิดใช้ Google HomeGraph API

1. ใน Google Cloud Console ให้ไปที่หน้า HomeGraph API

   ไปที่หน้า HomeGraph API
2. เลือกโปรเจ็กต์ที่ตรงกับรหัสโปรเจ็กต์ smart home ของคุณ
3. คลิกเปิดใช้

สร้างคีย์บัญชีบริการ

ทำตามวิธีการต่อไปนี้เพื่อสร้างคีย์บัญชีบริการจาก Google Cloud Console

1. ใน Google Cloud Console ให้ไปที่หน้าบัญชีบริการ

   ไปที่หน้าบัญชีบริการ

   คุณอาจต้องเลือกโปรเจ็กต์ก่อนจึงจะไปที่หน้าบัญชีบริการได้

2. คลิก addCreate service account

3. ป้อนชื่อในช่องชื่อบัญชีบริการ

4. ป้อนรหัสในช่องรหัสบัญชีบริการ

5. ป้อนคำอธิบายในช่องคำอธิบายบัญชีบริการ

6. คลิกสร้างและต่อไป

7. จากเมนูแบบเลื่อนลงบทบาท ให้เลือกบัญชีบริการ > ผู้สร้างโทเค็นข้อมูลประจำตัว OpenID Connect ของบัญชีบริการ

8. คลิกต่อไป

9. คลิกเสร็จสิ้น

10. เลือกบัญชีบริการที่คุณเพิ่งสร้างจากรายการบัญชีบริการ แล้วเลือกจัดการคีย์จากเมนูmore_vert การดำเนินการ

11. เลือกเพิ่มคีย์ > สร้างคีย์ใหม่

12. สําหรับประเภทคีย์ ให้เลือกตัวเลือก JSON

13. คลิกสร้าง ระบบจะดาวน์โหลดไฟล์ JSON ที่มีคีย์ลงในคอมพิวเตอร์

ส่งการแจ้งเตือน

โทรเพื่อขอรับการแจ้งเตือนโดยใช้ API devices.reportStateAndNotification คำขอ JSON ต้องมี eventId ซึ่งเป็นรหัสที่ไม่ซ้ำกันที่แพลตฟอร์มสร้างขึ้นสำหรับเหตุการณ์ที่ทริกเกอร์การแจ้งเตือน eventId ควรเป็นรหัสแบบสุ่มที่แตกต่างกันทุกครั้งที่คุณส่งคำขอการแจ้งเตือน

ในออบเจ็กต์ notifications ที่คุณส่งในการเรียก API ให้ใส่ค่า priority ซึ่งกำหนดวิธีแสดงการแจ้งเตือน ออบเจ็กต์ notifications อาจมีช่องที่แตกต่างกันไปตามลักษณะของอุปกรณ์

ทำตามเส้นทางใดเส้นทางหนึ่งต่อไปนี้เพื่อตั้งค่าเพย์โหลดและเรียกใช้ API

• ส่งเพย์โหลดการแจ้งเตือนเชิงรุก
• ส่งเพย์โหลดการตอบกลับติดตามผล

ส่งเพย์โหลดการแจ้งเตือนเชิงรุก

หากต้องการเรียก API ให้เลือกตัวเลือกจากแท็บใดแท็บหนึ่งต่อไปนี้

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);
    

ส่งเพย์โหลดการตอบกลับเพื่อติดตามผล

เพย์โหลดสำหรับการตอบกลับเพื่อติดตามผลจะมีสถานะของคำขอ รหัสข้อผิดพลาดสำหรับเหตุการณ์ที่ล้มเหลว (หากมี) และ followUpToken ที่ถูกต้องซึ่งระบุไว้ระหว่างคำขอ Intent EXECUTE คุณต้องใช้ followUpToken ภายใน 5 นาทีเพื่อให้ยังคงใช้งานได้และเชื่อมโยงการตอบกลับกับคำขอเดิมอย่างถูกต้อง

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างเพย์โหลดคำขอ EXECUTE ที่มีช่อง 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 ใช้ followUpToken เพื่อแสดงการแจ้งเตือนเฉพาะในอุปกรณ์ที่ผู้ใช้โต้ตอบด้วยในตอนแรก และไม่เผยแพร่ไปยังอุปกรณ์ทั้งหมดของผู้ใช้

หากต้องการเรียก API ให้เลือกตัวเลือกจากแท็บใดแท็บหนึ่งต่อไปนี้

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);
    

การบันทึก

การแจ้งเตือนรองรับการบันทึกเหตุการณ์ตามที่ระบุไว้ในการบันทึกในระบบคลาวด์สำหรับบริการแบบ Cloud-to-Cloud บันทึกเหล่านี้มีประโยชน์สำหรับการทดสอบและรักษาคุณภาพการแจ้งเตือนภายใน การดำเนินการของคุณ

ต่อไปนี้เป็นสคีมาของรายการ notificationLog

ช่อง status มีสถานะต่างๆ ที่อาจบ่งบอกถึงข้อผิดพลาดในเพย์โหลดการแจ้งเตือน บางรายการอาจใช้ได้เฉพาะกับการดำเนินการที่ยังไม่ได้เปิดตัวในเวอร์ชันที่ใช้งานจริง

ตัวอย่างสถานะมีดังนี้

นอกเหนือจากสถานะทั่วไปเหล่านี้ที่ใช้กับการแจ้งเตือนทั้งหมดได้แล้ว ช่อง status อาจรวมสถานะเฉพาะลักษณะด้วย หากมี (เช่น OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING)