Weryfikacja dodatkowego użytkownika

Dodatkowa weryfikacja użytkownika umożliwia dodanie drugiego etapu zabezpieczeń do poleceń głosowych. Umożliwia to dodanie dodatkowych zabezpieczeń w przypadku niektórych działań, takich jak wyłączenie kamery monitoringu czy otwarcie drzwi. Dodatkowa weryfikacja użytkownika nie jest powiązana z określoną cechą urządzenia, co pozwala Ci decydować, kiedy Google Assistant ma wysyłać test zabezpieczający. Możesz na przykład zdecydować się na wysłanie żądania weryfikacji w przypadku cechy OnOff kamery monitoringu, ale nie w przypadku cechy OnOff światła. Możesz też Assistant w określonych sytuacjach rzucać wyzwania w ramach tego samego działania. Możesz na przykład poprosić Assistant o wysłanie żądania weryfikacji w celu otwarcia drzwi, jeśli brelok NFC nie znajduje się w pobliżu tych drzwi, ale nie wysyłać żądania, jeśli brelok jest w pobliżu.

Assistant może wysyłać 2 rodzaje żądań weryfikacji: potwierdzenie lub osobisty numer identyfikacyjny (PIN). Spowoduje to dodanie bloku weryfikacji do intencji QUERY i EXECUTE wysyłanych z Assistant z powrotem do działania oraz zaakceptowanie odpowiedzi z błędem challengeNeeded. Assistant odsyła żądanie intencji do Twojej działania z danymi weryfikacyjnymi w bloku weryfikacyjnym. Następnie możesz zweryfikować dane wyzwania, aby sprawdzić, czy użytkownik podał prawidłową odpowiedź zabezpieczającą.

Assistant używa dialogu do wydania polecenia, ale jeśli używasz Assistant na platformach innych niż głosowe, kod PIN i potwierdzenia są wyświetlane na ekranie.

Kiedy używać dodatkowej weryfikacji użytkownika

Dodatkową weryfikację użytkownika możesz włączyć w przypadku dowolnego typu urządzenia lub cechy. Aby uzyskać certyfikat integracji, musisz jednak wdrożyć dodatkową weryfikację użytkownika w przypadku niektórych typów urządzeń i cech związanych z bezpieczeństwem.

Wymagana jest dodatkowa weryfikacja użytkownika za pomocą typu testu pinNeeded w przypadku tych kombinacji cech i typów urządzeń:

  • Cechę OnOff, jeśli typ urządzenia to CAMERA.
  • Cechę OpenClose, jeśli typ urządzenia to DOOR, GARAGE, GATE lub WINDOW.
  • LockUnlock podczas odblokowywania.
  • Cechę ArmDisarm podczas rozbrajania lub anulowania rozbrajania.
  • Cechy Reboot, SoftwareUpdate lub NetworkControl, jeśli typ urządzenia to NETWORK lub ROUTER.

W przypadku TemperatureSettingcechyAC_UNIT wymagany jest ackNeededtyp weryfikacjiAC_UNIT, jeśli typ urządzenia to AC_UNIT, a integracja jest lokalizacją w Japonii.

Obsługiwane typy wyzwań

Obsługiwane typy testów dodatkowej weryfikacji użytkownika:

  • Brak dodatkowej weryfikacji – żądanie i odpowiedź, które nie używają dodatkowej weryfikacji użytkownika.
  • ackNeeded – dodatkowa weryfikacja użytkownika, która wymaga wyraźnego potwierdzenia (tak lub nie) i może też wykorzystywać stany cech jako informacje zwrotne. Ten typ weryfikacji nie jest zalecany w przypadku urządzeń i cech związanych z bezpieczeństwem.
  • pinNeeded – dodatkowa weryfikacja użytkownika, która wymaga podania osobistego numeru identyfikacyjnego (PIN). Jest to idealne rozwiązanie w przypadku urządzeń i cech związanych z bezpieczeństwem.

Brak wymogów

Ten przykład pokazuje udane żądanie EXECUTE i odpowiedź bez wyzwania dotyczącego włączenia świateł.

Użytkownik Włącz światła.
Google Assistant OK, włączam 3 światła.
Prośba
{
  "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
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

Dodatkowe uwierzytelnianie użytkownika, które może korzystać z wielu stanów w przypadku cechy lub prostego uwierzytelniania potwierdzającego.

Istnieją następujące rodzaje ackNeeded wyzwań:

ackNeeded simple

Ten przykład przedstawia proste żądanie i odpowiedź z ackNeeded wyzwaniem dotyczącym przyciemnienia światła oraz potwierdzenie przyciemnienia światła.

Użytkownik Przyciemnij światło w salonie.
Google Assistant Przyciemniam światło w salonie. Na pewno?
Użytkownik Tak.
Google Assistant Przyciemniam światło w salonie.
Prośba 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
          }
        }]
      }]
    }
  }]
}
Odpowiedź 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Prośba 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
          }
        }]
      }]
    }
  }]
}
Odpowiedź 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackNeeded ze stanami cech

Dodatkowe uwierzytelnianie potwierdzenia użytkownika, które może używać stanów w przypadku cechy. Jeśli na przykład korzystasz z cechy TemperatureSetting i ustawione są zarówno thermostatMode, jak i thermostatTemperatureSetpoint, Assistant może zapytać Czy na pewno chcesz ustawić ogrzewanie klimatyzatora na 28 stopni?

Możesz też uwzględnić w odpowiedzi stan, aby Assistant wykonał określone działanie na podstawie danego żądania.

ackNeeded z atrybutami stanu obsługują te cechy i stany: Wymienienie konkretnej cechy oznacza, że obsługiwane są wszystkie jej stany.

  • ArmDisarm
    • Użyj typu weryfikacji ackNeeded, aby włączyć lub anulować włączenie urządzenia, ale w przypadku funkcji wyłączania i anulowania wyłączania wymagany jest typ weryfikacji pinNeeded.
  • Fill
  • LockUnlock
    • Użyj typu wyzwania ackNeeded, aby zablokować urządzenie, i typu wyzwania pinNeeded, aby je odblokować.
  • OnOff
    • on
    • Użyj typu wyzwania ackNeeded dla tej cechy. Typ weryfikacji pinNeeded jest wymagany, gdy ta cecha jest używana z urządzeniami CAMERA.
  • OpenClose
    • Użyj typu wyzwania ackNeeded dla tej cechy. Typ weryfikacji pinNeeded jest wymagany, gdy ta cecha jest używana z urządzeniami DOOR, GARAGE, GATE lub WINDOW.
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

Ten przykład pokazuje żądanie i odpowiedź z testem zabezpieczającym ackNeeded, który korzysta ze stanu cechy. Zmienia tryb klimatyzacji na grzanie i ustawia temperaturę na 28 stopni. Następnie Assistant prosi użytkowników o potwierdzenie włączenia ogrzewania i ustawienia temperatury na 28 stopni, ponieważ w odpowiedzi zwrócono thermostatTemperatureSetpoint o wartości 28 jako stan.

Użytkownik Ustaw tryb klimatyzacji na ogrzewanie.
Google Assistant Czy na pewno chcesz ustawić ogrzewanie w klimatyzatorze na 28 stopni?
Użytkownik Tak.
Google Assistant Ustawiam ogrzewanie na klimatyzatorze na 28 stopni.
Prośba 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"
          }
        }]
      }]
    }
  }]
}
Odpowiedź 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Prośba 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
          }
        }]
      }]
    }
  }]
}
Odpowiedź 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

pinNeeded

pinNeeded Wyzwanie jest zalecane w przypadku urządzeń zabezpieczających.

Ten przykład pokazuje początkowe żądanie i odpowiedź z pinNeededwyzwaniem. W tym przykładzie zwracana jest odpowiedź z testem pinNeeded, więc Assistant prosi o podanie kodu PIN. W tym momencie użytkownik może podać nieprawidłowy lub prawidłowy kod PIN.

Przykładowe żądanie i odpowiedź w przypadku nieprawidłowego lub prawidłowego kodu PIN:

Użytkownik Otwórz drzwi.
Google Assistant Czy możesz podać kod zabezpieczający?
Prośba
{
  "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
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Błędny kod PIN

Ten przykład pokazuje żądanie i odpowiedź z wyzwaniem challengeFailedPinNeeded. Z tego wyzwania należy skorzystać po nieudanej próbie początkowego pinNeeded wyzwania.

Gdy zwracany jest typ challengeFailedPinNeeded,Assistant ponownie prosi o kod zabezpieczający. Jeśli użytkownik wykona zbyt wiele nieudanych prób, możesz zwrócić tooManyFailedAttempts odpowiedź z błędem. Zobacz Komunikaty o błędach.

Użytkownik 333222
Google Assistant Kod zabezpieczający jest nieprawidłowy. Czy możesz podać kod zabezpieczający?
Prośba
{
  "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"
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

Prawidłowy kod PIN

Ten przykład pokazuje żądanie i odpowiedź dotyczące prawidłowego kodu PIN.

Użytkownik 333444
Google Assistant Otwieram zamek w drzwiach.
Prośba
{
  "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"
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}
Użytkownik Przyciemnij światło w salonie.
Google Assistant Czy możesz podać kod zabezpieczający?
Prośba
{
  "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
          }
        }]
      }]
    }
  }]
}
Odpowiedź
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Odpowiedzi na błędy

Oto niektóre kody błędów, które mogą być zwracane w odpowiedziach:

  • tooManyFailedAttempts – Przepraszamy, zbyt wiele nieudanych prób. Otwórz aplikację na urządzeniu, aby dokończyć tę czynność.
  • pinIncorrect – Przepraszamy, kod zabezpieczający jest nieprawidłowy.
  • userCancelled – OK

Zobacz pełną listę błędów i wyjątków.