Sekundäre Nutzerbestätigung

Mit der sekundären Nutzerbestätigung können Sie die Zwei-Faktor-Sicherheit zu Sprachbefehlen hinzufügen. So können Sie die Sicherheit für bestimmte Aktionen wie das Ausschalten einer Sicherheitskamera oder das Öffnen einer Tür erhöhen. Die sekundäre Nutzerbestätigung ist nicht an eine bestimmte Geräteeigenschaft gebunden. Dadurch kannst du entscheiden, wann eine Identitätsbestätigung mit Google Assistant durchgeführt werden soll. Sie können beispielsweise eine Herausforderung für die Trait OnOff für eine Sicherheitskamera, aber keine Herausforderung für die Trait OnOff für eine Lampe erstellen. Es können auch Assistant-Identitätsbestätigungen für dieselbe Aktion in bestimmten Situationen vorliegen. Sie können beispielsweise von Assistant eine Aufforderung zum Öffnen einer Tür anfordern, wenn sich ein NFC-Schlüsselanhänger nicht in der Nähe dieser Tür befindet, aber keine Identitätsbestätigung ausführen, wenn der Schlüsselanhänger vorhanden ist.

Die Assistant kann zwei Arten von Identitätsbestätigungen ausgeben: explizite Bestätigung oder persönliche Identifikationsnummer (PIN). Dadurch wird den QUERY- und EXECUTE-Intents, die von Assistant zurück an Ihre Aktion gesendet werden, eine Challenge hinzugefügt. Außerdem wird die Fehlerantwort challengeNeeded akzeptiert. Assistant sendet dann die Intent-Anfrage mit den Daten zur Identitätsbestätigung im Challenge-Block an Ihre Aktion zurück. Sie können dann die Daten der Identitätsbestätigung überprüfen, um festzustellen, ob der Nutzer die richtige Sicherheitsantwort gegeben hat.

Assistant verwendet ein Dialogfeld, um die Identitätsbestätigung durchzuführen. Wenn Sie jedoch Assistant auf Oberflächen verwenden, die keine Sprachfunktionen sind, werden PIN und Bestätigungen auf dem Bildschirm vorgenommen.

Unterstützte Gerätetypen

Die sekundäre Nutzerbestätigung wird auf allen Gerätetypen unterstützt.

Unterstützte Geräte-Traits

Die sekundäre Nutzerbestätigung wird für alle Geräte-Traits unterstützt.

Unterstützte Arten der Identitätsbestätigung

Folgende sekundäre Arten der Identitätsbestätigung werden unterstützt:

• Keine Identitätsbestätigung: Eine Anfrage und Antwort, für die keine sekundäre Identitätsbestätigung genutzt wird.
• ackneeded: Eine sekundäre Nutzerbestätigung, die eine explizite Bestätigung (ja oder nein) erfordert und auch Eigenschaftsstatus als Antwortfeedback verwenden kann. Dieser Aufgabentyp wird für Sicherheitsgeräte und -merkmale nicht empfohlen.
• pinneeded – Eine sekundäre Nutzerbestätigung, für die eine persönliche Identifikationsnummer (PIN) erforderlich ist. Diese ist ideal für Sicherheitsgeräte und -merkmale.

Keine Herausforderung

Dieses Beispiel zeigt eine erfolgreiche EXECUTE-Anfrage und -Antwort, ohne dass das Licht eingeschaltet werden muss.

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

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

Bestätigt

Eine sekundäre Authentifizierung zur Nutzerbestätigung, die mehrere Status für eine Eigenschaft oder eine einfache Bestätigungsauthentifizierung verwenden kann.

Es gibt die folgenden Arten von ackNeeded-Challenges:

• ackneeded simple
• ackneeded mit Trait-Status

ackneeded – einfach

Dieses Beispiel zeigt eine einfache Anfrage und Antwort mit der Aufforderung ackNeeded zum Dimmen eines Lichts und einer Bestätigung zum Dimmen.

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

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

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

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

Mit Trait-Status bestätigt

Eine sekundäre Authentifizierung zur Nutzerbestätigung, die Status für eine Eigenschaft verwenden kann. Wenn Sie beispielsweise mit dem Trait TemperatureSetting arbeiten und sowohl thermostatMode als auch thermostatTemperatureSetpoint festgelegt sind, kann Assistant fragen: Möchten Sie die Heizung der Klimaanlage wirklich auf 28 Grad stellen?

Sie können auch einen Status in eine Antwort aufnehmen, damit Assistant basierend auf einer bestimmten Anfrage eine bestimmte Aktion ausführt.

Die folgenden Traits und Status unterstützen ackNeeded mit Traits-Status. Eine Auflistung einer bestimmten Eigenschaft gibt an, dass alle zugehörigen Stadien unterstützt werden.

• ArmDisarm
• currentArmLevel
• currentStatusReport
• Fill
• LockUnlock
• OnOff
• on
• OpenClose
• Scene
• TemperatureSetting
• thermostatMode
• thermostatTemperatureSetpoint
• thermostatTemperatureSetpointHigh
• thermostatTemperatureSetpointLow

Dieses Beispiel zeigt eine Anfrage und eine Antwort mit der ackNeeded-Abfrage, bei der ein Trait-Status verwendet wird. Der Klimaanlagenmodus wird auf „Heizen“ gestellt und die Temperatur wird auf 28 Grad eingestellt. Anschließend fordert Assistant die Nutzer auf, zu bestätigen, dass sie die Heizung einschalten und die Temperatur auf 28 Grad einstellen dürfen, da ein thermostatTemperatureSetpoint von 28 als Status in der Antwort zurückgegeben wird.

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

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

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

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

Pinneeded

Für Sicherheitsgeräte wird die pinNeeded-Identitätsbestätigung empfohlen.

Dieses Beispiel zeigt eine erste Anfrage und eine erste Antwort mit einer pinNeeded-Challenge. In diesem Beispiel wird eine Antwort mit einer pinNeeded-Abfrage zurückgegeben. Daher fordert Assistant die PIN an. An dieser Stelle kann der Nutzer eine falsche oder gültige PIN angeben.

Beispielanfrage und Antwort für eine falsche oder gültige PIN:

• Falsche PIN
• Gültige PIN

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

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Falsche PIN

Dieses Beispiel zeigt die Anfrage und die Antwort mit einer challengeFailedPinNeeded-Challenge. Diese Identitätsbestätigung sollte verwendet werden, nachdem die erste pinNeeded-Abfrage fehlgeschlagen ist.

Wenn ein challengeFailedPinNeeded-Typ zurückgegeben wird, fragt Assistant noch einmal nach dem Sicherheitscode. Wenn der Nutzer zu viele fehlgeschlagene Versuche ausführt, können Sie die Fehlerantwort tooManyFailedAttempts zurückgeben. Siehe Fehlerantworten.

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

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

Gültige PIN

Dieses Beispiel zeigt die Anforderung und Antwort einer gültigen PIN.

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

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}

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

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Fehlerantworten

Im Folgenden sind einige Fehlercodes aufgeführt, die mit Ihren Antworten zurückgegeben werden können:

• challengeFailedNotSetup: Für diese Aktion ist ein Sicherheitscode erforderlich, aber noch nicht in der App Ihres Geräts eingerichtet.
• tooManyFailedAttempts: Leider zu viele fehlgeschlagene Versuche. Bitte öffne die App auf deinem Gerät, um diese Aktion abzuschließen.
• pinIncorrect: Der Sicherheitscode ist falsch.
• userCancelled: OK.

Sehen Sie sich die vollständige Liste der Fehler und Ausnahmen an.