Te damos la bienvenida al Centro para desarrolladores de Google Home, el nuevo destino para aprender a desarrollar acciones para el hogar inteligente. Nota: Continuarás compilando acciones en la Consola de Actions.
Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Guía del sistema de seguridad para el hogar inteligente

action.devices.types.SECURITYSYSTEM: los sistemas de seguridad se pueden activar y desactivar. Pueden activarse en varios niveles de seguridad (por ejemplo, En casa y Ausente), y pueden enviar información sobre ciertos sensores, como uno que detecte movimiento o una ventana abierta.

Este tipo indica que el dispositivo obtiene el ícono del sistema de seguridad y algunos sinónimos y sinónimos relacionados.

Funciones del dispositivo

Consulta la documentación de características correspondiente para obtener detalles de implementación, como atributos y estados que tu servicio debe admitir, y cómo compilar respuestas de EXECUTE y QUERY.

Características obligatorias

Estas características y comandos son necesarios si corresponden a tu dispositivo.

Recomendamos estas características, si se aplican a tu dispositivo. Sin embargo, puedes combinar todas las características disponibles para que se adapten mejor a la funcionalidad del producto existente.

Requisitos de calidad

  • Latencia: Debe ser menor o igual que 2,000 ms.
  • Confiabilidad: Debe ser mayor o igual que 97%.

Ejemplo de dispositivo: Sistema de seguridad simple

Esta sección contiene cargas útiles de intent de ejemplo que representan un "sistema de seguridad" común según el tipo de dispositivo y las características anteriores. Si agregas o quitas rasgos en tu implementación, modifica tus respuestas según corresponda para reflejar esos cambios.

Respuesta de muestra de SYNC

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

Respuesta de muestra QUERY

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

Comandos de EXECUTE de muestra

Activar la alarma

Para obtener detalles adicionales sobre los parámetros del comando, consulta la referencia de action.devices.traits.ArmDisarm.

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

Dispositivo ERRORS

Consulta la lista completa de errores y excepciones.

Informar excepciones activadas

Cuando intentes activar o desactivar el sistema, puedes proporcionar contexto adicional mediante códigos de excepciones que informes a través de la característica StatusReport. Se pueden informar excepciones como bloqueos o no bloqueos.

  • Las excepciones sin bloqueo informadas con el estado "SUCCESS" indican que la excepción no evitó que se activen o desactiven.
  • Las excepciones de bloqueo informadas con el estado "EXCEPTIONS" indican que la activación o desactivación se detuvo debido a estas excepciones.

Entre los códigos de excepción comúnmente asociados con los sistemas de seguridad, se incluyen los siguientes:

  • doorOpen: Hay una puerta abierta.
  • windowOpen: Está abierta una ventana.
  • isOpen: Un sensor detecta que hay algo abierto (pero no sabe si es una puerta o una ventana).

Ejemplo: Excepción sin bloqueo

En este ejemplo, se muestra una excepción sin bloqueo en la que el sistema de seguridad se activa a pesar de que una ventana se informa como abierta.

User Establece el sistema de seguridad en alto nivel.
Asistente de Google Muy bien, la ventana frontal está abierta. Se activará el sistema de seguridad para garantizar un nivel alto.
Solicitud
{
  "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"
          }
        }]
      }]
    }
  }]
}
Respuesta
{
  "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"
            }
          ]
        }
      }
    ]
  }
}

Ejemplo: excepción de bloqueo

User Establece el sistema de seguridad en alto nivel.
Asistente de Google Se produjo un error al controlar el sistema de seguridad. La ventana principal está abierta.
Solicitud
{
  "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"
          }
        }]
      }]
    }
  }]
}
Respuesta 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"
            }
          ]
        }
      }
    ]
  }
}

Activación de la autenticación de dos factores

Si tu flujo de activación requiere que los usuarios ingresen un PIN a través de un diálogo de autenticación de dos factores, debes confirmar si desean continuar activando el sistema cuando haya excepciones activas (por ejemplo, cuando una ventana o puerta está abierta).

En este caso, es posible que se requiera un PIN o una entrada de frase de contraseña, seguido de una confirmación de recepción.

Ejemplo: Desafío de confirmación

En este ejemplo, se muestra a un usuario que intenta activar el sistema de seguridad, pero se detecta que una puerta principal está abierta. El usuario reconoce que el sistema de seguridad debe activarse, aunque la puerta principal esté abierta.

User Activa el sistema de seguridad.
Asistente de Google La puerta principal está abierta. ¿Confirmas que quieres activar el sistema de seguridad?
User Sí.
Asistente de Google Muy bien, activando el sistema de seguridad.

En el primer turno, debes responder con un desafío ackNeeded.

Solicitud 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
          }
        }]
      }]
    }
  }]
}
Respuesta 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 solicitud posterior que recibas de Google contendrá el resultado de ack.

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

Ejemplo: PIN y desafío de confirmación

En este ejemplo, se muestra un usuario que intenta activar el sistema de seguridad y que requiere una entrada de PIN. El sistema detecta que las ventanas frontal y posterior están abiertas y le pide al usuario que reconozca que se debe activar la activación.

User Activa el brazo para alejarte.
Asistente de Google ¿Cuál es tu PIN?
User 1234.
Asistente de Google Parece que la ventana principal y la trasera están abiertas. ¿Estás seguro de que deseas continuar activando el sistema de seguridad para que desaparezca?
User Sí.
Asistente de Google Está bien, desactivando el sistema de seguridad

En el primer turno, debes responder con un desafío pinNeeded estándar.

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

A continuación, Google realiza un seguimiento de la solicitud que contiene el PIN proporcionado. Para admitir la segunda vuelta, debes responder con un desafío ackNeeded con información adicional, incluido el nivel del grupo objetivo y el informe de estado actual con excepciones de bloqueo.

Solicitud 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"
          }
        }]
      }]
    }
  }]
}
Respuesta
{
  "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 solicitud posterior que recibas de Google solo contendrá el resultado de ack y no el PIN proporcionado en el primer giro.

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