Verifikasi Pengguna Sekunder

Verifikasi tambahan oleh pengguna memungkinkan Anda menambahkan keamanan faktor kedua ke perintah suara. Hal ini memungkinkan Anda menambahkan keamanan tambahan untuk tindakan tertentu seperti mematikan kamera keamanan atau membuka pintu. Verifikasi tambahan oleh pengguna tidak terikat dengan karakteristik perangkat tertentu sehingga Anda dapat memutuskan kapan harus meminta Google Assistant untuk mengeluarkan tantangan. Misalnya, Anda dapat memilih untuk mengeluarkan tantangan untuk karakteristik OnOff untuk kamera keamanan, tetapi tidak mengeluarkan tantangan untuk karakteristik OnOff untuk lampu. Anda juga dapat meminta Assistant mengeluarkan tantangan dalam situasi tertentu untuk tindakan yang sama. Misalnya, Anda dapat meminta Assistant untuk mengeluarkan permintaan tantangan untuk membuka pintu jika NFC keyfob tidak berada di dekat pintu tersebut, tetapi tidak mengeluarkan tantangan jika keyfob ada.

Assistant dapat mengeluarkan dua jenis tantangan - konfirmasi eksplisit atau nomor identifikasi pribadi (PIN). Hal ini menambahkan blok tantangan ke QUERY dan EXECUTE intent yang dikirim dari Assistant kembali ke tindakan Anda dan menerima respons error challengeNeeded. Assistant kemudian mengirim kembali permintaan intent ke tindakan Anda dengan data tantangan di blok tantangan. Kemudian, Anda dapat memvalidasi data tantangan untuk menentukan apakah pengguna memberikan respons keamanan yang benar.

Assistant menggunakan dialog untuk mengeluarkan tantangan, tetapi jika Anda menggunakan Assistant di platform non-suara, PIN dan konfirmasi dilakukan di layar.

Kapan harus menggunakan verifikasi tambahan oleh pengguna

Anda dapat mengaktifkan verifikasi tambahan oleh pengguna untuk jenis atau karakteristik perangkat apa pun. Namun, Anda harus menerapkan verifikasi tambahan oleh pengguna untuk jenis dan karakteristik perangkat tertentu yang sensitif terhadap keamanan agar integrasi Anda disertifikasi.

Verifikasi tambahan oleh pengguna menggunakan jenis tantangan pinNeeded diperlukan untuk kombinasi jenis karakteristik dan perangkat berikut:

  • Karakteristik OnOff jika jenis perangkatnya adalah CAMERA.
  • Karakteristik OpenClose jika jenis perangkatnya adalah DOOR, GARAGE, GATE, atau WINDOW.
  • Karakteristik LockUnlock saat membuka kunci.
  • Karakteristik ArmDisarm saat menonaktifkan atau membatalkan penonaktifan.
  • Karakteristik Reboot, SoftwareUpdate, atau NetworkControl jika jenis perangkatnya adalah NETWORK atau ROUTER.

Jenis tantangan ackNeeded diperlukan untuk karakteristik TemperatureSetting jika jenis perangkatnya adalah AC_UNIT dan integrasinya berlokasi di Jepang.

Jenis tantangan yang didukung

Berikut adalah jenis tantangan verifikasi tambahan oleh pengguna yang didukung:

  • Tidak ada tantangan - Permintaan dan respons yang tidak menggunakan tantangan verifikasi tambahan oleh pengguna.
  • ackNeeded - Verifikasi tambahan oleh pengguna yang memerlukan konfirmasi eksplisit (ya atau tidak) dan juga dapat menggunakan status karakteristik sebagai masukan respons. Jenis tantangan ini tidak direkomendasikan untuk perangkat dan karakteristik keamanan.
  • pinNeeded - Verifikasi tambahan oleh pengguna yang memerlukan nomor identifikasi pribadi (PIN), yang ideal untuk perangkat keamanan dan karakteristik.

Tidak ada tantangan

Contoh ini menunjukkan permintaan dan respons EXECUTE yang berhasil tanpa tantangan untuk menyalakan lampu.

Pengguna Nyalakan lampu.
Google Assistant Oke, menyalakan 3 lampu.
Permintaan
{
  "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
          }
        }]
      }]
    }
  }]
}
Respons
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

Autentikasi konfirmasi tambahan oleh pengguna yang dapat menggunakan beberapa status untuk karakteristik atau autentikasi konfirmasi sederhana.

Ada jenis tantangan ackNeeded berikut:

ackNeeded sederhana

Contoh ini menunjukkan permintaan dan respons sederhana dengan tantangan ackNeeded untuk meredupkan lampu dan konfirmasi untuk meredupkan lampu.

Pengguna Redupkan lampu ruang keluarga.
Google Assistant Meredupkan lampu ruang keluarga. Yakin?
Pengguna Ya.
Google Assistant Meredupkan lampu ruang keluarga.
Permintaan 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
          }
        }]
      }]
    }
  }]
}
Respons 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Permintaan 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
          }
        }]
      }]
    }
  }]
}
Respons 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackNeeded dengan status karakteristik

Autentikasi konfirmasi tambahan oleh pengguna yang dapat menggunakan status untuk karakteristik. Misalnya, jika Anda menggunakan karakteristik TemperatureSetting dan thermostatMode serta thermostatTemperatureSetpoint ditetapkan, Assistant dapat bertanya Apakah Anda yakin ingin menyetel pemanas di AC ke 28 derajat?

Anda juga dapat menyertakan status dalam respons agar Assistant melakukan tindakan tertentu berdasarkan permintaan yang diberikan.

Karakteristik dan status berikut mendukung ackNeeded dengan status karakteristik. Daftar karakteristik tertentu menunjukkan bahwa semua statusnya didukung.

  • ArmDisarm
    • Gunakan jenis tantangan ackNeeded untuk mengaktifkan atau membatalkan pengaktifan perangkat, tetapi untuk fungsi menonaktifkan dan membatalkan penonaktifan, jenis tantangan pinNeeded diperlukan.
  • Fill
  • LockUnlock
    • Gunakan jenis tantangan ackNeeded untuk mengunci perangkat dan jenis tantangan pinNeeded untuk membuka kunci.
  • OnOff
    • on
    • Gunakan jenis tantangan ackNeeded untuk karakteristik ini. Jenis tantangan pinNeeded diperlukan saat karakteristik ini digunakan dengan perangkat CAMERA.
  • OpenClose
    • Gunakan jenis tantangan ackNeeded untuk karakteristik ini. Jenis tantangan pinNeeded diperlukan saat karakteristik ini digunakan dengan perangkat DOOR, GARAGE, GATE atau WINDOW.
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

Contoh ini menunjukkan permintaan dan respons dengan tantangan ackNeeded yang menggunakan status karakteristik. Contoh ini mengubah mode AC menjadi pemanas dan menetapkan suhu ke 28 derajat. Kemudian, Assistant meminta konfirmasi pengguna untuk menyalakan pemanas dan menetapkan suhu ke 28 derajat karena thermostatTemperatureSetpoint sebesar 28 ditampilkan sebagai status dalam respons.

Pengguna Setel mode AC ke pemanas.
Google Assistant Apakah Anda yakin ingin menyetel pemanas di AC ke 28 derajat?
Pengguna Ya.
Google Assistant Menyetel pemanas di AC ke 28 derajat.
Permintaan 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"
          }
        }]
      }]
    }
  }]
}
Respons 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
Permintaan 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
          }
        }]
      }]
    }
  }]
}
Respons 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

pinNeeded

Tantangan pinNeeded direkomendasikan untuk perangkat keamanan.

Contoh ini menunjukkan permintaan dan respons awal dengan tantangan pinNeeded. Contoh ini menampilkan respons dengan tantangan pinNeeded, sehingga Assistant meminta PIN. Pada tahap ini, pengguna dapat memberikan PIN yang salah atau valid.

Contoh permintaan dan respons untuk PIN yang salah atau valid:

Pengguna Buka kunci pintu.
Google Assistant Bolehkah saya meminta kode keamanan Anda?
Permintaan
{
  "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
          }
        }]
      }]
    }
  }]
}
Respons
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

PIN salah

Contoh ini menunjukkan permintaan dan respons dengan tantangan challengeFailedPinNeeded. Tantangan ini harus digunakan setelah tantangan pinNeeded awal gagal.

Saat jenis challengeFailedPinNeeded ditampilkan, Assistant akan meminta kode keamanan lagi. Jika pengguna melakukan terlalu banyak upaya yang gagal, Anda dapat menampilkan respons error tooManyFailedAttempts. Lihat Respons error.

Pengguna 333222
Google Assistant Maaf, kode keamanan salah. Bolehkah saya meminta kode keamanan Anda?
Permintaan
{
  "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"
          }
        }]
      }]
    }
  }]
}
Respons
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

PIN valid

Contoh ini menunjukkan permintaan dan respons PIN yang valid.

Pengguna 333444
Google Assistant Membuka kunci pintu.
Permintaan
{
  "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"
          }
        }]
      }]
    }
  }]
}
Respons
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}
Pengguna Redupkan lampu ruang keluarga.
Google Assistant Bolehkah saya meminta kode keamanan Anda?
Permintaan
{
  "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
          }
        }]
      }]
    }
  }]
}
Respons
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Respons error

Berikut beberapa kode error yang dapat ditampilkan dengan respons Anda:

  • tooManyFailedAttempts - Maaf, terlalu banyak upaya yang gagal. Buka aplikasi perangkat Anda untuk menyelesaikan tindakan tersebut.
  • pinIncorrect - Maaf, kode keamanan salah.
  • userCancelled - Oke

Lihat daftar lengkap error dan pengecualian.