Sekundäre Nutzerbestätigung

Mit der sekundären Nutzerbestätigung können Sie Sprachbefehlen eine 2‑Faktor-Authentifizierung hinzufügen. So können Sie bestimmte Aktionen wie das Ausschalten einer Sicherheitskamera oder das Öffnen einer Tür zusätzlich absichern. Die sekundäre Nutzerbestätigung ist nicht an ein bestimmtes Geräteattribut gebunden. Sie können also selbst entscheiden, wann Google Assistant eine Aufforderung ausgibt. Sie können beispielsweise eine Sicherheitsmaßnahme für das Attribut OnOff einer Sicherheitskamera, aber nicht für das Attribut OnOff einer Lampe auslösen. Assistant kann in bestimmten Situationen auch Herausforderungen für dieselbe Aktion ausgeben. 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 ausgibt, wenn der Schlüsselanhänger vorhanden ist.

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

Assistant verwendet Dialoge, um die Challenge zu stellen. Wenn Sie Assistant auf Oberflächen ohne Sprachausgabe verwenden, werden PIN und Bestätigungen auf dem Bildschirm angezeigt.

Wann die sekundäre Nutzerbestätigung verwendet werden sollte

Sie können die sekundäre Nutzerbestätigung für jeden Gerätetyp oder jedes Merkmal aktivieren. Für bestimmte sicherheitssensible Gerätetypen und Merkmale müssen Sie jedoch die sekundäre Nutzerbestätigung implementieren, damit Ihre 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 Merkmal OpenClose, wenn der Gerätetyp DOOR, GARAGE, GATE oder WINDOW ist.
  • Der LockUnlock-Trait beim Entriegeln.
  • Das Attribut ArmDisarm beim Deaktivieren oder Abbrechen der Deaktivierung.
  • Das Attribut Reboot, SoftwareUpdate oder NetworkControl, wenn der Gerätetyp NETWORK oder ROUTER ist.

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

Unterstützte Challenge-Typen

Folgende Arten von sekundären Nutzerbestätigungsaufforderungen werden unterstützt:

  • Keine Aufgabe: Eine Anfrage und Antwort, bei der keine Aufgabe zur sekundären Nutzerbestätigung verwendet wird.
  • ackNeeded: Eine sekundäre Nutzerbestätigung, die eine explizite Bestätigung („Ja“ oder „Nein“) erfordert und auch Attributstatus als Antwort-Feedback verwenden kann. Dieser Challenge-Typ 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. Sie ist ideal für Sicherheitsgeräte und ‑merkmale.

Keine Aufgabe

In diesem Beispiel wird eine erfolgreiche EXECUTE-Anfrage und ‑Antwort ohne Aufforderung zum Einschalten der Beleuchtung gezeigt.

Nutzer Schalte das Licht ein.
Google Assistant Ok, ich schalte drei 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 Nutzerbestätigungsauthentifizierung, die mehrere Status für ein Attribut oder eine einfache Bestätigungsauthentifizierung verwenden kann.

Es gibt die folgenden Arten von ackNeeded-Herausforderungen:

ackNeeded simple

Dieses Beispiel zeigt eine einfache Anfrage und Antwort mit einer ackNeeded-Herausforderung zum Dimmen eines Lichts und der Bestätigung, dass das Licht gedimmt wurde.

Nutzer Dimme das Licht im Wohnzimmer.
Google Assistant Das Licht im Wohnzimmer wird gedimmt. Sind Sie sicher?
Nutzer Ja.
Google Assistant Das Licht im Wohnzimmer wird gedimmt.
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 Authentifizierung zur Bestätigung durch einen sekundären Nutzer, bei der Status für ein Trait verwendet werden können. Wenn Sie beispielsweise mit dem Merkmal TemperatureSetting arbeiten 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 Eigenschaften und Status unterstützen ackNeeded mit Eigenschaftsstatus. Wenn ein bestimmtes Merkmal aufgeführt ist, werden alle seine Status unterstützt.

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

In diesem Beispiel werden eine Anfrage und eine Antwort mit einer ackNeeded-Herausforderung gezeigt, bei der ein Trait-Status verwendet wird. Dadurch wird der Klimaanlagenmodus auf „Heizen“ geändert und die Temperatur auf 28 Grad eingestellt. Assistant bittet die Nutzer dann um die 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 Klimaanlagenmodus 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-Herausforderung wird für Sicherheitsgeräte empfohlen.

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

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

Nutzer Entriegle die Tür.
Google Assistant Kann ich deinen Sicherheitscode haben?
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 sehen Sie die Anfrage und Antwort mit einer challengeFailedPinNeeded-Challenge. Diese Challenge sollte verwendet werden, nachdem eine erste pinNeeded-Challenge fehlgeschlagen ist.

Wenn der Typ challengeFailedPinNeeded zurückgegeben wird, fordert Assistant den Sicherheitscode noch einmal an. Wenn der Nutzer zu viele fehlgeschlagene Versuche unternimmt, können Sie eine tooManyFailedAttempts-Fehlerantwort zurückgeben. Weitere Informationen finden Sie unter Fehlerantworten.

Nutzer 333222
Google Assistant Der Sicherheitscode ist leider falsch. Kann ich deinen Sicherheitscode haben?
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 werden die Anfrage und die Antwort für eine gültige PIN gezeigt.

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 Kann ich deinen Sicherheitscode haben?
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 – Tut mir leid, zu viele fehlgeschlagene Versuche. Schließe den Vorgang in der App deines Geräts ab.
  • pinIncorrect – Der Sicherheitscode ist leider falsch.
  • userCancelled – Ok

Vollständige Liste der Fehler und Ausnahmen