Notifikasi untuk Action smart home

Notifikasi memungkinkan Action smart home Anda digunakan Google Assistant untuk berkomunikasi dengan pengguna tentang peristiwa atau perubahan yang terkait dengan perangkat. Anda dapat menerapkan notifikasi untuk pemberitahuan kepada pengguna untuk mengetahui peristiwa perangkat yang tepat waktu, misalnya saat seseorang ada di depan pintu, atau melaporkan perubahan status perangkat yang diminta, seperti saat baut kunci pintu memiliki telah berhasil terlibat atau macet.

Tindakan smart home Anda dapat mengirimkan jenis notifikasi untuk pengguna:

• Notifikasi proaktif: Memberi tahu pengguna tentang smart home peristiwa perangkat 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 notifikasi ini untuk perintah perangkat yang membutuhkan waktu untuk diselesaikan. Tanggapan tindak lanjut hanya didukung saat permintaan perintah perangkat dikirim dari smart speaker dan smart layar.

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, pemenuhan Action Anda akan mengirimkan permintaan notifikasi ke Google. Perangkat menunjukkan bahwa Action smart home 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 Action smart home

Tambahkan notifikasi ke Tindakan smart home Anda dalam tahap ini:

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

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

Tunjukkan apakah notifikasi diaktifkan di aplikasi Anda

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

Beri tahu 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 Anda, kirimkan salah satu pembaruan berikut:

• Jika pengguna secara eksplisit mengaktifkan/menonaktifkan notifikasi di aplikasi perangkat, atau jika Anda tidak menyediakan opsi beralih, setel devices.notificationSupportedByAgent ke true.
• Jika pengguna secara eksplisit menonaktifkan notifikasi di aplikasi perangkat Anda, atur devices.notificationSupportedByAgent ke false.

Cuplikan berikut menunjukkan contoh cara menetapkan respons SYNC:

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

Kirim permintaan notifikasi ke Google

Untuk memicu notifikasi di Assistant, fulfillment akan 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 Create service account key.

   Buka halaman Create Service Account Key
2. Dari daftar Service account, pilih Akun layanan baru.
3. Di kolom Nama akun layanan, masukkan nama.
4. Di kolom ID akun layanan, masukkan ID.

5. Dari daftar Role, pilih Service Accounts > Service Account Token Creator Google.

6. Untuk Jenis kunci, pilih opsi JSON.

7. Klik Buat. File JSON yang berisi kunci Anda {i>download<i} ke komputer Anda.

Mengirim notifikasi

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

Di objek notifications yang Anda teruskan dalam panggilan API, sertakan sebuah Nilai priority yang menentukan cara notifikasi harus ditampilkan. Nama Objek notifications dapat menyertakan kolom yang berbeda, bergantung pada perangkatnya karakteristik.

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

• Mengirim payload notifikasi proaktif
• Kirim 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);
    

Kirim payload respons tindak lanjut

{i>Payload<i} untuk respons tindak lanjut berisi status permintaan, {i>error<i} kode untuk kegagalan peristiwa, jika berlaku, dan followUpToken yang valid, yang disediakan selama permintaan intent EXECUTE. followUpToken harus digunakan dalam waktu lima menit agar tetap valid dan untuk mengaitkan respons dengan benar dengan 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 membuat output notifikasi hanya di perangkat tempat asal interaksi pengguna, dan bukan siaran ke seluruh 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 Mengakses log peristiwa dengan Cloud Logging. Log ini berguna untuk menguji dan mempertahankan kualitas notifikasi dalam Action 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 Action yang memiliki belum diluncurkan ke jalur produksi.

Contoh status mencakup:

Selain status umum yang dapat diterapkan ke semua notifikasi, kolom status juga dapat menyertakan status spesifik per karakteristik jika berlaku (misalnya, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).