Ti diamo il benvenuto nel Centro sviluppatori Google Home, la nuova destinazione per imparare a sviluppare azioni per la smart home. Nota:continuerai a creare azioni nella Console Actions.
Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Guida ai sistemi di sicurezza per la smart home

action.devices.types.SECURITYSYSTEM: i sistemi di sicurezza possono essere attivati e disattivati. Possono essere attivati a più livelli di sicurezza (ad esempio, A casa e Fuori) e possono segnalare informazioni su determinati sensori, come un sensore che rileva movimento o una finestra aperta.

Questo tipo indica che il dispositivo riceve l'icona Sistema di sicurezza e alcuni sinonimi e alias correlati.

Funzionalità dispositivo

Fai riferimento alla documentazione delle caratteristiche corrispondente per ulteriori dettagli sull'implementazione, ad esempio attributi e stati che il servizio deve supportare e come creare risposte EXECUTE e QUERY.

Caratteristiche obbligatorie

Questi tratti e comandi sono obbligatori, se pertinenti al tuo dispositivo.

Queste caratteristiche sono consigliate, se applicabili al tuo dispositivo. Tuttavia, puoi modificare e abbinare tutte le caratteristiche disponibili per trovare una corrispondenza ottimale con le tue funzionalità di prodotto esistenti.

Requisiti di qualità

  • Latenza: deve essere inferiore o uguale a 2000 ms.
  • Affidabilità: deve essere superiore o uguale al 97%.

Dispositivo di esempio: sistema di sicurezza semplice

Questa sezione contiene esempi di payload degli intent che rappresentano un "sistema di sicurezza" comune in base al tipo di dispositivo e alle caratteristiche citate sopra. Se aggiungi o rimuovi caratteristiche nell'implementazione, modifica le risposte di conseguenza per riflettere tali modifiche.

Esempio di risposta SYNC

Richiedi
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
Risposta
{
  "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"
        }
      }
    ]
  }
}

Esempio di risposta QUERY

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

Esempi di comandi EXECUTE

ArmDisarm

Per ulteriori dettagli sui parametri dei comandi, consulta il riferimento action.devices.traits.ArmDisarm.

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

ERRORI del dispositivo

Consulta l'elenco completo degli errori e delle eccezioni.

Segnala le eccezioni di attivazione

Quando tenti di abilitare o disabilitare il sistema, puoi fornire un contesto aggiuntivo tramite i codici di eccezione che segnali tramite la caratteristica StatusReport. Le eccezioni possono essere segnalate come con blocco o senza blocco.

  • Le eccezioni non bloccanti segnalate con lo stato "SUCCESS" indicano che l'eccezione non ha impedito l'abilitazione o la disabilitazione.
  • Le eccezioni di blocco con stato "ECCEZIONI" indicano che l'abilitazione o la disabilitazione sono state interrotte a causa di queste eccezioni.

I codici di eccezione comunemente associati ai sistemi di sicurezza includono:

  • doorOpen: è stata aperta una porta.
  • windowOpen: viene aperta una finestra.
  • isOpen: un sensore rileva che qualcosa è aperto, ma non sa se è una porta o una finestra.

Esempio: eccezione non bloccante

Questo esempio mostra un'eccezione non bloccante in cui il sistema di sicurezza viene abilitato anche se una finestra viene segnalata come aperta.

Utente Imposta il sistema di sicurezza su Alta sicurezza.
l'Assistente Google Ok, la finestra anteriore è aperta. Abilitare il sistema di sicurezza ad alta sicurezza.
Richiedi
{
  "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"
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "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"
            }
          ]
        }
      }
    ]
  }
}

Esempio: eccezione di blocco

Utente Imposta il sistema di sicurezza su Alta sicurezza.
l'Assistente Google Si è verificato un errore durante il controllo del sistema di sicurezza. La finestra anteriore è aperta.
Richiedi
{
  "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"
          }
        }]
      }]
    }
  }]
}
Risposta 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "isArmed": false,
          "currentArmLevel": "L2",
          "currentStatusReport": [
            {
              "blocking": true,
              "priority": 0,
              "statusCode": "windowOpen",
              "deviceTarget": "sensor_id1"
            }
          ]
        }
      }
    ]
  }
}

Abilitare l'autenticazione a due fattori

Se il flusso di inserimento richiede agli utenti di inserire un PIN tramite una finestra di dialogo per l'autenticazione a due fattori, devi confermare se vogliono continuare ad abilitare il sistema in caso di eccezioni attive (ad esempio, quando è aperta una finestra o una porta).

Questo scenario potrebbe richiedere sia un PIN sia la voce di passphrase, seguita da una conferma.

Esempio: verifica di riconoscimento

Questo esempio mostra un utente che cerca di abilitare il sistema di sicurezza, ma viene rilevata come aperta una porta d'ingresso. L'utente riconosce che il sistema di sicurezza deve essere abilitato anche se la porta d'ingresso è aperta.

Utente Abilita il sistema di sicurezza.
l'Assistente Google La porta d'ingresso è aperta. Vuoi abilitare il sistema di sicurezza?
Utente Sì,
l'Assistente Google Ok, abilitare il sistema di sicurezza.

Nel primo turno devi rispondere con una sfida ackNeeded.

Richiesta 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
          }
        }]
      }]
    }
  }]
}
Risposta 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"
            }
          ]
        }
      }
    ]
  }
}

La successiva richiesta che riceverai da Google conterrà il risultato di ack.

Richiesta 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
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}

Esempio: verifica tramite PIN e conferma

L'esempio mostra un utente che tenta di abilitare il sistema di sicurezza che richiede l'inserimento del PIN. Il sistema rileva che le finestre anteriore e posteriore sono aperte e chiede all'utente di confermare che l'abilitazione deve procedere.

Utente Braccio via.
l'Assistente Google Qual è il tuo PIN?
Utente 1234.
l'Assistente Google Sembra che la finestra anteriore e quella posteriore siano aperte. Vuoi continuare ad abilitare il sistema di sicurezza?
Utente Sì,
l'Assistente Google Ok, abilitare il sistema di sicurezza

Nel primo turno devi rispondere con una sfida pinNeeded standard.

Richiesta 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
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["456"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Google ti invia poi una richiesta contenente il PIN fornito. Per supportare la seconda svolta, devi rispondere con una verifica ackNeeded fornendo informazioni aggiuntive, incluso il livello del gruppo target e il report di stato attuale con eccezioni di blocco.

Richiesta 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"
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "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"
      }
    }]
  }
}

La richiesta successiva inviata da Google conterrà solo il risultato ack e non il PIN fornito alla prima svolta.

Richiesta 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
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "isArmed": true
        }
      }
    ]
  }
}