Willkommen beim Google Home Developer Center, der neuen Anlaufstelle für Informationen über Smart-Home-Aktionen. Hinweis:Die Aktionen in der Actions Console werden weiterhin erstellt.

Sekundäre Nutzerbestätigung

Mit der zweiten Nutzerüberprüfung können Sie Sicherheitsbefehlen die Bestätigung in zwei Schritten hinzufügen. So lassen sich zusätzliche Sicherheitsmaßnahmen für bestimmte Aktionen hinzufügen, z. B. um eine Sicherheitskamera auszuschalten oder eine Tür zu öffnen. Die sekundäre Nutzerbestätigung ist nicht an eine bestimmte Geräteeigenschaft gebunden, mit der Sie entscheiden können, wann Google Assistant ein Problem ausstellen soll. Sie können beispielsweise festlegen, dass für eine Sicherheitskamera der Hinweis OnOff und für eine Lampe nicht der Hinweis OnOff verwendet wird. In bestimmten Situationen kann es auch Assistant Herausforderungen für dieselbe Aktion geben. Sie können beispielsweise Assistant auffordern, eine Tür zu öffnen, wenn sich kein NFC-Schlüsselanhänger in der Nähe befindet. Wenn der Schlüsselanhänger vorhanden ist, können Sie jedoch keinen Wettkampf ausführen.

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

Assistant verwendet den Dialog, um den Wettkampf auszuführen. Wenn du Assistant jedoch auf Nicht-Sprachbefehlen verwendest, werden PINs und Bestätigungen auf dem Bildschirm angezeigt.

Unterstützte Gerätetypen

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

Unterstützte Gerätemerkmale

Die sekundäre Nutzerbestätigung wird für alle Gerätemerkmale unterstützt.

Unterstützte Challenges

Die folgenden Bestätigungstypen für sekundäre Nutzer werden unterstützt:

  • Keine Identitätsbestätigung: Eine Anfrage und Antwort, die keine sekundäre Bestätigungsaufforderung für Nutzer verwendet.
  • ackneeded: Eine sekundäre Nutzerbestätigung, die eine explizite Bestätigung (Ja oder Nein) erfordert und auch Merkmale als Antwort-Feedback verwenden kann. Dieser Sicherheitstyp wird für Sicherheitsgeräte und -merkmale nicht empfohlen.
  • pin Needed: Eine sekundäre Nutzerbestätigung, die eine persönliche Identifikationsnummer (PIN) erfordert. Diese ist ideal für Sicherheitsgeräte und -merkmale.

Kein Wettkampf

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

Nutzer Schalte das Licht ein.
Google Assistant Ok, 3 Lampen werden eingeschaltet.
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
      }
    }]
  }
}

Bestätigung erforderlich

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

Es gibt die folgenden Arten von ackNeeded-Herausforderungen:

Bestätigung erforderlich

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

Nutzer Dimm das Wohnzimmerlicht.
Google Assistant Das Licht im Wohnzimmer wird gedimmt. Bist du 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"
    }]
  }
}

Fehlender Status bei Anforderungen

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

Außerdem haben Sie die Möglichkeit, einen Status in eine Antwort aufzunehmen, damit Assistant anhand einer bestimmten Anfrage eine bestimmte Aktion ausführt.

Die folgenden Merkmale und Bundesstaaten unterstützen ackNeeded mit Eigenschaftszuständen. Eine Liste einer bestimmten Eigenschaft zeigt an, dass alle zugehörigen Merkmale unterstützt werden.

Dieses Beispiel zeigt eine Anfrage und eine Antwort mit einer ackNeeded-Herausforderung, die einen Eigenschaftsstatus verwendet. Er schaltet die Klimaanlage in den Heizmodus und stellt die Temperatur auf 28 Grad ein. Dann Assistant müssen die Nutzer die Bestätigung annehmen, damit die Heizung eingeschaltet und die Temperatur auf 28 Grad festgelegt werden, da ein thermostatTemperatureSetpoint von 28 als Status in der Antwort zurückgegeben wird.

Nutzer Stelle den Heizungsmodus auf „Heizen“ ein.
Google Assistant Möchtest du die Heizung in der Klimaanlage wirklich auf 28 Grad stellen?
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
      }
    }]
  }
}

Anpinnen erforderlich

Der Wettkampf „pinNeeded“ wird für Sicherheitsgeräte empfohlen.

Dieses Beispiel zeigt eine erste Anfrage und Antwort mit einem pinNeeded-Wettkampf. Das Beispiel gibt eine Antwort mit dem Wettkampf pinNeeded zurück. Also fragt Assistant nach der PIN. An dieser Stelle kann der Nutzer eine falsche oder gültige PIN angeben.

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

Nutzer Tür entriegeln.
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

Dieses Beispiel zeigt die Anfrage und die Antwort bei einer challengeFailedPinNeeded-Herausforderung. Dieser Wettkampf sollte verwendet werden, nachdem ein erster pinNeeded-Wettkampf 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, kann eine tooManyFailedAttempts-Fehlerantwort zurückgegeben werden. 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 Die Tür 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 Dimm das Wohnzimmerlicht.
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:

  • challengeFailedNotSetup: Für diese Aktion ist ein Sicherheitscode erforderlich, aber dieser wurde in der App deines Geräts noch nicht eingerichtet.
  • tooManyFailedAttempts: Leider zu viele Fehlversuche. Rufe die App auf deinem Gerät auf, um diese Aktion abzuschließen.
  • pinIncorrect – Der Sicherheitscode ist falsch.
  • userCancelled – Okay.

Hier finden Sie die vollständige Liste der Fehler und Ausnahmen.