Cihazlar veya istekler beklendiği gibi çalışmadığında, kullanıcılarınıza iyi bir hata işleme ve iletişim sağlamak önemlidir. Böylece kullanıcılar ne olduğunu ve mümkün olduğunda nasıl düzelteceklerini anlayabilirler. Olası hata senaryolarını ve cihazınızın nasıl yanıt vermesi gerektiğini iyice düşünün: Kullanıcı devam eden bir görevi yarıda keserse ne olur? Kullanıcı, çevrimdışı bir cihazdan işlem yapmasını isterse ne olur? Bu sorunları önceden planlamak ve kullanıcınızın bu sorunları çözmesine yardımcı olmak, kullanıcının hayal kırıklığı yaşamasını önleyebilir ve cihazlarınız için daha yüksek kaliteli bir deneyim oluşturabilir.
Bu kılavuzda, hataları işleyen intent yanıtlarına dair bazı örnekler verilmiştir. Hata ve istisnalar için geçerli errorCode değerlerini incelemek üzere Hatalar ve istisnalar bölümüne bakın.
1. örnek: EXECUTE amacı için hata yanıtı
Bir son kullanıcının oturma odasında iki akıllı ışık var. Kullanıcı "Oturma odasının ışıklarını aç" komutunu verir ve Google, karşılama URL'nize bir EXECUTE intent'i gönderir. Kullanıcının cihazlarının çevrimdışı olduğunu ve kontrol edilemediğini tespit ettiniz. Bu nedenle, karşılamanız status ERROR ve errorCode deviceOffline ile bir EXECUTE yanıtı döndürür.
Bu örnekte, daha önce açıklandığı gibi hafif bir cihazdan errorCode içeren bir EXECUTE yanıtının nasıl döndürüleceği gösterilmektedir:
{ "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, yanıtı aldıktan sonra kullanıcıya "Cihaz şu anda kullanılamıyor" mesajını gösterir. EXECUTE yanıtında errorCode deviceOffline gönderdikten sonra, cihazların çevrimdışı durumunu rapor durumunda göndermeniz gerektiğini unutmayın.
2. örnek: EXECUTE niyeti için engelleyici olmayan istisna
Bir kullanıcı, Assistant kullanarak ön kapısındaki akıllı kilidi kilitlemeye çalışıyor. Kullanıcının kilidini başarıyla kontrol edebiliyorsunuz ancak cihazın pil seviyesi düşük olduğu için yerine getirme işleminiz status SUCCESS ve exceptionCode lowBattery ile EXECUTE yanıtı döndürüyor.
Bu örnekte, daha önce açıklandığı gibi kilitli bir cihazdan exceptionCode içeren bir EXECUTE yanıtının nasıl gönderileceği gösterilmektedir:
{ "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, yanıtı aldıktan sonra kullanıcıya "Cihazın pili azaldı" uyarısını gösterir.
3. örnek: Proaktif hata bildirimleri
Bazı durumlarda, özellikle kullanıcıların otomatik olarak tamamlanmasını beklediği işlevlerde kullanıcıları bir hata konusunda uyarmak faydalı olabilir. Proaktif bildirimleri destekleyen özellikler için smart home proaktif bildirimleri uyguladıysanız hata oluştuğunda kullanıcıyı proaktif olarak bilgilendirebilirsiniz.
Akıllı kurutma makinesi çalışırken birisi program bitmeden kapağı açıyor.
errorCode ile proaktif bildirim göndermek için Google Home Graph API
reportStateAndNotifications yöntemini çağırabilirsiniz:
Bu örnekte, daha önce açıklandığı gibi bir kurutma makinesinden errorCode ile proaktif bildirim gönderme işlemi gösterilmektedir:
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, bildirimi aldıktan sonra kullanıcıya "Cihazın kapağı açıldı" uyarısını gösterir. İlgili cihaz durumlarını, bildirimlerle birlikte aynı yükte gönderebilirsiniz.
4. örnek: Takip bildirimi
Takip bildirimlerini destekleyen özellik komutları için, smart home takip bildirimlerini uyguladıysanız hata veya istisna oluştuğunda kullanıcıya takip bildirimi gönderebilirsiniz.
Kullanıcı, garaj kapısını kapatmak için bir komut verir ancak kapı kapanırken sıkışır. errorCode ile takip bildirimi gönderebilirsiniz:
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, bildirimi aldıktan sonra kullanıcıya "Cihaz sıkıştı" uyarısını gösterir. İlgili cihaz durumlarını, bildirimlerle birlikte aynı yükte gönderebilirsiniz.
Daha fazla bilgi ve ayrıntılı errorCodes için Hatalar ve istisnalar referans dokümanlarına bakın.