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 nasıl yanıt vermesi gerektiğini düşünün: Bir 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 sorunları öngörmek ve kullanıcılarınızın bu sorunlardan kurtulmasına yardımcı olmak, kullanıcıların canını sıkmasını önleyebilir ve cihazlarınızda daha kaliteli bir deneyim sunabilir.
Bu kılavuzda, hataları ele alan 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 intent'i için hata yanıtı
Bir son kullanıcının salonunda iki akıllı ışık vardır. Kullanıcı "oturma odasının ışıklarını aç" komutunu verir ve Google, yerine getirme URL'nize bir EXECUTEintent gönderir. Kullanıcının cihazlarının çevrimdışı olduğunu ve kontrol edilemediğini tespit ettiniz. Bu nedenle, 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 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" mesajını 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 engellemeyen istisna
Kullanıcı, Assistant'ü kullanarak ön kapısında akıllı kilidi 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 bir kilit cihazından 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 düşük" mesajını 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 bildirimleri 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 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 kullanıcıya "Cihaz sıkışmış" mesajını 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ını inceleyin.