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 depan pintu, atau untuk melaporkan perubahan status perangkat yang diminta, seperti saat gerendel kunci pintu telah berhasil diaktifkan atau macet.

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

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

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

Assistant memberikan notifikasi ini kepada pengguna sebagai pengumuman di smart speaker 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, fulfillment Anda akan mengirimkan permintaan notifikasi ke Google. Sifat perangkat yang didukung oleh integrasi Cloud-to-cloud Anda menentukan jenis peristiwa notifikasi yang tersedia dan data yang dapat Anda sertakan dalam notifikasi tersebut.

Sifat berikut mendukung notifikasi proaktif:

Sifat berikut mendukung respons tindak lanjut:

Semua jenis perangkat mendukung notifikasi untuk karakteristik yang berlaku.

Membuat notifikasi untuk integrasi Cloud ke cloud Anda

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

1. Tunjukkan kepada Google jika notifikasi diaktifkan dari smart home aplikasi perangkat Anda. Jika pengguna mengaktifkan atau menonaktifkan notifikasi di aplikasi Anda, kirim permintaan SYNC untuk memberi tahu Google tentang perubahan perangkat.
2. Saat terjadi peristiwa atau perubahan status perangkat yang relevan dan memicu notifikasi, kirim permintaan notifikasi dengan memanggil Report State reportStateAndNotification API. 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 mendetail.

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 secara eksplisit dari perangkat, misalnya, dari setelan aplikasi.

Tunjukkan kepada Google bahwa notifikasi diaktifkan untuk perangkat Anda dengan melakukan panggilan Minta 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 pembaruan berikut:

• Jika pengguna secara eksplisit mengaktifkan notifikasi di aplikasi perangkat, atau jika Anda tidak menyediakan opsi beralih, 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 menetapkan respons SYNC:

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

Mengirim permintaan notifikasi ke Google

Untuk memicu notifikasi di Assistant, fulfillment 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 berikut 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 Service Accounts.

2. Klik addCreate service account.

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, lalu pilih Manage keys dari menu more_vert Actions.

11. Pilih Add key > Create new key.

12. Untuk Key type, pilih opsi JSON.

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

Mengirim notifikasi

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

Dalam objek notifications yang Anda teruskan dalam panggilan API, sertakan nilai priority yang menentukan cara notifikasi harus ditampilkan. Objek notifications Anda dapat menyertakan kolom yang berbeda, bergantung pada karakteristik perangkat.

Ikuti salah satu jalur berikut untuk menetapkan payload dan memanggil API:

• Mengirim payload notifikasi proaktif
• Mengirim payload respons tindak lanjut

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 tindak lanjut

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

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 logging peristiwa seperti yang diuraikan dalam Logging cloud untuk Cloud-to-cloud. Log ini berguna untuk menguji dan menjaga kualitas notifikasi dalam Action Anda.

Berikut adalah skema entri notificationLog:

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

Contoh status mencakup:

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