Menangani error dan pengecualian

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

Panduan ini memberikan beberapa contoh respons maksud yang menangani error. Lihat Error dan pengecualian untuk meninjau nilai errorCode yang valid untuk error dan pengecualian.

Contoh 1: Respons error untuk intent EXECUTE

Pengguna akhir telah menginstal dua lampu smart di ruang keluarga mereka. Pengguna mengeluarkan perintah "nyalakan lampu ruang keluarga" dan Google mengirimkan intent EXECUTE ke URL fulfillment Anda. Anda mendapati bahwa perangkat pengguna sedang offline dan tidak dapat dikontrol, sehingga pemenuhan Anda menampilkan respons EXECUTE dengan status ERROR dan errorCode deviceOffline.

Contoh ini menunjukkan cara menampilkan respons EXECUTE dengan errorCode dari perangkat lampu 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"
      }
    ]
  }
}

Google Assistant akan meminta pengguna dengan "perangkat tidak tersedia saat ini" setelah menerima respons. Ingatlah bahwa Anda tetap perlu mengirim status offline untuk perangkat dalam status laporan setelah mengirim errorCode deviceOffline dalam respons EXECUTE.

Contoh 2: Pengecualian non-pemblokiran untuk maksud EXECUTE

Pengguna mencoba mengunci smart lock di pintu depan menggunakan Assistant. Anda dapat berhasil mengontrol smart lock-nya, tetapi Anda mendapati baterai perangkatnya lemah, sehingga pemenuhan Anda menampilkan respons EXECUTE dengan status SUCCESS dan exceptionCode lowBattery.

Contoh ini menunjukkan cara mengirim respons EXECUTE dengan exceptionCode dari perangkat smart lock 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"
      }
    }]
  }
}

Assistant meminta pengguna dengan "perangkat memiliki daya baterai rendah" setelah menerima respons.

Contoh 3: Notifikasi error proaktif

Dalam beberapa kasus, sebaiknya beri tahu pengguna tentang error, terutama untuk fungsi yang diharapkan pengguna selesai secara otomatis. Untuk karakteristik yang mendukung notifikasi proaktif, Anda dapat memberi tahu pengguna secara proaktif saat terjadi error jika Anda telah menerapkan smart home notifikasi proaktif.

Pengering pintar sedang berjalan, dan seseorang membuka pintu sebelum siklus selesai. Anda dapat memanggil metode Google 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
        }
      }
    }
  }
}

Assistant 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 lanjutan, Anda dapat mengirim notifikasi lanjutan kepada pengguna saat terjadi error atau pengecualian, jika Anda telah menerapkan smart home notifikasi lanjutan.

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

Assistant akan meminta pengguna dengan pesan "perangkat sedang terganggu" setelah menerima notifikasi. Anda dapat mengirim status perangkat yang sesuai dengan notifikasi dalam payload yang sama.

Untuk mengetahui informasi selengkapnya dan errorCodes mendetail, lihat dokumentasi referensi Error dan pengecualian.