Selamat datang di Pusat Developer Google Home, tujuan baru untuk mempelajari cara mengembangkan tindakan smart home. Catatan: Anda akan terus membuat tindakan di konsol Actions.

Notifikasi untuk Action smart home

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Notifikasi memungkinkan smart home Action to use Google Assistant to communicate with users about important device-related events or changes. You can implement notifications to alert users to timely device events, for example when someone is at the door, or to report on a requested device state change, such as when a door lock bolt has been successfully engaged or has jammed. Anda

Tindakan smart home Anda dapat mengirim jenis notifikasi berikut kepada pengguna:

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

  • Tindak lanjut: Konfirmasi bahwa permintaan perintah perangkat berhasil atau gagal, misalnya saat mengunci pintu. Gunakan notifikasi ini untuk perintah perangkat yang memerlukan waktu lama. Respons lanjutan hanya didukung jika 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, pemenuhan Action Anda akan mengirimkan permintaan notifikasi ke Google. Sifat perangkat yang didukung oleh Tindakan smart home Anda menentukan jenis peristiwa notifikasi yang tersedia dan data yang dapat Anda sertakan dalam notifikasi tersebut.

Ciri-ciri berikut mendukung notifikasi proaktif:

Sifat Acara
Deteksi Objek Objek yang terdeteksi oleh perangkat, seperti saat wajah yang dikenali terdeteksi di pintu. Misalnya: "Alice dan Bob ada di pintu depan".
Siklus Proses Perangkat menyelesaikan siklus. Misalnya: "Siklus mesin cuci telah selesai".
StatusSensor Perangkat mendeteksi status sensor yang didukung. Misalnya: "Pendeteksi asap mendeteksi asap."
Kontrol Suhu Perangkat mencapai titik penyetelan suhu. Misalnya: "Oven telah dipanaskan hingga 350 derajat".
Grup Armada Sistem memasuki status pra-alarm dengan hitung mundur entri, yang dipicu oleh pintu terbuka.
CameraStream Tautkan ke live stream kamera setelah objek atau gerakan terdeteksi oleh perangkat.
Deteksi Gerakan "Bergerak terdeteksi pada pukul 12 siang pada tanggal 1 Juli 2020."

Ciri-ciri berikut mendukung respons tindak lanjut:

Sifat Acara
Grup Armada Status penyelesaian dan perubahan status setelah menjalankan perintah perangkat action.devices.commands.ArmDisarm. Misalnya: "Sistem keamanan telah diaktifkan."
Kunci Buka Kunci Status penyelesaian dan perubahan status setelah menjalankan perintah perangkat action.devices.commands.LockUnlock. Misalnya: "Pintu depan telah dikunci" atau " Pintu depan macet".
Kontrol Jaringan Status penyelesaian dan perubahan status setelah menjalankan perintah perangkat action.devices.commands.TestNetworkSpeed. Misalnya: "Uji kecepatan jaringan Anda telah selesai. Kecepatan download di router kantor saat ini 80,2 Kbps, dan kecepatan upload 9,3 Kbps."
BukaTutup Status penyelesaian dan perubahan status setelah menjalankan perintah perangkat action.devices.commands.OpenClose. Misalnya: "Pintu depan telah dibuka" atau " Pintu depan tidak dapat dibuka".
Memulai Status penyelesaian dan perubahan status setelah menjalankan perintah perangkat action.devices.commands.StartStop. Misalnya: "Penyedot debu dimulai".

Semua jenis perangkat mendukung notifikasi untuk karakteristik yang berlaku.

Membuat notifikasi untuk Action smart home Anda

Tambahkan notifikasi ke Action smart home Anda dalam tahap ini:

  1. Tunjukkan kepada Google jika 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 tersebut.
  2. Saat terjadi peristiwa perangkat atau perubahan status yang relevan yang memicu notifikasi, kirim permintaan notifikasi dengan memanggil Report State reportStateAndNotification API. If the device state changed, you can send both a state and notification payload together in your Report State and Notification call.

Bagian berikut 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. Dalam aplikasi untuk perangkat smart home, Anda juga dapat menambahkan kemampuan bagi pengguna untuk secara eksplisit mengaktifkan notifikasi dari perangkat, misalnya, dari setelan aplikasi Anda.

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

Dalam respons SYNC Anda, kirim salah satu update ini:

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

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

Mengirim permintaan notifikasi ke Google

Untuk memicu notifikasi di Assistant, fulfillment Anda akan mengirim payload notifikasi ke Google Home Graph via a Report State and Notification API call.

Mengaktifkan Google HomeGraph API

  1. Di Google Cloud Console, go to the HomeGraph API page.

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

Membuat Kunci Akun Layanan

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

Catatan: Pastikan Anda menggunakan project GCP yang benar saat melakukan langkah-langkah ini. Ini adalah project yang cocok dengan project ID smart home Anda.

  1. Di Google Cloud Console, buka halaman Create service account key.

    Buka halaman Create Service Account Key
  2. Dari daftar Akun layanan, 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.

  6. Untuk Key type, pilih opsi JSON.

  7. Klik Create. File JSON yang berisi kunci yang 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 dihasilkan oleh platform Anda untuk peristiwa yang memicu notifikasi. eventId harus berupa ID acak yang berbeda setiap kali Anda mengirim permintaan notifikasi.

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

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

Mengirim payload notifikasi proaktif

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

HTTP

Home Graph API menyediakan endpoint HTTP

  1. Gunakan file JSON akun layanan yang didownload untuk membuat Token Web JSON (JWT). Untuk informasi selengkapnya, lihat Mengautentikasi Menggunakan Akun Layanan.
  2. Dapatkan token akses OAuth 2.0 dengan cakupan https://www.googleapis.com/auth/homegraph menggunakan oauth2l:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. Buat permintaan JSON dengan agentUserId. Berikut adalah contoh permintaan JSON untuk Report State dan Notifikasi:
    4. {
  "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
            }
          }
        }
      }
    }
  }
}
  4. Gabungkan Report State dan JSON Notifikasi, serta token dalam permintaan HTTP POST Anda ke endpoint Google Home Graph. Berikut adalah contoh cara membuat permintaan di command line menggunakan curl, sebagai pengujian:
    5. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

gRPC

API Home Graph menyediakan endpoint gRPC

  1. Dapatkan definisi layanan buffering protokol untuk Home Graph API.
  2. Ikuti dokumentasi developer gRPC untuk membuat stub klien untuk salah satu bahasa yang didukung.
  3. Panggil metode ReportStateAndNotification.

Node.js

Klien Node.js Google API menyediakan binding untuk Home Graph API.

  1. Lakukan inisialisasi layanan google.homegraph menggunakan Kredensial Default Aplikasi.
  2. Panggil metode reportStateAndNotification dengan ReportStateAndNotificationRequest. Metode ini menampilkan Promise dengan ReportStateAndNotificationResponse.
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
              }
            }
          }
        }
      }
    }
  }
});

Java

Library Klien HomeGraph API untuk Java menyediakan binding untuk Home Graph API.

  1. Lakukan inisialisasi HomeGraphApiService menggunakan Kredensial Default Aplikasi.
  2. Panggil metode reportStateAndNotification dengan ReportStateAndNotificationRequest. Tindakan ini akan menampilkan ReportStateAndNotificationResponse.
// 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

Payload untuk respons tindak lanjut 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 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 menghasilkan output notifikasi hanya pada perangkat yang awalnya digunakan untuk berinteraksi dengan pengguna, dan tidak disiarkan ke semua perangkat pengguna.

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

HTTP

Home Graph API menyediakan endpoint HTTP

  1. Gunakan file JSON akun layanan yang didownload untuk membuat Token Web JSON (JWT). Untuk informasi selengkapnya, lihat Mengautentikasi Menggunakan Akun Layanan.
  2. Dapatkan token akses OAuth 2.0 dengan cakupan https://www.googleapis.com/auth/homegraph menggunakan oauth2l:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. Buat permintaan JSON dengan agentUserId. Berikut adalah contoh permintaan JSON untuk Report State dan Notifikasi:
    4. {
  "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": "PLACEHOLDER",
              "networkDownloadSpeedMbps": 23.3,
              "networkUploadSpeedMbps": 10.2
            }
          }
        }
      }
    }
  }
}
  4. Gabungkan Report State dan JSON Notifikasi, serta token dalam permintaan HTTP POST Anda ke endpoint Google Home Graph. Berikut adalah contoh cara membuat permintaan di command line menggunakan curl, sebagai pengujian:
    5. curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

gRPC

API Home Graph menyediakan endpoint gRPC

  1. Dapatkan definisi layanan buffering protokol untuk Home Graph API.
  2. Ikuti dokumentasi developer gRPC untuk membuat stub klien untuk salah satu bahasa yang didukung.
  3. Panggil metode ReportStateAndNotification.

Node.js

Klien Node.js Google API menyediakan binding untuk Home Graph API.

  1. Lakukan inisialisasi layanan google.homegraph menggunakan Kredensial Default Aplikasi.
  2. Panggil metode reportStateAndNotification dengan ReportStateAndNotificationRequest. Metode ini menampilkan Promise dengan ReportStateAndNotificationResponse.
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,
              }
            }
          }
        }
      }
    }
  }
});

Java

Library Klien HomeGraph API untuk Java menyediakan binding untuk Home Graph API.

  1. Lakukan inisialisasi HomeGraphApiService menggunakan Kredensial Default Aplikasi
  2. Panggil metode reportStateAndNotification dengan ReportStateAndNotificationRequest. Metode ini menampilkan ReportStateAndNotificationResponse
// 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 dijelaskan dalam Mengakses log peristiwa dengan Cloud Logging. Log ini berguna untuk menguji dan mempertahankan kualitas notifikasi dalam Action Anda.

Berikut adalah skema entri notificationLog:

Properti Deskripsi
requestId ID permintaan notifikasi.
structName Nama struct notifikasi, seperti "ObjectDetection".
status Menunjukkan status notifikasi.

Kolom status menyertakan berbagai status yang mungkin menunjukkan error dalam payload notifikasi. Beberapa di antaranya mungkin hanya tersedia di Action yang belum diluncurkan ke tahap produksi.

Contoh status mencakup:

Status Deskripsi
EVENT_ID_MISSING Menunjukkan bahwa kolom eventId yang wajib diisi tidak ada.
PRIORITY_MISSING Menunjukkan bahwa kolom priority tidak ada.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Menunjukkan bahwa properti notificationSupportedByAgent perangkat notifikasi yang diberikan di SYNC bernilai salah.
NOTIFICATION_ENABLED_BY_USER_FALSE Menunjukkan bahwa pengguna belum mengaktifkan notifikasi pada perangkat notifikasi dalam GHA. Status ini hanya tersedia di Action yang belum diluncurkan ke tahap produksi.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Menunjukkan bahwa pengguna belum menetapkan perangkat notifikasi ke Home/Structure. Status ini hanya tersedia di Action yang belum diluncurkan ke tahap produksi.

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

Sebelumnya
Menerapkan Status Laporan
Berikutnya
Menguji dan membagikan Tindakan