Sekundäre Nutzerbestätigung

Mit der sekundären Nutzerbestätigung kannst du Sprachbefehle mit einem zweiten Sicherheitsfaktor versehen. So kannst du bestimmte Aktionen zusätzlich absichern, z. B. das Ausschalten einer Sicherheitskamera oder das Öffnen einer Tür. Die sekundäre Nutzerbestätigung ist nicht an ein bestimmtes Gerätemerkmal gebunden. Du kannst also entscheiden, wann Google Assistant eine Bestätigung anfordern soll. Du kannst beispielsweise eine Challenge für das Attribut OnOff einer Sicherheitskamera ausgeben, aber nicht für das Attribut OnOff einer Lampe. In bestimmten Situationen können auch Assistant-Herausforderungen für dieselbe Aktion ausgegeben werden. Sie können beispielsweise anfordern, dass Assistant eine Challenge-Anfrage zum Öffnen einer Tür ausgibt, wenn sich kein NFC-Schlüsselanhänger in der Nähe dieser Tür befindet, aber keine Challenge-Anfrage ausgibt, wenn der Schlüsselanhänger vorhanden ist.

Der Assistant kann zwei Arten von Challenges ausgeben: explizite Bestätigung oder persönliche Identifikationsnummer (PIN). Dadurch wird den Intents QUERY und EXECUTE, die von Assistant an deine Aktion gesendet werden, ein Challenge-Block hinzugefügt und eine challengeNeeded-Fehlerantwort akzeptiert. Assistant sendet dann die Intent-Anfrage mit den Challenge-Daten im Challenge-Block an deine Aktion zurück. Anschließend können Sie die Daten der Sicherheitsfrage validieren, um festzustellen, ob der Nutzer die richtige Antwort gegeben hat.

Assistant verwendet einen Dialog, um die Aufforderung auszugeben. Wenn du Assistant jedoch auf Oberflächen ohne Sprachausgabe verwendest, werden PIN und Bestätigungen auf dem Bildschirm angezeigt.

Wann die sekundäre Nutzerbestätigung verwendet werden sollte

Du kannst die sekundäre Nutzerbestätigung für jeden Gerätetyp oder jede Eigenschaft aktivieren. Du musst jedoch die sekundäre Nutzerbestätigung für bestimmte sicherheitsrelevante Gerätetypen und ‑merkmale implementieren, damit deine Integration zertifiziert werden kann.

Für die folgenden Kombinationen aus Merkmal und Gerätetyp ist eine sekundäre Nutzerbestätigung mit dem Challenge-Typ pinNeeded erforderlich:

  • Das Attribut OnOff, wenn der Gerätetyp CAMERA ist.
  • Das Attribut OpenClose, wenn der Gerätetyp DOOR, GARAGE, GATE oder WINDOW ist.
  • Das Attribut LockUnlock beim Entsperren.
  • Das Attribut ArmDisarm beim Deaktivieren oder Abbrechen einer Deaktivierung.
  • Das Attribut Reboot, SoftwareUpdate oder NetworkControl, wenn der Gerätetyp NETWORK oder ROUTER ist.

Der Challenge-Typ ackNeeded ist für das Attribut TemperatureSetting erforderlich, wenn der Gerätetyp AC_UNIT ist und die Integration in Japan erfolgt.

Unterstützte Methoden der Identitätsbestätigung

Folgende Arten der sekundären Nutzerbestätigung werden unterstützt:

  • Keine Bestätigung: Eine Anfrage und Antwort, bei der keine sekundäre Nutzerbestätigung verwendet wird.
  • ackNeeded: Eine sekundäre Nutzerbestätigung, die eine explizite Bestätigung (Ja oder Nein) erfordert und auch Eigenschaftsstatus als Antwortfeedback verwenden kann. Dieser Challenge-Typ wird für Sicherheitsgeräte und -merkmale nicht empfohlen.
  • pinNeeded: Eine sekundäre Nutzerbestätigung, die eine persönliche Identifikationsnummer (PIN) erfordert. Diese Option ist ideal für Sicherheitsgeräte und ‑merkmale.

Keine Aufgabe

Dieses Beispiel zeigt eine erfolgreiche EXECUTE-Anfrage und -Antwort ohne Challenge zum Einschalten des Lichts.

Nutzer Schalte das Licht ein.
Google Assistant Ok, ich schalte 3 Lampen ein.
Anfrage
{
  "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
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

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

Es gibt die folgenden Arten von ackNeeded-Herausforderungen:

ackNeeded simple

Dieses Beispiel zeigt eine einfache Anfrage und Antwort mit einer ackNeeded-Challenge, um ein Licht zu dimmen, und die Bestätigung, dass das Licht gedimmt wurde.

Nutzer Dimme das Licht im Wohnzimmer.
Google Assistant Ich dimme das Licht im Wohnzimmer. Sind Sie sicher?
Nutzer Ja.
Google Assistant Ich dimme das Licht im Wohnzimmer.
Anfrage 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
          }
        }]
      }]
    }
  }]
}
Antwort 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Anfrage 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
          }
        }]
      }]
    }
  }]
}
Antwort 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackNeeded mit Trait-Status

Eine sekundäre Nutzerbestätigung, die Status für ein Attribut verwenden kann. Wenn du beispielsweise mit dem Attribut TemperatureSetting arbeitest und sowohl thermostatMode als auch thermostatTemperatureSetpoint festgelegt sind, kann Assistant fragen: Möchtest du die Heizung der Klimaanlage wirklich auf 28 Grad einstellen?

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

Die folgenden Attribute und Status unterstützen ackNeeded mit Attributstatus. Wenn ein bestimmtes Attribut aufgeführt ist, werden alle zugehörigen Status unterstützt.

  • ArmDisarm
    • Verwende den Challenge-Typ ackNeeded, um das Gerät scharfzuschalten oder die Scharfschaltung abzubrechen. Für die Funktionen zum Deaktivieren und Abbrechen der Deaktivierung ist jedoch der Challenge-Typ pinNeeded erforderlich.
  • Fill
  • LockUnlock
    • Verwende den Challenge-Typ ackNeeded, um das Gerät zu sperren, und den Challenge-Typ pinNeeded, um es zu entsperren.
  • OnOff
    • on
    • Verwenden Sie für dieses Merkmal den Challenge-Typ ackNeeded. Der Anforderungstyp pinNeeded ist erforderlich, wenn dieses Attribut mit CAMERA-Geräten verwendet wird.
  • OpenClose
    • Verwenden Sie für dieses Merkmal den Challenge-Typ ackNeeded. Der Challenge-Typ pinNeeded ist erforderlich, wenn dieses Attribut mit DOOR-, GARAGE-, GATE- oder WINDOW-Geräten verwendet wird.
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

Dieses Beispiel zeigt eine Anfrage und eine Antwort mit einer ackNeeded-Challenge, die einen Attributstatus verwendet. Der Modus der Klimaanlage wird auf „Heizen“ geändert und die Temperatur auf 28 Grad eingestellt. Anschließend bittet Assistant die Nutzer um Bestätigung, dass die Heizung eingeschaltet und die Temperatur auf 28 Grad eingestellt werden soll, da in der Antwort ein thermostatTemperatureSetpoint von 28 als Status zurückgegeben wird.

Nutzer Stelle den Modus der Klimaanlage auf „Heizen“.
Google Assistant Möchtest du die Heizung der Klimaanlage wirklich auf 28 Grad einstellen?
Nutzer Ja.
Google Assistant Die Temperatur der Klimaanlage wird auf 28 Grad gestellt.
Anfrage 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"
          }
        }]
      }]
    }
  }]
}
Antwort 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Anfrage 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
          }
        }]
      }]
    }
  }]
}
Antwort 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

pinNeeded

Die pinNeeded-Aufgabe wird für Sicherheitsgeräte empfohlen.

In diesem Beispiel sehen Sie eine erste Anfrage und Antwort mit einer pinNeeded-Aufgabe. Das Beispiel gibt eine Antwort mit einer pinNeeded-Anforderung zurück, sodass Assistant nach der PIN fragt. An diesem Punkt kann der Nutzer eine falsche oder gültige PIN eingeben.

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

Nutzer Entriegeln Sie die Tür.
Google Assistant Wie lautet der Sicherheitscode?
Anfrage
{
  "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
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Falsche PIN

In diesem Beispiel werden die Anfrage und die Antwort mit einer challengeFailedPinNeeded-Aufgabe gezeigt. Diese Challenge sollte verwendet werden, nachdem eine erste pinNeeded-Challenge fehlgeschlagen ist.

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

Nutzer 333222
Google Assistant Der Sicherheitscode ist leider falsch. Wie lautet der Sicherheitscode?
Anfrage
{
  "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"
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

Gültige PIN

In diesem Beispiel sehen Sie die Anfrage und Antwort für eine gültige PIN.

Nutzer 333444
Google Assistant Die Tür wird entriegelt.
Anfrage
{
  "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"
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}
Nutzer Dimme das Licht im Wohnzimmer.
Google Assistant Wie lautet der Sicherheitscode?
Anfrage
{
  "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
          }
        }]
      }]
    }
  }]
}
Antwort
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Fehlerantworten

Hier sind einige Fehlercodes, die mit Ihren Antworten zurückgegeben werden können:

  • tooManyFailedAttempts – Zu viele fehlgeschlagene Versuche. Bitte öffne die App auf deinem Gerät, um diese Aktion auszuführen.
  • pinIncorrect – Der Sicherheitscode ist falsch.
  • userCancelled – Ok

Vollständige Liste der Fehler und Ausnahmen