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

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

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

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

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

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

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

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

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

Trait ต่อไปนี้รองรับการตอบกลับติดตามผล

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

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

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

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

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

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

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

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

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

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

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

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

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

หากต้องการทริกเกอร์การแจ้งเตือนใน Assistant การดำเนินการตามคำสั่งจะส่งเพย์โหลดการแจ้งเตือนไปยัง Google Home Graph ผ่าน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. คลิกaddสร้างบัญชีบริการ

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 สำหรับ Cloud-to-Cloud บันทึกเหล่านี้มีประโยชน์สำหรับการทดสอบและรักษาคุณภาพการแจ้งเตือนภายใน Action ของคุณ

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

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

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

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