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 yang direkomendasikan
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
{ "requestId": "6894439706274654512", "inputs": [ { "intent": "action.devices.SYNC" } ] }
{ "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
{ "requestId": "6894439706274654514", "inputs": [ { "intent": "action.devices.QUERY", "payload": { "devices": [ { "id": "123" } ] } } ] }
{ "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
.
{ "requestId": "6894439706274654516", "inputs": [ { "intent": "action.devices.EXECUTE", "payload": { "commands": [ { "devices": [ { "id": "123" } ], "execution": [ { "command": "action.devices.commands.ArmDisarm", "params": { "arm": true, "armLevel": "away_key" } } ] } ] } } ] }
{ "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. |
{
"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"
}
}]
}]
}
}]
}
{
"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. |
{
"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"
}
}]
}]
}
}]
}
{
"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
.
{
"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
}
}]
}]
}
}]
}
{
"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
.
{
"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
}
}]
}]
}
}]
}
{
"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.
{ "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 } }] }] } }] }
{ "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.
{ "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" } }] }] } }] }
{ "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.
{ "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 } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "isArmed": true } } ] } }