Panduan Sistem Keamanan Smart Home

action.devices.types.SECURITYSYSTEM - Sistem keamanan dapat diaktifkan dan dinonaktifkan. Sensor dapat diaktifkan di berbagai tingkat keamanan (misalnya, di rumah dan di luar rumah) dan dapat melaporkan informasi tentang sensor tertentu, seperti sensor yang mendeteksi gerakan atau jendela yang terbuka.

Jenis ini menunjukkan bahwa perangkat mendapatkan ikon Sistem Keamanan serta beberapa sinonim dan alias yang terkait.

Kemampuan perangkat

Lihat dokumentasi trait yang sesuai untuk mengetahui detail implementasi, seperti atribut dan status yang harus didukung layanan Anda, serta cara membuat respons EXECUTE dan QUERY.

Ciri yang diperlukan

Sifat dan perintah ini diperlukan, jika berlaku untuk perangkat Anda. Jika perangkat Anda tidak mendukung ciri ini, masukkan kode error functionNotSupported dalam respons QUERY atau EXECUTE. Lihat Error dan pengecualian untuk mengetahui info selengkapnya.

Fitur ini direkomendasikan, jika berlaku untuk perangkat Anda. Namun, Anda dapat memadupadankan semua ciri yang tersedia agar sesuai dengan fungsi produk yang sudah ada.

Persyaratan kualitas

  • Latensi: harus kurang dari atau sama dengan 2.000 md.
  • Keandalan: harus lebih dari atau sama dengan 97%.

Perangkat contoh: Sistem keamanan sederhana

Bagian ini berisi contoh payload intent yang merepresentasikan "Sistem Keamanan" umum berdasarkan jenis dan ciri perangkat di atas. Jika Anda menambahkan atau menghapus ciri dalam implementasi, ubah respons Anda sesuai dengan perubahan tersebut untuk mencerminkan perubahan tersebut.

Contoh respons SYNC

Permintaan
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
Respons
{
  "requestId": "6894439706274654512",
  "payload": {
    "agentUserId": "user123",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.SECURITYSYSTEM",
        "traits": [
          "action.devices.traits.StatusReport",
          "action.devices.traits.ArmDisarm"
        ],
        "name": {
          "name": "Simple security system"
        },
        "willReportState": true,
        "attributes": {
          "availableArmLevels": {
            "levels": [
              {
                "level_name": "home_key",
                "level_values": [
                  {
                    "level_synonym": [
                      "Home and Guarding",
                      "level 1",
                      "home",
                      "SL1"
                    ],
                    "lang": "en"
                  }
                ]
              },
              {
                "level_name": "away_key",
                "level_values": [
                  {
                    "level_synonym": [
                      "Away and Guarding",
                      "level 2",
                      "away",
                      "SL2"
                    ],
                    "lang": "en"
                  }
                ]
              }
            ],
            "ordered": true
          }
        },
        "deviceInfo": {
          "manufacturer": "smart-home-inc",
          "model": "hs1234",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        }
      }
    ]
  }
}

Contoh respons QUERY

Permintaan
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
Respons
{
  "requestId": "6894439706274654514",
  "payload": {
    "devices": {
      "123": {
        "status": "SUCCESS",
        "online": true,
        "isArmed": true,
        "currentArmLevel": "home_key",
        "currentStatusReport": [
          {
            "blocking": false,
            "deviceTarget": "123",
            "priority": 0,
            "statusCode": "lowBattery"
          }
        ]
      }
    }
  }
}

Contoh perintah EXECUTE

ArmDisarm

Untuk detail tambahan tentang parameter perintah, lihat referensi action.devices.traits.ArmDisarm.

Permintaan
{
  "requestId": "6894439706274654516",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.ArmDisarm",
                "params": {
                  "arm": true,
                  "armLevel": "away_key"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Respons
{
  "requestId": "6894439706274654516",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": true,
          "currentArmLevel": "away_key"
        }
      }
    ]
  }
}

Perangkat ERRORS

Lihat daftar lengkap error dan pengecualian.

Melaporkan pengecualian pengaktifan

Saat mencoba mengaktifkan atau menonaktifkan sistem, Anda dapat memberikan konteks tambahan melalui kode pengecualian yang Anda laporkan melalui fitur StatusReport. Pengecualian dapat dilaporkan sebagai pemblokiran atau non-pemblokiran.

  • Pengecualian non-pemblokiran yang dilaporkan dengan status "SUCCESS" menunjukkan bahwa pengecualian tidak mencegah pengaktifan atau penonaktifan.
  • Pengecualian pemblokiran yang dilaporkan dengan status "EXCEPTIONS" menunjukkan bahwa pengaktifan atau penonaktifan dihentikan karena pengecualian ini.

Kode pengecualian yang umumnya dikaitkan dengan sistem keamanan meliputi:

  • doorOpen: Pintu terbuka.
  • windowOpen: Jendela terbuka.
  • isOpen: Sensor mendeteksi ada yang terbuka (tetapi tidak mengetahui apakah itu pintu atau jendela).

Contoh: Pengecualian non-pemblokiran

Contoh ini menunjukkan pengecualian yang tidak memblokir saat sistem keamanan diaktifkan meskipun jendela dilaporkan sebagai terbuka.

User Setel sistem keamanan ke keamanan tinggi.
Asisten Google Oke, jendela depan dibuka. Mengaktifkan sistem keamanan ke keamanan tinggi.
Permintaan
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true,
              "armLevel": "L2"
            }
          }]
        }]
      }
    }]
  }
Respons
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "online": true,
            "isArmed": true,
            "currentArmLevel": "L2",
            "currentStatusReport": [
              {
                "blocking": false,
                "priority": 0,
                "statusCode": "windowOpen",
                "deviceTarget": "sensor_id1"
              }
            ]
          }
        }
      ]
    }
  }

Contoh: Pengecualian pemblokiran

User Setel sistem keamanan ke keamanan tinggi.
Asisten Google Terjadi error saat mengontrol sistem keamanan. Jendela depan terbuka.
Permintaan
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true,
              "armLevel": "L2"
            }
          }]
        }]
      }
    }]
  }
Respons 2
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "EXCEPTIONS",
          "states": {
            "online": true,
            "isArmed": false,
            "currentArmLevel": "L2",
            "currentStatusReport": [
              {
                "blocking": true,
                "priority": 0,
                "statusCode": "windowOpen",
                "deviceTarget": "sensor_id1"
              }
            ]
          }
        }
      ]
    }
  }

Persenjataan dengan autentikasi 2 langkah

Jika alur pengaktifan mengharuskan pengguna memasukkan PIN melalui dialog autentikasi 2 langkah, Anda harus mengonfirmasi apakah pengguna ingin terus mengaktifkan sistem saat ada pengecualian aktif (misalnya, saat jendela atau pintu terbuka).

Skenario ini mungkin memerlukan kedua entri PIN atau frasa sandi, diikuti dengan konfirmasi.

Contoh: Tantangan pengakuan

Contoh ini menunjukkan pengguna yang mencoba mengaktifkan sistem keamanan, tetapi pintu depan terdeteksi sebagai terbuka. Pengguna mengetahui bahwa sistem keamanan harus aktif meskipun pintu depan terbuka.

User Aktifkan sistem keamanan.
Asisten Google Pintu depan terbuka. Yakin ingin mengaktifkan sistem keamanan?
User Ya.
Asisten Google Oke, mengaktifkan sistem keamanan.

Di belokan pertama, Anda harus merespons dengan tantangan ackNeeded.

Permintaan 1
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true
            }
          }]
        }]
      }
    }]
  }
Respons 2
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "ERROR",
          "errorCode": "challengeNeeded",
          "challengeNeeded": {
            "type": "ackNeeded"
          },
          "states": {
            "isArmed": true,
            "currentArmLevel": "L2",
            "currentStatusReport": [
              {
                "blocking": false,
                "priority": 0,
                "statusCode": "doorOpen",
                "deviceTarget": "456"
              }
            ]
          }
        }
      ]
    }
  }

Permintaan berikutnya dari Google kepada Anda akan berisi hasil ack.

Permintaan 2
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [{
          "devices": [{
            "id": "123"
          }],
          "execution": [{
            "command": "action.devices.commands.ArmDisarm",
            "params": {
              "arm": true
            },
            "challenge": {
              "ack": true
            }
          }]
        }]
      }
    }]
  }
Respons
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
      "commands": [
        {
          "ids": [
            "123"
          ],
          "status": "SUCCESS",
          "states": {
            "isArmed": true
          }
        }
      ]
    }
  }

Contoh: verifikasi PIN dan konfirmasi

Contoh ini menunjukkan pengguna yang mencoba mengaktifkan sistem keamanan yang memerlukan input PIN. Sistem mendeteksi bahwa jendela depan dan belakang terbuka, lalu meminta pengguna untuk mengonfirmasi bahwa pengaktifan harus dilanjutkan.

User Lengan ke arah menjauh.
Asisten Google Apa PIN Anda?
User 1234.
Asisten Google Sepertinya jendela depan dan jendela belakang terbuka. Yakin ingin terus mengaktifkan sistem keamanan?
User Ya.
Asisten Google Oke, mengaktifkan sistem keamanan untuk

Di belokan pertama, Anda harus merespons dengan tantangan pinNeeded standar.

Permintaan 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.ArmDisarm",
          "params": {
            "arm": true
          }
        }]
      }]
    }
  }]
}
Respons
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Kemudian, Google menindaklanjuti dengan permintaan yang berisi PIN yang diberikan. Untuk mendukung belokan kedua, Anda harus merespons dengan tantangan ackNeeded dengan informasi tambahan, termasuk level grup target, dan laporan status saat ini dengan pengecualian pemblokiran.

Permintaan 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [...],
        "execution": [{
          "command": "action.devices.commands.ArmDisarm",
          "params": {
            "arm": true,
            "armLevel": "away"
          },
          "challenge": {
            "pin": "1234"
          }
        }]
      }]
    }
  }]
}
Respons
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "states": {
        "targetArmLevel": "away",
        "currentStatusReport": [{
            "blocking": true,
            "priority": 1,
            "deviceTarget": "front_window_id",
            "statusCode": "deviceOpen"
          },
          {
            "blocking": true,
            "priority": 1,
            "deviceTarget": "back_window_id",
            "statusCode": "deviceOpen"
          }
        ]
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

Permintaan berikutnya dari Google kepada Anda hanya akan berisi hasil ack, dan bukan PIN yang diberikan pada belokan pertama.

Permintaan 3
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [...],
        "execution": [{
          "command": "action.devices.commands.ArmDisarm",
          "params": {
            "arm": true,
            "armLevel": "away"
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
Respons
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}