Weryfikacja dodatkowego użytkownika

Dodatkowa weryfikacja użytkownika umożliwia dodanie do poleceń głosowych zabezpieczenia w postaci drugiego czynnika. Dzięki temu możesz zwiększyć bezpieczeństwo w przypadku niektórych działań, takich jak wyłączanie kamery monitoringu czy otwieranie drzwi. Dodatkowa weryfikacja użytkownika nie jest powiązana z żadną konkretną cechą urządzenia, co pozwala Ci decydować, kiedy Google Assistant ma wysyłać test. Możesz na przykład wybrać wysyłanie testu w przypadku cechy OnOff dla kamery bezpieczeństwa, ale nie wysyłać testu w przypadku OnOff cechy dla światła. Możesz też skonfigurować Asystenta tak, aby w określonych sytuacjach wysyłał testy w przypadku tego samego działania.Assistant Możesz na przykład poprosić Assistant o wysłanie testu otwarcia drzwi, jeśli w pobliżu nie ma breloka NFC, ale nie wysyłać testu, jeśli brelok jest obecny.

Assistant może wysyłać 2 rodzaje testów – wyraźne potwierdzenie lub osobisty numer identyfikacyjny (PIN). Spowoduje to dodanie bloku testu do QUERY i EXECUTE intencji wysyłanych z Assistant z powrotem do Twojej akcji oraz zaakceptowanie odpowiedzi na błąd challengeNeeded. Assistant wysyła wtedy z powrotem żądanie intencji do Twojej akcji z danymi testu w bloku testu. Możesz wtedy zweryfikować dane testu, aby sprawdzić, czy użytkownik podał prawidłową odpowiedź zabezpieczającą.

Assistant używa okna dialogowego do wysyłania testu, ale jeśli używasz Assistant na powierzchniach bez głosu, kod PIN i potwierdzenia są wykonywane na ekranie.

Kiedy używać dodatkowej weryfikacji użytkownika

Możesz włączyć dodatkową weryfikację użytkownika w przypadku dowolnego typu urządzenia lub cechy. Aby uzyskać certyfikat integracji, musisz jednak zaimplementować dodatkową weryfikację użytkownika w przypadku niektórych typów urządzeń i cech, które są szczególnie wrażliwe na kwestie bezpieczeństwa.

Dodatkowa weryfikacja użytkownika z użyciem typu testu pinNeeded jest wymagana w przypadku tych kombinacji cech i typów urządzeń:

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

Typ testu ackNeeded jest wymagany w przypadku cechy TemperatureSetting, jeśli typ urządzenia to AC_UNIT, a integracja znajduje się w Japonii.

Obsługiwane typy wyzwań

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

  • Brak testu – żądanie i odpowiedź, które nie używają testu dodatkowej weryfikacji użytkownika.
  • ackNeeded – dodatkowa weryfikacja użytkownika, która wymaga wyraźnego potwierdzenia (tak lub nie) i może też używać stanów cech jako opinii w odpowiedzi. Ten typ testu 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), co jest idealne w przypadku urządzeń i cech związanych z bezpieczeństwem.

Brak testu

Ten przykład pokazuje udane żądanie EXECUTE i odpowiedź bez testu w przypadku włączania świateł.

Użytkownik Włącz światła.
Google Assistant OK, włączam 3 światła.
Żądanie
{
  "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

Uwierzytelnianie z potwierdzeniem dodatkowej weryfikacji użytkownika, które może używać wielu stanów cechy lub prostego uwierzytelniania z potwierdzeniem.

Dostępne są następujące typy wyzwań ackNeeded:

ackNeeded simple

Ten przykład pokazuje proste żądanie i odpowiedź z testem ackNeeded w celu 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.
Żądanie 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"
      }
    }]
  }
}
Żądanie 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 with trait states

Uwierzytelnianie z potwierdzeniem dodatkowej weryfikacji użytkownika, które może używać stanów cechy. Jeśli na przykład pracujesz z cechą TemperatureSetting i ustawione są zarówno thermostatMode i thermostatTemperatureSetpoint, Assistant może zapytać Czy na pewno chcesz ustawić ogrzewanie na klimatyzatorze na 28 stopni?

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

Te cechy i stany obsługują ackNeeded ze stanami cech. Lista konkretnej cechy oznacza, że obsługiwane są wszystkie jej stany.

  • ArmDisarm
    • Użyj typu testu ackNeeded, aby uzbroić lub anulować uzbrojenie urządzenia, ale w przypadku funkcji rozbrajania i anulowania rozbrajania wymagany jest typ testu pinNeeded challenge type is required.
  • Fill
  • LockUnlock
    • Użyj typu testu ackNeeded, aby zablokować urządzenie, a typu testu pinNeeded – aby je odblokować.
  • OnOff
    • on
    • W przypadku tej cechy użyj typu testu ackNeeded. Gdy ta cecha jest używana z urządzeniami CAMERA, wymagany jest typ testu pinNeeded.
  • OpenClose
    • W przypadku tej cechy użyj typu testu ackNeeded. Gdy ta cecha jest używana z urządzeniami DOOR, GARAGE, GATE lub WINDOW, wymagany jest typ testu pinNeeded.
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

Ten przykład pokazuje żądanie i odpowiedź z testem ackNeeded, który używa stanu cechy. Zmienia tryb klimatyzatora na ogrzewanie 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 jako stan zwracana jest wartość thermostatTemperatureSetpoint równa 28.

Użytkownik Ustaw tryb klimatyzatora na ogrzewanie.
Google Assistant Czy na pewno chcesz ustawić ogrzewanie na klimatyzatorze na 28 stopni?
Użytkownik Tak.
Google Assistant Ustawiam ogrzewanie na klimatyzatorze na 28 stopni.
Żądanie 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"
      }
    }]
  }
}
Żądanie 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

Wyzwanie pinNeeded jest zalecane w przypadku urządzeń związanych z bezpieczeństwem.

Ten przykład pokazuje początkowe żądanie i odpowiedź z testem pinNeeded. Przykład zwraca 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 Odblokuj drzwi.
Google Assistant Czy możesz podać kod zabezpieczający?
Żądanie
{
  "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"
      }
    }]
  }
}

Nieprawidłowy kod PIN

Ten przykład pokazuje żądanie i odpowiedź z testem challengeFailedPinNeeded. Ten test należy użyć po nieudanym początkowym teście pinNeeded.

Gdy zwracany jest typ challengeFailedPinNeeded, Assistant ponownie prosi o podanie kodu zabezpieczającego. Jeśli użytkownik wykona zbyt wiele nieudanych prób, możesz zwrócić odpowiedź na błąd tooManyFailedAttempts. Zobacz Odpowiedzi na błędy.

Użytkownik 333222
Google Assistant Kod zabezpieczający jest nieprawidłowy. Czy możesz podać kod zabezpieczający?
Żądanie
{
  "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ź z prawidłowym kodem PIN.

Użytkownik 333444
Google Assistant Otwieram zamek w drzwiach.
Żądanie
{
  "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?
Żądanie
{
  "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 – Zbyt wiele nieudanych prób. Otwórz aplikację na urządzeniu, by 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.