Notifikasi untuk Action smart home

Notifikasi memungkinkan integrasi Cloud-to-cloud Anda menggunakan Google Assistant untuk berkomunikasi dengan pengguna tentang peristiwa atau perubahan penting terkait perangkat. Anda dapat menerapkan notifikasi untuk memberi tahu pengguna tentang peristiwa perangkat yang tepat waktu, misalnya saat seseorang berada di pintu, atau untuk melaporkan perubahan status perangkat yang diminta, seperti saat baut smart lock pintu berhasil dipasang atau macet.

Integrasi Cloud-to-cloud Anda dapat mengirimkan jenis notifikasi berikut kepada pengguna:

• Notifikasi proaktif: Memberi tahu pengguna tentang smart home peristiwa perangkat tanpa permintaan pengguna sebelumnya ke perangkat mereka, seperti bel pintu berdering.

• Respons lanjutan: Konfirmasi bahwa permintaan perintah perangkat berhasil atau gagal, misalnya saat mengunci pintu. Gunakan pemberitahuan ini untuk perintah perangkat yang memerlukan waktu untuk diselesaikan. Respons lanjutan hanya didukung saat permintaan perintah perangkat dikirim dari speaker smart dan layar smart.

Assistant memberikan notifikasi ini kepada pengguna sebagai pengumuman di speaker smart dan layar smart. Notifikasi proaktif dinonaktifkan secara default. Pengguna dapat mengaktifkan atau menonaktifkan semua notifikasi proaktif dari Google Home app (GHA).

Peristiwa yang memicu notifikasi

Saat peristiwa perangkat terjadi, pemenuhan Anda akan mengirim permintaan notifikasi ke Google. Trait perangkat yang didukung oleh integrasi Cloud-to-cloud Anda menentukan jenis peristiwa notifikasi yang tersedia dan data yang dapat Anda sertakan dalam notifikasi tersebut.

Ciri berikut mendukung notifikasi proaktif:

Ciri berikut mendukung respons lanjutan:

Semua jenis perangkat mendukung notifikasi untuk trait yang berlaku.

Membangun notifikasi untuk integrasi Cloud-to-cloud

Tambahkan notifikasi ke integrasi Cloud-to-cloud Anda pada tahap berikut:

1. Tunjukkan kepada Google apakah notifikasi diaktifkan dari aplikasi perangkat smart home Anda. Jika pengguna mengaktifkan atau menonaktifkan notifikasi di aplikasi Anda, kirim permintaan SYNC untuk memberi tahu Google tentang perubahan perangkat.
2. Saat peristiwa perangkat atau perubahan status yang relevan terjadi dan memicu notifikasi, kirim permintaan notifikasi dengan memanggil API Report State reportStateAndNotification. Jika status perangkat berubah, Anda dapat mengirimkan payload status dan notifikasi bersama-sama dalam panggilan Report State dan Notifikasi.

Bagian berikut akan membahas langkah-langkah ini secara lebih detail.

Menunjukkan apakah notifikasi diaktifkan di aplikasi Anda

Pengguna dapat memilih apakah mereka ingin menerima notifikasi proaktif dengan mengaktifkan fitur ini di GHA. Di aplikasi untuk perangkat smart home, Anda juga dapat menambahkan kemampuan bagi pengguna untuk mengaktifkan/menonaktifkan notifikasi dari perangkat secara eksplisit, misalnya, dari setelan aplikasi Anda.

Tunjukkan kepada Google bahwa notifikasi diaktifkan untuk perangkat Anda dengan melakukan panggilan Request SYNC untuk memperbarui data perangkat. Anda harus mengirim permintaan SYNC seperti ini setiap kali pengguna mengubah setelan ini di aplikasi Anda.

Dalam respons SYNC, kirim salah satu info terbaru berikut:

• Jika pengguna secara eksplisit mengaktifkan notifikasi di aplikasi perangkat Anda, atau jika Anda tidak menyediakan opsi tombol, tetapkan properti devices.notificationSupportedByAgent ke true.
• Jika pengguna secara eksplisit menonaktifkan notifikasi di aplikasi perangkat Anda, tetapkan properti devices.notificationSupportedByAgent ke false.

Cuplikan berikut menunjukkan contoh cara menyetel respons SYNC Anda:

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

Mengirim permintaan notifikasi ke Google

Untuk memicu notifikasi di Assistant, pemenuhan Anda mengirimkan payload notifikasi ke Google Home Graph melalui panggilan Report State dan Notification API.

Mengaktifkan Google HomeGraph API

1. Di Google Cloud Console, buka halaman HomeGraph API.

   Buka halaman HomeGraph API
2. Pilih project yang cocok dengan project ID smart home Anda.
3. Klik ENABLE.

Membuat Kunci Akun Layanan

Ikuti petunjuk ini untuk membuat kunci akun layanan dari Google Cloud Console:

1. Di Google Cloud Console, buka halaman Service accounts.

   Buka halaman Service Accounts.

   Anda mungkin perlu memilih project sebelum diarahkan ke halaman Akun Layanan.

2. Klik addBuat akun layanan.

3. Di kolom Nama akun layanan, masukkan nama.

4. Di kolom Service account ID, masukkan ID.

5. Di kolom Deskripsi akun layanan, masukkan sebuah deskripsi.

6. Klik Buat dan lanjutkan.

7. Dari dropdown Role, pilih Service Accounts > Service Account OpenID Connect Identity Token Creator.

8. Klik Lanjutkan.

9. Klik Selesai.

10. Pilih akun layanan yang baru saja Anda buat dari daftar akun layanan dan pilih Kelola kunci dari menu more_vert Tindakan.

11. Pilih Tambahkan kunci > Buat kunci baru.

12. Untuk Jenis kunci, pilih opsi JSON.

13. Klik Buat. File JSON yang berisi kunci Anda akan didownload ke komputer Anda.

Mengirim notifikasi

Lakukan panggilan permintaan notifikasi menggunakan devices.reportStateAndNotification API. Permintaan JSON Anda harus menyertakan eventId, yang merupakan ID unik yang dibuat oleh platform Anda untuk peristiwa yang memicu notifikasi. eventId harus berupa ID acak yang berbeda setiap kali Anda mengirim permintaan notifikasi.

Di objek notifications yang Anda teruskan dalam panggilan API, sertakan nilai priority yang menentukan cara menampilkan notifikasi. Objek notifications Anda dapat menyertakan kolom yang berbeda, bergantung pada sifat perangkat.

Ikuti salah satu jalur ini untuk menyetel payload dan memanggil API:

• Mengirim payload notifikasi proaktif
• Mengirim payload respons lanjutan

Mengirim payload notifikasi proaktif

Untuk memanggil API, pilih opsi dari salah satu tab berikut:

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

Mengirim payload respons lanjutan

Payload untuk respons lanjutan berisi status permintaan, kode error untuk kegagalan peristiwa, jika berlaku, dan followUpToken yang valid, yang diberikan selama permintaan intent EXECUTE. followUpToken harus digunakan dalam waktu lima menit agar tetap valid dan untuk mengaitkan respons dengan benar ke permintaan asli.

Cuplikan berikut menunjukkan contoh payload permintaan EXECUTE dengan kolom 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 menggunakan followUpToken untuk menampilkan notifikasi hanya di perangkat yang awalnya digunakan pengguna untuk berinteraksi, dan tidak menyiarkannya ke semua perangkat pengguna.

Untuk memanggil API, pilih opsi dari salah satu tab berikut:

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

Logging

Notifikasi mendukung pencatatan peristiwa seperti yang diuraikan dalam Cloud Logging untuk Cloud-to-Cloud. Log ini berguna untuk menguji dan menjaga kualitas notifikasi dalam Tindakan Anda.

Berikut adalah skema entri notificationLog:

Kolom status mencakup berbagai status yang dapat menunjukkan error dalam payload notifikasi. Beberapa di antaranya mungkin hanya tersedia di Tindakan yang belum diluncurkan ke produksi.

Contoh status mencakup:

Selain status umum yang dapat berlaku untuk semua notifikasi ini, kolom status juga dapat menyertakan status khusus sifat jika berlaku (misalnya, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).