Verifica utente secondario

La verifica utente secondaria ti consente di aggiungere la sicurezza del secondo fattore ai comandi vocali. In questo modo, puoi aggiungere ulteriore sicurezza per determinate azioni, ad esempio spegnere una videocamera di sicurezza o aprire una porta. La verifica utente secondaria non è legata a una caratteristica specifica del dispositivo, il che ti consente di decidere quando Google Assistant deve emettere una richiesta di verifica. Ad esempio, puoi scegliere di emettere una richiesta di verifica per la caratteristica OnOff di una videocamera di sicurezza, ma non emettere una richiesta di verifica per la OnOff caratteristica di una luce. Puoi anche fare in modo che Assistant emetta richieste di verifica in determinate situazioni per la stessa azione. Ad esempio, puoi richiedere che Assistant emetta una richiesta di verifica per aprire una porta se un portachiavi NFC non si trova nelle vicinanze della porta, ma non emetta una richiesta di verifica se il portachiavi è presente.

Il Assistant può emettere due tipi di richieste di verifica: riconoscimento esplicito o PIN (Personal Identification Number). In questo modo, viene aggiunto un blocco di richieste di verifica agli intenti QUERY e EXECUTE inviati da Assistant alla tua azione e viene accettata una risposta di errore challengeNeeded. Assistant invia quindi la richiesta di intent a tua azione con i dati della richiesta di verifica nel blocco di richieste di verifica. A questo punto, puoi convalidare i dati della richiesta di verifica per determinare se l'utente ha fornito la risposta di sicurezza corretta.

Assistant utilizza la finestra di dialogo per emettere la richiesta di verifica, ma se utilizzi Assistant su superfici non vocali, il PIN e le conferme vengono eseguiti sullo schermo.

Quando utilizzare la verifica utente secondaria

Puoi attivare la verifica utente secondaria per qualsiasi tipo di dispositivo o caratteristica. Tuttavia, devi implementare la verifica utente secondaria per determinati tipi di dispositivi e caratteristiche sensibili alla sicurezza per ottenere la certificazione dell'integrazione.

La verifica utente secondaria che utilizza il tipo di richiesta di verifica pinNeeded è obbligatoria per le seguenti combinazioni di caratteristiche e tipi di dispositivi:

  • La caratteristica OnOff se il tipo di dispositivo è CAMERA.
  • La caratteristica OpenClose se il tipo di dispositivo è DOOR, GARAGE, GATE o WINDOW.
  • La caratteristica LockUnlock durante lo sblocco.
  • La caratteristica ArmDisarm durante il disarmo o l'annullamento del disarmo.
  • La caratteristica Reboot, SoftwareUpdate o NetworkControl se il tipo di dispositivo è NETWORK o ROUTER.

Il tipo di richiesta di verifica ackNeeded è obbligatorio per la caratteristica TemperatureSetting se il tipo di dispositivo è AC_UNIT e l'integrazione si trova in Giappone.

Tipi di richieste di verifica supportati

Di seguito sono riportati i tipi di richieste di verifica utente secondaria supportati:

  • Nessuna richiesta di verifica - Una richiesta e una risposta che non utilizzano una richiesta di verifica utente secondaria.
  • ackNeeded: una verifica utente secondaria che richiede un riconoscimento esplicito (sì o no) e può anche utilizzare gli stati delle caratteristiche come feedback di risposta. Questo tipo di richiesta di verifica non è consigliato per dispositivi e caratteristiche di sicurezza.
  • pinNeeded: una verifica utente secondaria che richiede un PIN (Personal Identification Number), ideale per dispositivi e caratteristiche di sicurezza.

Nessuna richiesta di verifica

Questo esempio mostra una richiesta e una risposta EXECUTE riuscite senza una richiesta di verifica per accendere le luci.

Utente Accendi le luci.
Google Assistant Ok, accendo 3 luci.
Richiesta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.OnOff",
          "params": {
            "on": true
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

Un'autenticazione di riconoscimento utente secondaria che può utilizzare più stati per una caratteristica o un'autenticazione di riconoscimento semplice.

Esistono i seguenti tipi di richieste di verifica ackNeeded:

ackNeeded semplice

Questo esempio mostra una semplice richiesta e risposta con una richiesta di verifica ackNeeded per attenuare una luce e la conferma per attenuare la luce.

Utente Attenua la luce del salotto.
Google Assistant Attenuo la luce del salotto. Vuoi continuare?
Utente Sì.
Google Assistant Attenuo la luce del salotto.
Richiesta 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}
Risposta 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Richiesta 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
Risposta 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackNeeded con stati delle caratteristiche

Un'autenticazione di riconoscimento utente secondaria che può utilizzare gli stati per una caratteristica. Ad esempio, se utilizzi la TemperatureSetting caratteristica e sono impostati sia thermostatMode sia thermostatTemperatureSetpoint, Assistant può chiedere Vuoi impostare il riscaldamento del condizionatore d'aria a 28 gradi?

Puoi anche includere uno stato in una risposta per fare in modo che Assistant esegua un'azione specifica in base a una determinata richiesta.

Le seguenti caratteristiche e stati supportano ackNeeded con gli stati delle caratteristiche. Un elenco di una caratteristica specifica indica che tutti i relativi stati sono supportati.

  • ArmDisarm
    • Utilizza il tipo di richiesta di verifica ackNeeded per abilitare o annullare l'abilitazione del dispositivo, ma per le funzioni di disabilitazione e annullamento della disabilitazione è necessario il tipo di richiesta di verifica pinNeeded.
  • Fill
  • LockUnlock
    • Utilizza il tipo di richiesta di verifica ackNeeded per bloccare il dispositivo e il tipo di richiesta di verifica pinNeeded per sbloccarlo.
  • OnOff
    • on
    • Utilizza il tipo di richiesta di verifica ackNeeded per questa caratteristica. Il tipo di richiesta di verifica pinNeeded è obbligatorio quando questa caratteristica viene utilizzata con i dispositivi CAMERA.
  • OpenClose
    • Utilizza il tipo di richiesta di verifica ackNeeded per questa caratteristica. Il tipo di richiesta di verifica pinNeeded è obbligatorio quando questa caratteristica viene utilizzata con i dispositivi DOOR, GARAGE, GATE o WINDOW.
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

Questo esempio mostra una richiesta e una risposta con una richiesta di verifica ackNeeded che utilizza uno stato della caratteristica. Cambia la modalità del condizionatore d'aria in riscaldamento e imposta la temperatura a 28 gradi. Quindi, Assistant chiede agli utenti di confermare l'accensione del riscaldamento e l'impostazione della temperatura a 28 gradi, poiché nella risposta viene restituito un thermostatTemperatureSetpoint di 28 come stato.

Utente Imposta la modalità del condizionatore d'aria su riscaldamento.
Google Assistant Vuoi impostare il riscaldamento del condizionatore d'aria a 28 gradi?
Utente Sì.
Google Assistant Imposto il riscaldamento del condizionatore d'aria a 28 gradi.
Richiesta 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          }
        }]
      }]
    }
  }]
}
Risposta 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Richiesta 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
Risposta 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

pinNeeded

La richiesta di verifica pinNeeded è consigliata per i dispositivi di sicurezza.

Questo esempio mostra una richiesta e una risposta iniziali con una richiesta di verifica pinNeeded. L'esempio restituisce una risposta con una richiesta di verifica pinNeeded quindi Assistant chiede il PIN. A questo punto, l'utente può fornire un PIN errato o valido.

Richiesta e risposta di esempio per un PIN errato o valido:

Utente Apri la porta.
Google Assistant Posso avere il tuo codice di sicurezza?
Richiesta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

PIN errato

Questo esempio mostra la richiesta e la risposta con una richiesta di verifica challengeFailedPinNeeded. Questa richiesta di verifica deve essere utilizzata dopo che una richiesta di verifica pinNeeded iniziale non è andata a buon fine.

Quando viene restituito un tipo challengeFailedPinNeeded, Assistant chiede di nuovo il codice di sicurezza. Se l'utente esegue troppi tentativi non riusciti, puoi restituire una risposta di errore tooManyFailedAttempts. Consulta Risposte di errore.

Utente 333222
Google Assistant Mi spiace, il codice di sicurezza non è corretto. Posso avere il tuo codice di sicurezza?
Richiesta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333222"
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

PIN valido

Questo esempio mostra la richiesta e la risposta di un PIN valido.

Utente 333444
Google Assistant Apro la porta.
Richiesta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333444"
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}
Utente Attenua la luce del salotto.
Google Assistant Posso avere il tuo codice di sicurezza?
Richiesta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}
Risposta
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Risposte di errore

Di seguito sono riportati alcuni codici di errore che possono essere restituiti con le risposte:

  • tooManyFailedAttempts : Mi spiace, troppi tentativi non riusciti. Vai all'app del dispositivo per completare l'azione.
  • pinIncorrect : Mi spiace, il codice di sicurezza non è corretto.
  • userCancelled : Ok

Consulta l'elenco completo degli errori e delle eccezioni.