Selamat datang di Pusat Developer Google Home, tempat baru untuk mempelajari cara mengembangkan tindakan smart home. Catatan: Anda akan terus membuat tindakan di konsol Actions.

Halaman ini diterjemahkan oleh Cloud Translation API.

Notifikasi untuk Action smart home

Notifikasi memungkinkan integrasi Cloud-to-cloud Anda menggunakan Google Assistant untuk berkomunikasi dengan pengguna tentang peristiwa atau perubahan penting terkait perangkat. Anda dapat menerapkan notifikasi untuk memberi tahu pengguna tentang peristiwa perangkat yang tepat waktu, misalnya saat seseorang berada di depan pintu, atau untuk melaporkan perubahan status perangkat yang diminta, seperti saat gerendel kunci pintu berhasil diaktifkan atau macet.

Integrasi Cloud-to-cloud Anda dapat mengirim jenis notifikasi berikut kepada pengguna:

Notifikasi proaktif: Memberi tahu pengguna tentang peristiwa perangkat smart home tanpa permintaan pengguna sebelumnya ke perangkat mereka, seperti bel pintu berdering.
Respons tindak lanjut: Konfirmasi bahwa permintaan perintah perangkat berhasil atau gagal, misalnya saat mengunci pintu. Gunakan pemberitahuan ini untuk perintah perangkat yang memerlukan waktu untuk diselesaikan. Respons lanjutan hanya didukung saat permintaan perintah perangkat dikirim dari speaker smart dan layar smart.

Assistant memberikan notifikasi ini kepada pengguna sebagai pengumuman di speaker smart dan layar smart. Notifikasi proaktif dinonaktifkan secara default. Pengguna dapat mengaktifkan atau menonaktifkan semua notifikasi proaktif dari Google Home app (GHA).

Peristiwa yang memicu notifikasi

Saat peristiwa perangkat terjadi, fulfillment Anda akan mengirimkan permintaan notifikasi ke Google. Ciri perangkat yang didukung integrasi Cloud-to-cloud Anda menentukan jenis peristiwa notifikasi yang tersedia dan data yang dapat Anda sertakan dalam notifikasi tersebut.

Ciri berikut mendukung notifikasi proaktif:

Sifat	Acara
ObjectDetection	Objek yang terdeteksi oleh perangkat, seperti saat wajah yang dikenali terdeteksi di pintu. Misalnya: "Alice dan Bob ada di pintu depan".
RunCycle	Perangkat menyelesaikan siklus. Misalnya: "Siklus mesin cuci telah selesai."
SensorState	Perangkat mendeteksi status sensor yang didukung. Misalnya: "Pendeteksi asap mendeteksi asap."

Ciri berikut mendukung respons tindak lanjut:

Sifat	Acara
LockUnlock	Status penyelesaian dan perubahan status setelah eksekusi perintah perangkat `action.devices.commands.LockUnlock`. Misalnya: "Pintu depan sudah dikunci" atau "Pintu depan macet."
NetworkControl	Status penyelesaian dan perubahan status setelah eksekusi perintah perangkat `action.devices.commands.TestNetworkSpeed`. Misalnya: "Uji kecepatan jaringan Anda telah selesai. Kecepatan download di router kantor saat ini adalah 80,2 Kbps, dan kecepatan uploadnya adalah 9,3 Kbps."
OpenClose	Status penyelesaian dan perubahan status setelah eksekusi perintah perangkat `action.devices.commands.OpenClose`. Misalnya: "Pintu depan telah terbuka" atau "Pintu depan tidak dapat dibuka".

Semua jenis perangkat mendukung notifikasi untuk karakteristik yang berlaku.

Membuat notifikasi untuk integrasi Cloud-to-cloud

Tambahkan notifikasi ke integrasi Cloud-to-cloud Anda pada tahap berikut:

Tunjukkan kepada Google apakah notifikasi diaktifkan dari aplikasi perangkat smart home Anda. Jika pengguna mengaktifkan atau menonaktifkan notifikasi di aplikasi Anda, kirim permintaan SYNC untuk memberi tahu Google tentang perubahan perangkat.
Saat peristiwa atau perubahan status perangkat yang relevan terjadi yang memicu notifikasi, kirim permintaan notifikasi dengan memanggil Report State reportStateAndNotification API. Jika status perangkat berubah, Anda dapat mengirim payload status dan notifikasi bersama-sama dalam panggilan Report State dan Notifikasi.

Bagian berikut akan membahas langkah-langkah ini secara lebih mendetail.

Menunjukkan apakah notifikasi diaktifkan di aplikasi Anda

Pengguna dapat memilih apakah mereka ingin menerima notifikasi proaktif dengan mengaktifkan fitur ini di GHA. Di aplikasi untuk perangkat smart home, Anda juga dapat secara opsional menambahkan kemampuan bagi pengguna untuk mengalihkan notifikasi secara eksplisit dari perangkat, misalnya, dari setelan aplikasi Anda.

Tunjukkan kepada Google bahwa notifikasi diaktifkan untuk perangkat Anda dengan melakukan panggilan Request SYNC untuk memperbarui data perangkat. Anda harus mengirim permintaan SYNC seperti ini setiap kali pengguna mengubah setelan ini di aplikasi Anda.

Dalam respons SYNC, kirim salah satu pembaruan berikut:

Jika pengguna secara eksplisit mengaktifkan notifikasi di aplikasi perangkat, atau jika Anda tidak memberikan opsi tombol, tetapkan properti devices.notificationSupportedByAgent ke true.
Jika pengguna secara eksplisit menonaktifkan notifikasi di aplikasi perangkat Anda, tetapkan properti devices.notificationSupportedByAgent ke false.

Cuplikan berikut menunjukkan contoh cara menetapkan respons SYNC:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

Mengirim permintaan notifikasi ke Google

Untuk memicu notifikasi di Assistant, fulfillment Anda mengirim payload notifikasi ke Google Home Graph melalui panggilan Report State dan Notification API.

Mengaktifkan Google HomeGraph API

Di Google Cloud Console, buka halaman HomeGraph API.
Buka halaman HomeGraph API
Pilih project yang cocok dengan project ID smart home Anda.
Klik ENABLE.

Membuat Kunci Akun Layanan

Ikuti petunjuk berikut untuk membuat kunci akun layanan dari Google Cloud Console:

Catatan: Pastikan Anda menggunakan project GCP yang benar saat melakukan langkah-langkah ini. Ini adalah project yang cocok dengan project ID smart home Anda.

Di Google Cloud Console, buka halaman Create service account key.
Buka halaman Create Service Account Key
Dari daftar Service account, pilih New service account.
Di kolom Nama akun layanan, masukkan nama.
Di kolom Service account ID, masukkan ID.
Dari daftar Peran, pilih Akun Layanan > Pembuat Token Akun Layanan.
Untuk Jenis kunci, pilih opsi JSON.
Klik Buat. File JSON yang berisi kunci Anda akan didownload ke komputer Anda.

Mengirim notifikasi

Lakukan panggilan permintaan notifikasi menggunakan devices.reportStateAndNotification API. Permintaan JSON Anda harus menyertakan eventId, yang merupakan ID unik yang dihasilkan oleh platform Anda untuk peristiwa yang memicu notifikasi. eventId harus merupakan ID acak yang berbeda setiap kali Anda mengirim permintaan notifikasi.

Dalam objek notifications yang Anda teruskan dalam panggilan API, sertakan nilai priority yang menentukan cara notifikasi ditampilkan. Objek notifications Anda dapat menyertakan kolom yang berbeda bergantung pada karakteristik perangkat.

Ikuti salah satu jalur berikut untuk menetapkan payload dan memanggil API:

Mengirim payload notifikasi proaktif
Mengirim payload respons tindak lanjut

Mengirim payload notifikasi proaktif

Untuk memanggil API, pilih opsi dari salah satu tab berikut:

HTTP

Home Graph API menyediakan endpoint HTTP

Gunakan file JSON akun layanan yang didownload untuk membuat Token Web JSON (JWT). Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi Menggunakan Akun Layanan.
Dapatkan token akses OAuth 2.0 dengan cakupan https://www.googleapis.com/auth/homegraph menggunakan oauth2l:

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

Buat permintaan JSON dengan agentUserId. Berikut adalah contoh permintaan JSON untuk Report State dan Notifikasi:

{
  "agentUserId": "PLACEHOLDER-USER-ID",
  "eventId": "PLACEHOLDER-EVENT-ID",
  "requestId": "PLACEHOLDER-REQUEST-ID",
  "payload": {
    "devices": {
      "notifications": {
        "PLACEHOLDER-DEVICE-ID": {
          "ObjectDetection": {
            "priority": 0,
            "detectionTimestamp": 1534875126750,
            "objects": {
              "named": [
                "Alice"
              ],
              "unclassified": 2
            }
          }
        }
      }
    }
  }
}

Gabungkan Report State dan JSON Notifikasi serta token dalam permintaan POST HTTP Anda ke endpoint Google Home Graph. Berikut adalah contoh cara membuat permintaan di command line menggunakan curl, sebagai pengujian:

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

gRPC

Home Graph API menyediakan endpoint gRPC

Dapatkan definisi layanan buffering protokol untuk Home Graph API.
Ikuti dokumentasi developer gRPC untuk membuat stub klien untuk salah satu bahasa yang didukung .
Panggil metode ReportStateAndNotification .

Node.js

Klien Node.js Google API menyediakan binding untuk Home Graph API.

Lakukan inisialisasi layanan google.homegraph menggunakan Kredensial Default Aplikasi.
Panggil metode reportStateAndNotification dengan ReportStateAndNotificationRequest. Fungsi ini menampilkan Promise dengan ReportStateAndNotificationResponse.

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            ObjectDetection: {
              priority: 0,
              detectionTimestamp: 1534875126750,
              objects: {
                named: ['Alice'],
                unclassified: 2
              }
            }
          }
        }
      }
    }
  }
});

Java

Library Klien HomeGraph API untuk Java menyediakan binding untuk Home Graph API.

Lakukan inisialisasi HomeGraphApiService menggunakan Kredensial Default Aplikasi.
Panggil metode reportStateAndNotification dengan ReportStateAndNotificationRequest. Metode ini menampilkan ReportStateAndNotificationResponse.

// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Build device notification payload.
Map<?, ?> notifications =
    Map.of(
        "ObjectDetection",
        Map.of(
            "priority", 0,
            "detectionTimestamp", 1534875126,
            "objects", Map.of("named", List.of("Alice"), "unclassifed", 2)));

// Send notification.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications))));
homegraphService.devices().reportStateAndNotification(request);

Mengirim payload respons tindak lanjut

Payload untuk respons tindak lanjut berisi status permintaan, kode error untuk kegagalan peristiwa, jika berlaku, dan followUpToken yang valid, yang diberikan selama permintaan intent EXECUTE. followUpToken harus digunakan dalam waktu lima menit agar tetap valid dan mengaitkan respons dengan permintaan asli dengan benar.

Cuplikan berikut menunjukkan contoh payload permintaan EXECUTE dengan kolom followUpToken.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
        }],
        "execution": [{
          "command": "action.devices.commands.TestNetworkSpeed",
          "params": {
            "testDownloadSpeed": true,
            "testUploadSpeed": false,
            "followUpToken": "PLACEHOLDER"
          }
        }]
      }]
    }
  }]
};

Google menggunakan followUpToken untuk menampilkan notifikasi hanya di perangkat yang awalnya berinteraksi dengan pengguna, dan tidak disiarkan ke semua perangkat pengguna.

Untuk memanggil API, pilih opsi dari salah satu tab berikut:

HTTP

Home Graph API menyediakan endpoint HTTP

Gunakan file JSON akun layanan yang didownload untuk membuat Token Web JSON (JWT). Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi Menggunakan Akun Layanan.
Dapatkan token akses OAuth 2.0 dengan cakupan https://www.googleapis.com/auth/homegraph menggunakan oauth2l:

oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph

Buat permintaan JSON dengan agentUserId. Berikut adalah contoh permintaan JSON untuk Report State dan Notifikasi:

{
  "agentUserId": "PLACEHOLDER-USER-ID",
  "eventId": "PLACEHOLDER-EVENT-ID",
  "requestId": "PLACEHOLDER-REQUEST-ID",
  "payload": {
    "devices": {
      "notifications": {
        "PLACEHOLDER-DEVICE-ID": {
          "NetworkControl": {
            "priority": 0,
            "followUpResponse": {
              "status": "SUCCESS",
              "followUpToken": "PLACEHOLDER",
              "networkDownloadSpeedMbps": 23.3,
              "networkUploadSpeedMbps": 10.2
            }
          }
        }
      }
    }
  }
}

Gabungkan Report State dan JSON Notifikasi serta token dalam permintaan POST HTTP Anda ke endpoint Google Home Graph. Berikut adalah contoh cara membuat permintaan di command line menggunakan curl, sebagai pengujian:

curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request-body.json \
  "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"

gRPC

Home Graph API menyediakan endpoint gRPC

Dapatkan definisi layanan buffering protokol untuk Home Graph API.
Ikuti dokumentasi developer gRPC untuk membuat stub klien untuk salah satu bahasa yang didukung.
Panggil metode ReportStateAndNotification.

Node.js

Klien Node.js Google API menyediakan binding untuk Home Graph API.

Lakukan inisialisasi layanan google.homegraph menggunakan Kredensial Default Aplikasi.
Panggil metode reportStateAndNotification dengan ReportStateAndNotificationRequest. Tindakan ini akan menampilkan Promise dengan ReportStateAndNotificationResponse.

const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken;

const homegraphClient = homegraph({
  version: 'v1',
  auth: new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/homegraph'
  })
});

const res = await homegraphClient.devices.reportStateAndNotification({
  requestBody: {
    agentUserId: 'PLACEHOLDER-USER-ID',
    eventId: 'PLACEHOLDER-EVENT-ID',
    requestId: 'PLACEHOLDER-REQUEST-ID',
    payload: {
      devices: {
        notifications: {
          'PLACEHOLDER-DEVICE-ID': {
            NetworkControl: {
              priority: 0,
              followUpResponse: {
                status: 'SUCCESS',
                followUpToken,
                networkDownloadSpeedMbps: 23.3,
                networkUploadSpeedMbps: 10.2,
              }
            }
          }
        }
      }
    }
  }
});

Java

Library Klien HomeGraph API untuk Java menyediakan binding untuk Home Graph API.

Lakukan inisialisasi HomeGraphApiService menggunakan Kredensial Default Aplikasi
Panggil metode reportStateAndNotification dengan ReportStateAndNotificationRequest. Metode ini menampilkan ReportStateAndNotificationResponse

// Get Application Default credentials.
GoogleCredentials credentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(List.of("https://www.googleapis.com/auth/homegraph"));

// Create Home Graph service client.
HomeGraphService homegraphService =
    new HomeGraphService.Builder(
            GoogleNetHttpTransport.newTrustedTransport(),
            GsonFactory.getDefaultInstance(),
            new HttpCredentialsAdapter(credentials))
        .setApplicationName("HomeGraphExample/1.0")
        .build();

// Extract follow-up token.
ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0];
String followUpToken =
    (String)
        executeInputs
            .getPayload()
            .getCommands()[0]
            .getExecution()[0]
            .getParams()
            .get("followUpToken");

// Build device follow-up response payload.
Map<?, ?> followUpResponse =
    Map.of(
        "NetworkControl",
        Map.of(
            "priority",
            0,
            "followUpResponse",
            Map.of(
                "status",
                "SUCCESS",
                "followUpToken",
                followUpToken,
                "networkDownloadSpeedMbps",
                23.3,
                "networkUploadSpeedMbps",
                10.2)));

// Send follow-up response.
ReportStateAndNotificationRequest request =
    new ReportStateAndNotificationRequest()
        .setRequestId("PLACEHOLDER-REQUEST-ID")
        .setAgentUserId("PLACEHOLDER-USER-ID")
        .setEventId("PLACEHOLDER-EVENT-ID")
        .setPayload(
            new StateAndNotificationPayload()
                .setDevices(
                    new ReportStateAndNotificationDevice()
                        .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse))));
homegraphService.devices().reportStateAndNotification(request);

Logging

Notifikasi mendukung logging peristiwa seperti yang diuraikan dalam Cloud Logging untuk Cloud-to-cloud. Log ini berguna untuk menguji dan mempertahankan kualitas notifikasi dalam Action Anda.

Berikut adalah skema entri notificationLog:

Properti	Deskripsi
`requestId`	ID permintaan notifikasi.
`structName`	Nama struct notifikasi, seperti "ObjectDetection".
`status`	Menunjukkan status notifikasi.

Kolom status mencakup berbagai status yang dapat menunjukkan error dalam payload notifikasi. Beberapa di antaranya mungkin hanya tersedia di Action yang belum diluncurkan ke produksi.

Contoh status mencakup:

Status	Deskripsi
`EVENT_ID_MISSING`	Menunjukkan bahwa kolom `eventId` yang diperlukan tidak ada.
`PRIORITY_MISSING`	Menunjukkan bahwa kolom `priority` tidak ada.
`NOTIFICATION_SUPPORTED_BY_AGENT_FALSE`	Menunjukkan bahwa properti `notificationSupportedByAgent` perangkat pemberitahuan yang diberikan di `SYNC` bernilai salah.
`NOTIFICATION_ENABLED_BY_USER_FALSE`	Menunjukkan bahwa pengguna belum mengaktifkan notifikasi di perangkat pemberitahuan di GHA. Status ini hanya tersedia di integrasi yang belum diluncurkan ke produksi.
`NOTIFYING_DEVICE_NOT_IN_STRUCTURE`	Menunjukkan bahwa pengguna belum menetapkan perangkat pemberitahuan ke Rumah/Struktur. Status ini hanya tersedia di integrasi yang belum diluncurkan ke produksi.

Selain status umum ini yang dapat berlaku untuk semua notifikasi, kolom status juga dapat menyertakan status khusus fitur jika berlaku (misalnya, OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).

Sebelumnya

Menerapkan Status Laporan

Berikutnya

Menguji integrasi Cloud-to-cloud