Sekundäre Nutzerbestätigung

Mit der sekundären Nutzerbestätigung können Sie Sprachbefehlen einen zweiten Sicherheitsfaktor hinzufügen. So können Sie bestimmte Aktionen zusätzlich schützen, z. B. das Deaktivieren einer Überwachungskamera oder das Öffnen einer Tür. Die sekundäre Nutzerbestätigung ist nicht an ein bestimmtes Gerätemerkmal gebunden. So können Sie entscheiden, wann Google Assistant eine Aufgabe ausgeben soll. Sie können beispielsweise eine Aufgabe für das OnOff Merkmal einer Überwachungskamera ausgeben, aber nicht für das OnOff Merkmal einer Lampe. Sie können auch festlegen, dass Assistant in bestimmten Situationen Aufgaben für dieselbe Aktion ausgibt. Beispielsweise können Sie festlegen, dass Assistant eine Aufgabe zum Öffnen einer Tür ausgibt, wenn sich kein NFC-Schlüsselanhänger in der Nähe der Tür befindet. Wenn der Schlüsselanhänger vorhanden ist, soll keine Aufgabe ausgegeben werden.

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

Assistant gibt die Aufgabe über einen Dialog aus. Wenn Sie jedoch Assistant auf Oberflächen verwenden, die keine Sprachausgabe unterstützen, werden PIN und Bestätigungen auf dem Bildschirm angezeigt.

Wann sollte die sekundäre Nutzerbestätigung verwendet werden?

Sie können die sekundäre Nutzerbestätigung für jeden Gerätetyp oder jedes Merkmal aktivieren. Für bestimmte sicherheitsrelevante Gerätetypen und Merkmale müssen Sie die sekundäre Nutzerbestätigung jedoch implementieren, um Ihre Integration zertifizieren zu lassen.

Die sekundäre Nutzerbestätigung mit dem Aufgabentyp pinNeeded ist für die folgenden Kombinationen aus Merkmal und Gerätetyp erforderlich:

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

Der Aufgabentyp ackNeeded ist für das Merkmal TemperatureSetting erforderlich, wenn der Gerätetyp AC_UNIT ist und sich der Standort der Integration in Japan befindet.

Unterstützte Aufgabentypen

Folgende Aufgabentypen für die sekundäre Nutzerbestätigung werden unterstützt:

  • Keine Aufgabe: Eine Anfrage und Antwort, bei der keine Aufgabe für die sekundäre Nutzerbestätigung verwendet wird.
  • ackNeeded: Eine sekundäre Nutzerbestätigung, die eine explizite Bestätigung (Ja oder Nein) erfordert. Außerdem können Merkmalsstatus als Antwort-Feedback verwendet werden. Dieser Aufgabentyp wird für Sicherheitsgeräte und ‑merkmale nicht empfohlen.
  • pinNeeded: Eine sekundäre Nutzerbestätigung, die eine persönliche Identifikationsnummer (PIN) erfordert. Dieser Aufgabentyp ist ideal für Sicherheitsgeräte und ‑merkmale.

Keine Aufgabe

Dieses Beispiel zeigt eine erfolgreiche EXECUTE-Anfrage und ‑Antwort ohne Aufgabe 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 Nutzerbestätigung, bei der mehrere Status für ein Merkmal oder eine einfache Bestätigung verwendet werden können.

Es gibt die folgenden Arten von ackNeeded-Aufgabentypen:

ackNeeded (einfach)

Dieses Beispiel zeigt eine einfache Anfrage und Antwort mit einer ackNeeded-Aufgabe zum Dimmen einer Lampe und der Bestätigung, die Lampe zu dimmen.

Nutzer Dimme das Licht im Wohnzimmer.
Google Assistant Ich dimme das Licht im Wohnzimmer. Bist du 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 Merkmalsstatus

Eine sekundäre Nutzerbestätigung, bei der Status für ein Merkmal verwendet werden können. Wenn Sie beispielsweise mit dem TemperatureSetting Merkmal arbeiten und sowohl thermostatMode als auch thermostatTemperatureSetpoint festgelegt sind, Assistant kann fragen: Möchtest du die Temperatur 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 Merkmale und Status unterstützen ackNeeded mit Merkmalsstatus. Wenn ein bestimmtes Merkmal aufgeführt ist, werden alle zugehörigen Status unterstützt.

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

Dieses Beispiel zeigt eine Anfrage und Antwort mit einer ackNeeded-Aufgabe, bei der ein Merkmalsstatus verwendet wird. Der Klimaanlagenmodus wird auf „Heizen“ geändert und die Temperatur auf 28 Grad eingestellt. Anschließend fordert Assistant die Nutzer zur Bestätigung auf, die Heizung einzuschalten und die Temperatur auf 28 Grad einzustellen, da in der Antwort ein thermostatTemperatureSetpoint von 28 als Status zurückgegeben wird.

Nutzer Stell den Klimaanlagenmodus auf „Heizen“.
Google Assistant Möchtest du die Temperatur der Klimaanlage wirklich auf 28 Grad einstellen?
Nutzer Ja.
Google Assistant Ich stelle die Temperatur der Klimaanlage auf 28 Grad ein.
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.

Dieses Beispiel zeigt eine erste Anfrage und Antwort mit einer pinNeeded-Aufgabe. Das Beispiel gibt eine Antwort mit einer pinNeeded Aufgabe zurück, sodass Assistant nach der PIN fragt. An dieser Stelle 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 Entsperre die Tür.
Google Assistant Kannst du mir den richtigen geben?
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

Dieses Beispiel zeigt die Anfrage und Antwort mit einer challengeFailedPinNeeded-Aufgabe. Diese Aufgabe sollte verwendet werden, nachdem eine erste pinNeeded-Aufgabe fehlgeschlagen ist.

Wenn ein challengeFailedPinNeeded-Typ zurückgegeben wird, Assistant fragt noch einmal nach dem Sicherheitscode. 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

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

Nutzer 333444
Google Assistant Ich entsperre die Tür.
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 Kannst du mir den richtigen geben?
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

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

  • tooManyFailedAttempts : Tut mir leid, zu viele fehlgeschlagene Versuche. Schließ den Vorgang in der App deines Geräts ab.
  • pinIncorrect : Der Sicherheitscode ist leider falsch.
  • userCancelled : Ok

Eine vollständige Liste der Fehler und Ausnahmenfinden Sie hier.