Cihazlar veya istekler beklendiği gibi çalışmadığında kullanıcılarınızın ne olduğunu ve mümkün olduğunda nasıl düzeltileceğini anlayabilmeleri için iyi bir hata işleme ve iletişim sunmanız önemlidir. Olası hata senaryolarını ve cihazınızın bu durumlara nasıl yanıt vereceğini göz önünde bulundurun: Kullanıcı, devam eden bir görevi kesintiye uğratırsa ne olur? Kullanıcı, çevrimdışıyken bir cihazdan işlem isteğinde bulunursa ne olur? Bu sorunlara yönelik plan yapmak ve kullanıcınızın bunları kurtarmasına yardımcı olmak, kullanıcıların hayal kırıklığına uğramasını önler ve cihazlarınız için daha kaliteli bir deneyim sunar.
Bu kılavuzda, hataları işleyen amaç yanıtlarının bazı örnekleri sunulmaktadır. Hata ve istisnalar için geçerli errorCode değerlerini incelemek üzere Hatalar ve istisnalar bölümüne bakın.
1. örnek: EXECUTE intent'i için hata yanıtı
Bir son kullanıcının salonunda iki akıllı ışık vardır. Kullanıcı "oturma odası ışıklarını aç" komutu verir ve Google, sipariş karşılama URL'nize bir EXECUTE amacı gönderir. Kullanıcının cihazlarının çevrimdışı olduğunu ve kontrol edilemediğini tespit ettiğiniz için karşılama işleminiz status ERROR ve errorCode deviceOffline içeren bir EXECUTE yanıt döndürür.
Bu örnekte, daha önce açıklandığı gibi hafif bir cihazdan errorCode ile 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, "cihaz şu anda kullanılamıyor" ifadesini içeren kullanıcıya istem gösterir. EXECUTE yanıtında errorCode deviceOffline gönderdikten sonra, rapor durumundaki cihazlar için çevrimdışı durumunu göndermeniz gerektiğini unutmayın.
2. örnek: EXECUTE intent'i için engellenmeyen istisna
Bir kullanıcı, Assistant özellikli cihazı kullanarak ön kapıdaki akıllı kilidini kilitlemeye çalışıyor. Kilidi başarıyla kontrol edebilirsiniz ancak cihazın pilinin düşük olduğunu görürsünüz. Bu nedenle, yerine getirme işleminiz status SUCCESS ve exceptionCode lowBattery içeren bir EXECUTE yanıtı döndürür.
Bu örnekte, daha önce açıklandığı gibi kilit cihazından exceptionCode ile 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 "cihazın pil seviyesi düşük" olan kullanıcıya istem gösterir.
3. Örnek: Proaktif hata bildirimleri
Bazı durumlarda, özellikle kullanıcıların otomatik olarak tamamlanmasını beklediği işlevler için kullanıcıları bir hata konusunda uyarmak yararlı olabilir. Proaktif bildirimleri destekleyen özelliklerde, smart home proaktif bildirimler uyguladıysanız hata oluştuğunda kullanıcıyı proaktif olarak bilgilendirebilirsiniz.
Akıllı bir kurutma makinesi çalışıyor ve kullanıcı, döngü bitmeden önce kapıyı açıyor.
Google Home Graph APIreportStateAndNotifications yöntemini çağırarak errorCode içeren proaktif bir bildirim gönderebilirsiniz:
Bu örnekte, daha önce açıklandığı gibi bir çamaşır kurutma makinesi cihazından 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 kapısı açıldı" mesajını gösterir. Aynı yükte bildirimlerin yanı sıra ilgili cihaz durumlarını da 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ı kapatma komutu verir ancak kapı kapanırken takılı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 "cihaz sıkışmış" ifadesini içeren kullanıcıya istem gösterir. Aynı yükte bildirimler ile ilgili cihaz durumlarını gönderebilirsiniz.
Daha fazla bilgi ve ayrıntılı errorCodes için Hatalar ve istisnalar referans dokümanlarına bakın.