Notifikasi memungkinkan Action smart home 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 ada di depan pintu, atau untuk melaporkan perubahan status perangkat yang diminta, seperti saat baut kunci pintu berhasil dipasang atau macet.
Action smart home Anda dapat mengirim 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 perlu waktu beberapa saat untuk diselesaikan. Respons tindak lanjut 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 memiliki kemampuan untuk 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 Action 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 | Peristiwa |
---|---|
ObjectDetection | Objek yang terdeteksi oleh perangkat, seperti saat wajah yang dikenali terdeteksi di pintu. Misalnya: "Alice dan Bobi ada di pintu depan". |
RunCycle | Perangkat menyelesaikan siklus. Misalnya: "Siklus mesin cuci telah selesai". |
SensorState | Perangkat mendeteksi status sensor yang didukung. Misalnya: "Pendeteksi asap mendeteksi asap". |
TemperatureControl | Perangkat mencapai titik penyetelan suhu. Misalnya: "Oven telah dipanaskan hingga 350 derajat". |
ArmDisarm | Sistem memasuki status pra-alarm dengan hitung mundur masuk, yang dipicu oleh pintu yang terbuka. |
CameraStream | Menautkan ke live stream kamera setelah objek atau gerakan terdeteksi oleh perangkat. |
MotionDetection | "Gerakan terdeteksi pukul 12.00 pada 1 Juli 2020". |
Ciri-ciri berikut mendukung respons tindak lanjut:
Sifat | Peristiwa |
---|---|
ArmDisarm | Status penyelesaian dan perubahan status setelah eksekusi
perintah perangkat action.devices.commands.ArmDisarm . Misalnya:
"Sistem keamanan telah aktif".
|
LockUnlock | Status penyelesaian dan perubahan status setelah eksekusi
perintah perangkat action.devices.commands.LockUnlock . Misalnya: "pintu depan telah dikunci" atau "pintu depan macet".
|
NetworkControl | Status penyelesaian dan perubahan status setelah eksekusi
perintah perangkat action.devices.commands.TestNetworkSpeed . Misalnya: "Uji kecepatan jaringan Anda telah selesai. Kecepatan download di
router kantor saat ini adalah 80,2 Kbps, dan kecepatan upload 9,3 Kbps."
|
OpenClose | Status penyelesaian dan perubahan status setelah eksekusi
perintah perangkat action.devices.commands.OpenClose . Misalnya: "pintu depan telah terbuka" atau "pintu depan tidak dapat dibuka".
|
StartStop | Status penyelesaian dan perubahan status setelah eksekusi
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:
- 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. - Saat terjadi peristiwa atau perubahan status perangkat yang relevan yang memicu
notifikasi, kirim permintaan notifikasi dengan memanggil
Report State
reportStateAndNotification
API. Jika status perangkat berubah, Anda dapat mengirim status dan payload notifikasi secara bersamaan dalam panggilan Report State dan Notifikasi.
Bagian berikut 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 secara opsional menambahkan kemampuan bagi pengguna untuk secara eksplisit mengalihkan notifikasi dari perangkat, misalnya, dari setelan aplikasi Anda.
Tunjukkan kepada Google bahwa notifikasi diaktifkan untuk perangkat Anda dengan melakukan
panggilan Request SYNC
untuk mengupdate 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 pembaruan berikut:
- Jika pengguna secara eksplisit mengaktifkan notifikasi di aplikasi perangkat Anda, atau jika Anda
tidak memberikan opsi tombol, setel
properti
devices.notificationSupportedByAgent
ketrue
. - Jika pengguna secara eksplisit menonaktifkan notifikasi di aplikasi perangkat Anda, tetapkan
properti
devices.notificationSupportedByAgent
kefalse
.
Cuplikan berikut menampilkan contoh cara menetapkan respons SYNC:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Kirim 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
-
Di Google Cloud Console, buka halaman HomeGraph API.
Buka halaman HomeGraph API - Pilih project yang cocok dengan project ID smart home Anda.
- Klik ENABLE.
Membuat Kunci Akun Layanan
Ikuti petunjuk ini untuk membuat kunci akun layanan dari Google Cloud Console:
-
Di Google Cloud Console, buka halaman Create service account key.
Buka halaman Create Service Account Key - Dari daftar Service account, pilih New service account.
- Di kolom Nama akun layanan, masukkan nama.
- Di kolom ID akun layanan, masukkan ID.
Dari daftar Role, pilih Service Accounts > Service Account Token Creator.
Untuk Jenis kunci, pilih opsi JSON.
- Klik Create. File JSON yang berisi kunci yang didownload ke komputer Anda.
Mengirim notifikasi
Lakukan panggilan permintaan notifikasi menggunakan
devices.reportStateAndNotification
API.
Permintaan JSON 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.
Pada objek notifications
yang Anda teruskan dalam panggilan API, sertakan
nilai priority
yang menentukan cara notifikasi 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
Untuk memanggil API, pilih opsi dari salah satu tab berikut:
HTTP
Home Graph API menyediakan endpoint HTTP
- Gunakan file JSON akun layanan yang didownload untuk membuat Token Web JSON (JWT). Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi Menggunakan Akun Layanan.
- Dapatkan token akses OAuth 2.0 dengan cakupan
https://www.googleapis.com/auth/homegraph
menggunakan oauth2l: - Buat permintaan JSON dengan
agentUserId
. Berikut adalah contoh permintaan JSON untuk Report State dan Notifikasi: - Gabungkan Report State dan Notification JSON serta token dalam permintaan HTTP POST
Anda ke endpoint Google Home Graph. Berikut adalah contoh cara
membuat permintaan dalam command line menggunakan
curl
, sebagai pengujian:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
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
Home Graph API menyediakan endpoint gRPC
- Dapatkan definisi layanan buffering protokol untuk Home Graph API.
- Ikuti dokumentasi developer gRPC untuk membuat stub klien untuk salah satu bahasa yang didukung.
- Panggil metode ReportStateAndNotification.
Node.js
Klien Node.js Google API menyediakan binding untuk Home Graph API.
- Lakukan inisialisasi layanan
google.homegraph
menggunakan Kredensial Default Aplikasi. - Panggil metode
reportStateAndNotification
dengan ReportStateAndNotificationRequest. Metode ini menampilkanPromise
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.
- Lakukan inisialisasi
HomeGraphApiService
menggunakan Kredensial Default Aplikasi. - Panggil metode
reportStateAndNotification
denganReportStateAndNotificationRequest
. Metode ini akan menampilkanReportStateAndNotificationResponse
.
// 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
valid, yang diberikan 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 menghasilkan notifikasi hanya di perangkat
yang awalnya berinteraksi dengan pengguna, dan bukan ke seluruh
perangkat pengguna.
Untuk memanggil API, pilih opsi dari salah satu tab berikut:
HTTP
Home Graph API menyediakan endpoint HTTP
- Gunakan file JSON akun layanan yang didownload untuk membuat Token Web JSON (JWT). Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi Menggunakan Akun Layanan.
- Dapatkan token akses OAuth 2.0 dengan cakupan
https://www.googleapis.com/auth/homegraph
menggunakan oauth2l: - Buat permintaan JSON dengan
agentUserId
. Berikut adalah contoh permintaan JSON untuk Report State dan Notifikasi: - Gabungkan Report State dan Notification JSON serta token dalam permintaan HTTP POST
Anda ke endpoint Google Home Graph. Berikut adalah contoh cara
membuat permintaan dalam command line menggunakan
curl
, sebagai pengujian:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
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
Home Graph API menyediakan endpoint gRPC
- Dapatkan definisi layanan buffering protokol untuk Home Graph API.
- Ikuti dokumentasi developer gRPC untuk membuat stub klien untuk salah satu bahasa yang didukung.
- Panggil metode ReportStateAndNotification.
Node.js
Klien Node.js Google API menyediakan binding untuk Home Graph API.
- Lakukan inisialisasi layanan
google.homegraph
menggunakan Kredensial Default Aplikasi. - Panggil metode
reportStateAndNotification
dengan ReportStateAndNotificationRequest. Metode ini menampilkanPromise
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.
- Lakukan inisialisasi
HomeGraphApiService
menggunakan Kredensial Default Aplikasi - Panggil metode
reportStateAndNotification
denganReportStateAndNotificationRequest
. Metode ini menampilkanReportStateAndNotificationResponse
// 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 sebagaimana 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 struktur notifikasi, seperti "ObjectDetection". |
status |
Menunjukkan status notifikasi. |
Kolom status
mencakup berbagai status yang dapat menunjukkan error dalam payload notifikasi. Beberapa di antaranya mungkin hanya tersedia di Action yang
belum diluncurkan ke produksi.
Contoh status mencakup:
Status | Deskripsi |
---|---|
EVENT_ID_MISSING |
Menunjukkan bahwa kolom eventId yang diperlukan tidak ada.
|
PRIORITY_MISSING |
Menunjukkan bahwa kolom priority tidak ada.
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Menunjukkan bahwa properti notificationSupportedByAgent perangkat yang memberi tahu, yang diberikan di SYNC adalah salah.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Menunjukkan bahwa pengguna belum mengaktifkan notifikasi pada perangkat yang memberi tahu di GHA. Status ini hanya tersedia di Action yang belum diluncurkan ke jalur produksi. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Menunjukkan bahwa pengguna belum menetapkan perangkat yang memberitahukan ke Rumah/Struktur. Status ini hanya tersedia di Action yang belum diluncurkan ke jalur produksi. |
Selain status umum berikut yang dapat diterapkan ke semua notifikasi, kolom status
juga dapat menyertakan status khusus trait jika berlaku (misalnya, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).