FAQ Smart Home

Umum

T: Di mana dan dalam bahasa apa sebaiknya kami menerapkan infrastruktur pemenuhan Cloud-to-cloud?

J: Selama mendukung SSL (TLS) modern dan OAuth 2.0, Anda dapat menerapkan infrastruktur di platform dan dalam bahasa apa pun yang Anda pilih. Sebaiknya lakukan deployment sedekat mungkin dengan infrastruktur lainnya, untuk meningkatkan keandalan dan mengurangi latensi eksekusi ke perangkat pengguna sebenarnya.

T: Apakah ID perangkat harus unik?

J: ID harus unik. Jika Anda tidak memiliki ID unik di seluruh layanan, ID tersebut harus unik setidaknya di tingkat per pengguna. Bayangkan pengguna dengan beberapa rumah, yang keduanya memiliki integrasi ke pengguna yang sama. Meminta untuk menyalakan lampu di satu rumah tidak boleh menyalakan lampu dengan ID yang sama di rumah lain.

T: Apakah nama perangkat harus unik?

J: Nama tidak harus unik, meskipun seiring waktu kami dapat mendorong orang untuk meningkatkan penamaan yang buruk setelah penyiapan untuk pengalaman pengguna yang lebih baik.

Berikut panduan penamaan singkat:

  • Nama harus berupa hal yang dapat diucapkan orang.
  • Kami mengenali subset string, jadi jika Anda memiliki 'acme color light', kami juga akan menjawab 'acme light'.
  • Sebaiknya gunakan nama deskriptif untuk produk dan satu atau beberapa nama yang ditentukan pengguna.
  • Pengguna tidak perlu memberikan nama ruangan untuk lampu, karena kami memiliki ruangan untuk itu; lampu harus memiliki nama unik per ruangan, tetapi selalu dapat menggunakan bentuk jamak untuk memerintahkan semuanya (misalnya, dua lampu di lampu dinding kantor adalah 'north light' dan 'east light', tetapi dapat diperintahkan sebagai 'lights').

T: Seberapa sering status perangkat diperbarui?

J: Status sementara diambil saat QUERY atau EXECUTE, yang merupakan tindakan yang dimulai pengguna. Jika pengguna bertanya 'apakah lampu menyala?', atau ingin menerangkan lampu, kita perlu melakukan kueri untuk mengetahui status saat ini.

T: Apakah mungkin memperbarui Home Graph secara langsung dengan status perangkat saat ini?

J: Ya, gunakan panggilan API Report State.

Penautan Akun dan OAuth

J: Ya, penautan akun diperlukan untuk menghubungkan perangkat pengguna ke layanan cloud penyedia.

T: Untuk OAuth, kami menetapkan masa berlaku token akses setiap 15.213 jam, apakah tidak masalah?

J: Ya, tetapi sebaiknya uji dengan waktu habis masa berlaku yang cukup singkat, misalnya 10-20 menit. Klien OAuth kami harus memperbarui token sesuai kebutuhan, dan pengujian dengan waktu habis masa berlaku yang singkat akan membuktikan bahwa hal tersebut berfungsi.

Intent

T: Kapan SYNC terjadi?

J: SYNC terjadi segera setelah penyelesaian OAuth, dan setelah panggilan Request Sync dilakukan.

T: Mengapa SYNC tidak berfungsi?

J: Ada beberapa alasan umum mengapa hal ini dapat gagal.

  • Anda mengirim jenis perangkat yang salah.

    • Misalnya, kami mengharapkan action.devices.types.LIGHT, tetapi Anda mengirim action.devices.types.Light.

  • Anda mengirim jenis perangkat yang tidak didukung.

    • Misalnya, Anda mengirim action.devices.types.FLASHLIGHT - hal ini tidak kami dukung.

  • Anda mengirim kolom yang tidak valid/tidak didukung.

    • Misalnya, Anda memiliki kolom yang tidak ada dalam spesifikasi kami.

  • Ada masalah pemformatan lain dengan respons SYNC Anda.

    • Periksa tanda kurung Anda.

  • Anda mengalami masalah penautan akun.

    • Pastikan Anda menerima token akses yang valid di header Otorisasi permintaan SYNC.

  • Anda memerlukan waktu terlalu lama untuk merespons permintaan SYNC.

    • Pastikan Anda merespons permintaan SYNC dalam waktu 5 detik.

T: Apakah respons “tertunda” tidak masalah?

J: Kami lebih memilih respons berhasil/gagal, bukan tertunda, jika perangkat Anda tersedia secara real time. Hubungi kami jika Anda merasa memerlukan respons 'tertunda' -- kami menyadari bahwa beberapa perangkat berdaya rendah dan non-real-time mungkin memerlukan respons tertunda dan model eksekusi asinkron.

Pengujian dan Pengiriman

T: Dapatkah kami menyiapkan lingkungan cloud pengembangan?

J: Ya, Anda dapat menguji lingkungan dan konfigurasi cloud yang belum diluncurkan.

T: Action saya tidak terlihat di bagian Kontrol Rumah aplikasi Google Home. Apa yang terjadi?

J: Pastikan Anda adalah Developer untuk project ini.

Laporkan Status

T: Apakah ada prasyarat untuk menerapkan Laporkan Status?

J: Project harus menggunakan Smart Home API, mendukung OAuth2, dan harus memiliki trait yang memiliki status untuk dilaporkan.

T: Seberapa sering kita perlu Melaporkan Status di perangkat?

J: Google tertarik dengan transisi dan status terminal. Namun, jika ada banyak perubahan status dalam waktu singkat (misalnya, pengguna membuka dan menutup kulkas tiga kali dalam satu menit atau menggeser dimmer), kita hanya memerlukan status akhir yang dilaporkan.

T: Apakah status perangkat lengkap perlu dikirim saat melakukan panggilan Laporkan Status?

J: Pembaruan status sebagian tidak didukung, sehingga Report State panggilan harus selalu menyertakan semua data untuk trait tertentu yang telah diperbarui. Jika dua trait akan membuat ketidakkonsistenan, keduanya harus dilaporkan bersama.

T: Dapatkah Google membuat kueri perangkat saya untuk mendapatkan status (yaitu, melakukan polling perangkat)?

J: Ini adalah mekanisme penggantian yang tidak kami rekomendasikan. Jika kita perlu melakukan polling perangkat secara sering untuk pengguna tersebut, kita tidak dapat menjamin beban tambahan yang akan terjadi. Kebutuhan ini berasal dari platform visual baru. Selain masalah beban yang tidak diketahui, hal ini akan menurunkan kualitas pengalaman pengguna. Kami merasa bahwa Report State sangat penting untuk platform.

T: Trait apa yang mendukung Laporkan Status saat ini?

J: Semua trait publik yang memiliki status terkait didukung. Setiap perubahan dalam status Online perangkat juga harus dilaporkan.

Perhatikan bahwa Scene tidak memiliki status. Namun, Scene dapat menyebabkan perubahan status perangkat. Jika ada perangkat di Google Home Graph yang memiliki status perubahan, hal ini harus dilaporkan kembali.

T: Apakah Laporkan Status mengharuskan stempel waktu dikirim?

J: Kami tidak memerlukan stempel waktu; status terakhir yang dikirim akan mengganti panggilan sebelumnya.

T: Apakah saya perlu Melaporkan Status secara terpisah jika saya sudah mengirim status di Kueri dan/atau Eksekusi?

J: Home Graph hanya menyimpan status yang dikirim melalui Report State. Status yang ditampilkan sebagai respons terhadap intent EXECUTE dan QUERY hanya digunakan untuk respons ucapan kepada pengguna dan tidak disimpan. Oleh karena itu, Report State harus dipanggil meskipun status baru perangkat telah ditampilkan sebagai respons terhadap intent EXECUTE atau QUERY.

T: Apa konsekuensinya jika tidak sepenuhnya menerapkan Laporkan Status dalam batas waktu yang ditentukan?

J: Hal ini akan menyebabkan penurunan kualitas pengalaman pengguna, misalnya di Google Home app (GHA) dan platform visual. Artinya, banyak intent QUERY akan dikirim untuk melakukan polling status dan kami tidak dapat menjamin bahwa hal ini akan sesuai dengan beban tambahan di cloud partner.

T: Bagaimana cara menguji implementasi Laporkan Status kami?

J: Gunakan Home Graph Viewer - alat pengujian mandiri yang menampilkan status perangkat Anda saat ini yang disimpan di Home Graph.

T: Dapatkah kita menggunakan requestId acak untuk Laporkan Status?

J: Sebaiknya partner menggunakan requestId yang sama yang mereka terima dari permintaan EXECUTE jika Report State dipicu oleh permintaan EXECUTE. Jika tidak, Anda dapat menggunakan requestId acak.

T: Jika pengguna memiliki beberapa perangkat dan salah satunya mengalami perubahan status, apakah kita harus melaporkan status terbaru semua perangkat?

J: Tidak. Anda hanya perlu melaporkan status perangkat tertentu tersebut.

Praktik Terbaik

T: Latensi seperti apa yang dapat diterima?

J: Idealnya kurang dari 1.000 md, antara 2-5 detik tidak masalah. Jika latensi Anda berada di sekitar 5 detik, hubungi kami.

T: Bagaimana cara membuat speaker yang diaktifkan dengan suara merespons dengan benar saat offline?

J: Tampilkan status offline untuk perangkat offline. Kami menampilkan 'tidak tersedia saat ini' sebagai TTS untuk error ini. Untuk mengetahui informasi selengkapnya, lihat Error dan pengecualian.