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 dan beberapa hal terkait sinonim dan alias.

Kemampuan perangkat

Lihat dokumentasi sifat yang sesuai untuk detail penerapan, seperti atribut dan status yang harus didukung layanan Anda, serta cara membangun respons EXECUTE dan QUERY.

Ciri yang diperlukan

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

Fitur ini direkomendasikan, jika berlaku untuk perangkat Anda. Namun, Anda bebas memadupadankan semua sifat yang tersedia agar cocok dengan yang ada fungsionalitas produk.

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 mewakili "Sistem Keamanan" umum berdasarkan jenis dan karakteristik perangkat di atas. Jika Anda menambahkan atau menghapus ciri khas dalam implementasi Anda, ubah tanggapan Anda untuk mencerminkan perubahan tersebut.

Contoh respons SYNC

Minta
{
  "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

Minta
{
  "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 action.devices.traits.ArmDisarm alamat IP internal.

Minta
{
  "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 informasi konteks melalui kode pengecualian yang Anda laporkan melalui ciri StatusReport. Pengecualian dapat dilaporkan sebagai pemblokiran atau non-pemblokiran.

  • Pengecualian yang tidak memblokir dilaporkan dengan "SUCCESS" status menunjukkan bahwa pengecualian ini tidak mencegah penyusupan atau penonaktifan.
  • Pengecualian pemblokiran dilaporkan dengan "EXCEPTIONS" menunjukkan bahwa mengaktifkan 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 sesuatu yang terbuka (tetapi tidak mengetahui jika berupa pintu atau jendela).

Contoh: Pengecualian non-pemblokiran

Contoh ini menunjukkan pengecualian non-pemblokiran di mana sistem keamanan berada meskipun jendela dilaporkan sebagai terbuka.

Pengguna Setel sistem keamanan ke keamanan tinggi.
Asisten Google Oke, jendela depan terbuka. Mengaktifkan sistem keamanan ke keamanan tinggi.
Minta
{
    "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

Pengguna Setel sistem keamanan ke keamanan tinggi.
Asisten Google Terjadi error mengontrol sistem keamanan. Jendela depan terbuka.
Minta
{
    "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 untuk memasukkan PIN melalui dialog autentikasi 2 langkah, Anda harus mengonfirmasi apakah mereka ingin terus mengaktifkan sistem saat ada pengecualian (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 mengakui bahwa keamanan sistem harus diaktifkan meskipun pintu depan terbuka.

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

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 dan meminta pengguna untuk mengonfirmasi agar pemberdayaan itu dilanjutkan.

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

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 di belokan kedua, Anda harus merespons dengan tantangan ackNeeded dengan informasi tambahan, termasuk tingkat 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 di 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
        }
      }
    ]
  }
}