Jika perangkat atau permintaan tidak berfungsi sesuai yang diharapkan, penting untuk memberikan penanganan dan komunikasi error yang baik bagi pengguna agar mereka memahami apa yang terjadi, dan jika memungkinkan, cara memperbaikinya. Pastikan Anda memikirkan kemungkinan skenario kegagalan dan bagaimana perangkat Anda akan merespons: Bagaimana jika pengguna mengganggu tugas yang sedang berlangsung? Bagaimana jika pengguna meminta tindakan dari perangkat saat offline? Merencanakan untuk mengatasi masalah ini dan membantu pengguna pulih dari masalah ini dapat menghindari kebingungan pengguna dan menciptakan pengalaman yang lebih berkualitas untuk perangkat Anda.
Panduan ini menyediakan beberapa contoh respons intent yang menangani error. Lihat Error dan pengecualian untuk meninjau nilai errorCode
yang valid untuk error dan pengecualian.
Contoh 1: Respons error untuk intent EXECUTE
Pengguna akhir memiliki dua lampu smart dan diinstal di ruang keluarga. Pengguna
memberikan perintah "nyalakan lampu ruang keluarga" dan Google mengirimkan intent EXECUTE
ke URL fulfillment Anda. Anda mendapati bahwa perangkat pengguna sedang offline
dan tidak dapat dikontrol, sehingga fulfillment Anda menampilkan respons EXECUTE
dengan
status
ERROR
dan errorCode
deviceOffline
.
Contoh ini menunjukkan cara menampilkan respons EXECUTE
dengan
errorCode
dari perangkat lampu seperti yang dijelaskan sebelumnya:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "light-device-id-1" ], "status": "ERROR", "errorCode": "deviceOffline" }, { "ids": [ "light-device-id-2" ], "status": "ERROR", "errorCode": "deviceOffline" } ] } }
Google Assistant akan meminta pengguna mengucapkan "device
saat ini tidak tersedia" setelah menerima respons. Ingat bahwa Anda masih
perlu mengirim status offline untuk perangkat dalam status laporan setelah mengirim
errorCode
deviceOffline
dalam respons EXECUTE
.
Contoh 2: Pengecualian non-pemblokiran untuk intent EXECUTE
Pengguna mencoba mengunci smart lock-nya di pintu depan menggunakan perangkat dengan
Assistant. Anda dapat mengontrol kunci mereka dengan sukses, tetapi
menemukan baterai perangkat lemah, sehingga fulfillment Anda menampilkan respons EXECUTE
dengan status
SUCCESS
dan exceptionCode
lowBattery
.
Contoh ini menunjukkan cara mengirim respons EXECUTE
dengan
exceptionCode
dari perangkat kunci seperti yang dijelaskan sebelumnya:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["lock-device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isLocked": true, "isJammed": false, "exceptionCode": "lowBattery" } }] } }
Assistant akan meminta pengguna yang mengucapkan "perangkat kehabisan baterai" setelah menerima respons.
Contoh 3: Notifikasi error proaktif
Dalam beberapa kasus, ada baiknya untuk memberi tahu pengguna tentang error, terutama untuk fungsi yang diharapkan selesai secara otomatis oleh pengguna. Untuk karakteristik yang mendukung notifikasi proaktif, Anda dapat memberi tahu pengguna secara proaktif saat terjadi error jika Anda telah menerapkan notifikasi proaktif smart home.
Pengering smart sedang berjalan, dan seseorang akan membuka pintu sebelum siklus selesai.
Anda dapat memanggil metode Google Home Graph API
reportStateAndNotifications
untuk mengirim notifikasi proaktif dengan
errorCode
:
Contoh ini menunjukkan cara mengirim notifikasi proaktif dengan
errorCode
dari perangkat pengering seperti yang dijelaskan sebelumnya:
POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id", "eventId": "unique-event-id", "payload": { "devices": { "notifications": { "dryer-device-id": { "RunCycle": { "priority": 0, "status": "FAILURE", "errorCode": "deviceDoorOpen" } } }, "states": { "dryer-device-id": { "isRunning": false, "isPaused": true } } } } }
Assistant akan meminta pengguna melihat pesan "pintu perangkat terbuka" setelah menerima notifikasi. Anda dapat mengirim status perangkat yang sesuai bersama notifikasi dalam payload yang sama.
Contoh 4: Notifikasi tindak lanjut
Untuk perintah fitur yang mendukung notifikasi tindak lanjut, Anda dapat mengirim notifikasi tindak lanjut kepada pengguna saat terjadi error atau pengecualian, jika Anda telah menerapkan smart home notifikasi tindak lanjut.
Pengguna mengeluarkan perintah untuk menutup pintu garasi, tetapi pintu macet
saat ditutup. Anda dapat mengirim notifikasi tindak lanjut dengan errorCode
:
POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id", "eventId": "unique-event-id", "payload": { "devices": { "notifications": { "door-device-id": { "LockUnlock": { "priority": 0, "followUpResponse": { "status": "FAILURE", "errorCode": "deviceJammingDetected", "followUpToken": "follow-up-token-1" } } } }, "states": { "door-device-id": { "openPercent": 70 } } } } }
Assistant akan meminta pengguna mengucapkan "perangkat bermasalah" setelah menerima notifikasi. Anda dapat mengirim status perangkat yang sesuai dengan notifikasi dalam payload yang sama.
Untuk informasi selengkapnya dan detail errorCodes
, lihat dokumentasi referensi Error dan pengecualian.