Menangani error dan pengecualian

Saat perangkat atau permintaan tidak berfungsi seperti yang diharapkan, penting untuk memberikan penanganan dan komunikasi error yang baik bagi pengguna sehingga mereka memahami apa yang terjadi, dan jika memungkinkan, cara memperbaikinya. Pastikan Anda mempertimbangkan kemungkinan skenario kegagalan dan cara perangkat merespons: Bagaimana jika pengguna mengganggu tugas yang sedang berlangsung? Bagaimana jika pengguna meminta tindakan dari perangkat saat sedang offline? Perencanaan untuk masalah ini dan membantu pengguna pulih dari masalah tersebut dapat menghindari frustrasi pengguna dan menciptakan pengalaman berkualitas lebih tinggi untuk perangkat Anda.

Panduan ini menyediakan beberapa contoh respons intent yang menangani error. Lihat dokumentasi referensi 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 terpasang di ruang keluarga. Pengguna memberikan perintah "nyalakan lampu ruang keluarga" dan Google mengirimkan intent EXECUTE ke URL pemenuhan 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 terang 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"
      }
    ]
  }
}

Asisten Google akan meminta pengguna dengan "perangkat tidak tersedia saat ini" setelah menerima respons. Ingat bahwa Anda masih perlu mengirimkan 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 di depan pintu menggunakan perangkat dengan Asisten Google. Anda berhasil mengontrol kuncinya, tetapi ternyata 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"
      }
    }]
  }
}

Asisten Google akan meminta pengguna dengan "baterai baterai hampir habis" setelah menerima respons.

Contoh 3: Notifikasi error proaktif

Dalam beberapa kasus, ada baiknya untuk memperingatkan pengguna tentang error, terutama untuk fungsi yang ingin diselesaikan pengguna secara otomatis. Untuk fitur yang mendukung notifikasi proaktif, Anda dapat memberi tahu pengguna secara proaktif saat terjadi error jika Anda telah menerapkan notifikasi proaktif smart home.

Smart dryer berjalan, dan seseorang membuka pintu sebelum siklus selesai. Anda dapat memanggil metode 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
        }
      }
    }
  }
}

Asisten Google akan meminta pengguna dengan "pintu perangkat dibuka" setelah menerima notifikasi. Anda dapat mengirim status perangkat yang sesuai bersama notifikasi dalam payload yang sama.

Contoh 4: Notifikasi tindak lanjut

Untuk perintah karakteristik yang mendukung notifikasi tindak lanjut, Anda dapat mengirim notifikasi tindak lanjut kepada pengguna saat terjadi error atau pengecualian, jika Anda telah menerapkan notifikasi tindak lanjut smart home.

Pengguna mengeluarkan perintah untuk menutup pintu garasi, tetapi pintu macet saat menutup. 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
        }
      }
    }
  }
}

Asisten Google akan meminta pengguna dengan "perangkat macet" 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.