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:

Ciri berikut mendukung respons tindak lanjut:

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:

1. 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.
2. 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

1. Di Google Cloud Console, buka halaman HomeGraph API.

   Buka halaman HomeGraph API
2. Pilih project yang cocok dengan project ID smart home Anda.
3. Klik ENABLE.

Membuat Kunci Akun Layanan

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

1. Di Google Cloud Console, buka halaman Create service account key.

   Buka halaman Create Service Account Key
2. Dari daftar Service account, pilih New service account.
3. Di kolom Nama akun layanan, masukkan nama.
4. Di kolom Service account ID, masukkan ID.

5. Dari daftar Peran, pilih Akun Layanan > Pembuat Token Akun Layanan.

6. Untuk Jenis kunci, pilih opsi JSON.

7. 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:

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
              }
            }
          }
        }
      }
    }
  }
});
    

// 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:

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,
              }
            }
          }
        }
      }
    }
  }
});
    

// 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:

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:

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).