Cihazlar veya istekler beklendiği gibi çalışmadığında, kullanıcılarınıza iyi bir hata işleme ve iletişim sağlamanız önemlidir. Böylece kullanıcılarınız ne olduğunu ve mümkün olduğunda nasıl düzelteceklerini anlayabilir. Olası hata senaryolarını ve cihazınızın nasıl yanıt vermesi gerektiğini dikkatlice düşünün: Kullanıcı, devam eden bir görevi kesintiye uğratırsa ne olur? Kullanıcı, çevrimdışı durumdaki bir cihazdan işlem isteğinde bulunursa ne olur? Bu sorunları planlamak ve kullanıcılarınızın bu sorunlardan kurtulmasına yardımcı olmak, kullanıcıların hayal kırıklığına uğramasını önleyebilir ve cihazlarınız için daha kaliteli bir deneyim oluşturabilir.
Bu kılavuzda, hataları işleyen amaç yanıtlarına ilişkin bazı örnekler verilmektedir. 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 yüklü. Kullanıcı "oturma odasının ışıklarını aç" komutunu veriyor ve Google, EXECUTE
intent'ini karşılama URL'nize gönderiyor. Kullanıcının cihazlarının çevrimdışı ve kontrol edilemez olduğunu tespit ettiğiniz için karşılamanız EXECUTE
yanıtını status
ERROR
ve errorCode
deviceOffline
ile birlikte döndürüyor.
Bu örnekte, daha önce açıklandığı gibi, ışıklı bir cihazdan EXECUTE
yanıtının errorCode
ile 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" istemini gösteriyor. EXECUTE
yanıtında errorCode
deviceOffline
gönderdikten sonra rapor durumundaki cihazlar için çevrimdışı durumu göndermeniz gerektiğini unutmayın.
2. örnek: EXECUTE
amaçlı, engelleyici olmayan istisna
Bir kullanıcı, Assistant kullanarak ön kapısındaki akıllı kilidi kilitlemeye çalışıyor. Kilitlerini başarıyla kontrol edebilirsiniz ancak cihazın pilinin düşük olduğunu fark edersiniz. Bu nedenle, karşılamanız EXECUTE
yanıtını status
SUCCESS
ve exceptionCode
lowBattery
ile birlikte döndürür.
Bu örnekte, daha önce açıklandığı gibi kilitli bir cihazdan EXECUTE
yanıtının exceptionCode
ile 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ı" mesajı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 hataya karşı uyarmak faydalı olabilir. smart home Proaktif bildirimleri uyguladıysanız proaktif bildirimleri destekleyen özelliklerde hata oluştuğunda kullanıcıyı proaktif olarak bilgilendirebilirsiniz.
Akıllı bir kurutma makinesi çalışırken birisi program bitmeden kapıyı açarsa
Google Home Graph API'sinin reportStateAndNotifications
yöntemini çağırarak errorCode
ile proaktif bildirim gönderebilirsiniz:
Bu örnekte, daha önce açıklandığı gibi bir kurutma makinesi cihazından errorCode
içeren proaktif bir bildirimin nasıl gönderileceği 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ı" istemini gösterir. İlgili cihaz durumlarını aynı yükteki bildirimlerle birlikte gönderebilirsiniz.
4. örnek: Takip bildirimi
Takip bildirimlerini destekleyen özellik komutları için, hata veya istisna oluştuğunda kullanıcıya takip bildirimi gönderebilirsiniz. Bunun için smart home takip bildirimlerini uygulamanız gerekir.
Bir kullanıcı garaj kapısını kapatma komutu veriyor ancak kapı kapanırken sıkışıyor. 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ı" istemini gösterir. İlgili cihaz durumlarını aynı yükteki bildirimlerle birlikte gönderebilirsiniz.
Daha fazla bilgi ve ayrıntılı errorCodes
için Hatalar ve istisnalar referans belgelerine bakın.