Akıllı ev İşlemleri için bildirimler

Bildirimler, Cloud-to-cloud entegrasyonunuzun önemli cihaz etkinlikleri veya değişiklikleri hakkında kullanıcılarla iletişim kurmak için Google Assistant kullanmasına olanak tanır. Kullanıcıları zamanında cihaz etkinlikleri (ör. kapıda biri olduğunda) konusunda uyarmak veya istenen bir cihaz durumu değişikliğini (ör. kapı kilidi sürgüsünün başarıyla takılması veya sıkışması) bildirmek için bildirimleri uygulayabilirsiniz.

Cloud-to-cloud entegrasyonunuz, kullanıcılara aşağıdaki bildirim türlerini gönderebilir:

• Proaktif bildirimler: Kullanıcıyı, cihazlarından önceden herhangi bir kullanıcı isteği olmadan bir smart home cihaz etkinliği (ör. kapı zilinin çalması) hakkında uyarır.

• Takip yanıtları: Bir cihaz komutu isteğinin başarılı veya başarısız olduğuna dair onay (ör. kapı kilitlenirken). Bu uyarıları, tamamlanması zaman alan cihaz komutları için kullanın. Takip yanıtları yalnızca cihaz komutu istekleri akıllı hoparlörlerden ve akıllı ekranlardan gönderildiğinde desteklenir.

Assistant, bu bildirimleri kullanıcılara akıllı hoparlörlerde ve akıllı ekranlarda duyuru olarak sunar. Proaktif bildirimler varsayılan olarak kapalıdır. Kullanıcılar, Google Home app (GHA)'dan gelen tüm proaktif bildirimleri etkinleştirebilir veya devre dışı bırakabilir.

Bildirimleri tetikleyen etkinlikler

Cihaz etkinlikleri gerçekleştiğinde, yerine getirme işleminiz Google'a bir bildirim isteği gönderir. Cloud-to-cloud entegrasyonunuzun desteklediği cihaz özellikleri, hangi bildirim etkinliği türlerinin kullanılabileceğini ve bu bildirimlere ekleyebileceğiniz verileri belirler.

Aşağıdaki özellikler proaktif bildirimleri destekler:

Aşağıdaki özellikler takip yanıtlarını destekler:

Tüm cihaz türleri, geçerli özellikler için bildirimleri destekler.

Buluttan buluta entegrasyonunuz için bildirimler oluşturma

Cloud-to-cloud entegrasyonunuza şu aşamalarda bildirim ekleyin:

1. Bildirimlerin smart home cihaz uygulamanızda etkinleştirilip etkinleştirilmediğini Google'a bildirin. Kullanıcılar uygulamanızda bildirimleri açar veya kapatırsa cihaz değişikliğini Google'a bildirmek için bir SYNC isteği gönderin.
2. Bildirim tetikleyen alakalı bir cihaz etkinliği veya durum değişikliği gerçekleştiğinde Report State reportStateAndNotification API'yi çağırarak bildirim isteği gönderin. Cihaz durumu değiştiyse Report State ve bildirim çağrınızda hem durum hem de bildirim yükü gönderebilirsiniz.

Aşağıdaki bölümlerde bu adımlar daha ayrıntılı olarak ele alınmaktadır.

Uygulamanızda bildirimlerin etkin olup olmadığını belirtme

Kullanıcılar, GHA bölümünde bu özelliği etkinleştirerek proaktif bildirimler almak isteyip istemediklerini seçebilir. smart home cihazınızın uygulamasında, kullanıcıların cihazdan gelen bildirimleri açıkça açıp kapatabilme özelliğini de (ör. uygulama ayarlarınızdan) ekleyebilirsiniz.

Cihaz verilerini güncellemek için Request SYNC çağrısı yaparak Google'a cihazınızda bildirimlerin etkinleştirildiğini belirtin. Kullanıcılar uygulamanızda bu ayarı her değiştirdiğinde bu şekilde bir SYNC isteği göndermeniz gerekir.

SYNC yanıtınızda aşağıdaki güncellemelerden birini gönderin:

• Kullanıcı, cihaz uygulamanızda bildirimleri açıkça etkinleştirdiyse veya açma/kapatma seçeneği sunmuyorsanız devices.notificationSupportedByAgent özelliğini true olarak ayarlayın.
• Kullanıcı, cihaz uygulamanızda bildirimleri açıkça devre dışı bıraktıysa devices.notificationSupportedByAgent özelliğini false olarak ayarlayın.

Aşağıdaki snippet'te, SYNC yanıtınızı nasıl ayarlayacağınıza dair bir örnek gösterilmektedir:

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

Google'a bildirim istekleri gönderme

Assistant cihazında bildirimleri tetiklemek için karşılama, Report State ve Notification API çağrısı aracılığıyla Google Home Graph cihazına bir bildirim yükü gönderir.

Google HomeGraph API'yi etkinleştirme

1. Google Cloud Console içinde HomeGraph API sayfasına gidin.

   HomeGraph API sayfasına gidin
2. smart home proje kimliğinizle eşleşen projeyi seçin.
3. ETKİNLEŞTİR'i tıklayın.

Hizmet hesabı anahtarı oluşturma

Google Cloud Console üzerinden hizmet hesabı anahtarı oluşturmak için aşağıdaki talimatları uygulayın:

1. Google Cloud Console'nda Hizmet hesapları sayfasına gidin.

   Hizmet Hesapları sayfasına gidin.

   Hizmet Hesapları sayfasına yönlendirilmeden önce bir proje seçmeniz gerekebilir.

2. addHizmet hesabı oluştur'u tıklayın.

3. Service account name (Hizmet hesabı adı) alanına bir ad girin.

4. Hizmet hesabı kimliği alanına bir kimlik girin.

5. Hizmet hesabı açıklaması alanına bir açıklama girin.

6. Oluştur ve devam et'i tıklayın.

7. Role (Rol) açılır menüsünden Service Accounts (Hizmet Hesapları) > Service Account OpenID Connect Identity Token Creator'ı (Hizmet Hesabı OpenID Connect Kimlik Jetonu Oluşturucu) seçin.

8. Devam'ı tıklayın.

9. Bitti'yi tıklayın.

10. Hizmet hesapları listesinden yeni oluşturduğunuz hizmet hesabını seçin ve more_vert İşlemler menüsünden Anahtarları yönet'i seçin.

11. Anahtar ekle > Yeni anahtar oluştur'u seçin.

12. Anahtar türü için JSON seçeneğini belirleyin.

13. Oluştur'u tıklayın. Anahtarınızı içeren bir JSON dosyası bilgisayarınıza indirilir.

Bildirimi gönderme

devices.reportStateAndNotification API'yi kullanarak bildirim isteği çağrısı yapın. JSON isteğinizde, bildirimi tetikleyen etkinlik için platformunuz tarafından oluşturulan benzersiz bir kimlik olan eventId bulunmalıdır. eventId, bildirim isteği gönderdiğiniz her seferde farklı olan rastgele bir kimlik olmalıdır.

API çağrınızda ilettiğiniz notifications nesnesine, bildirimin nasıl sunulması gerektiğini tanımlayan bir priority değeri ekleyin. notifications nesneniz, cihaz özelliğine bağlı olarak farklı alanlar içerebilir.

Yükü ayarlamak ve API'yi çağırmak için aşağıdaki yollardan birini izleyin:

• Proaktif bildirim yükü gönderme
• Takip yanıtı yükü gönderme

Proaktif bildirim yükü gönderme

API'yi çağırmak için aşağıdaki sekmelerden birindeki seçeneği belirleyin:

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

Takip yanıtı yükü gönderme

Takip yanıtının yükü, isteğin durumunu, etkinlik hataları için hata kodlarını (varsa) ve EXECUTE intent isteği sırasında sağlanan geçerli followUpToken değerini içerir. followUpToken, geçerli kalması ve yanıtın orijinal istekle doğru şekilde ilişkilendirilmesi için beş dakika içinde kullanılmalıdır.

Aşağıdaki snippet'te, followUpToken alanı içeren örnek bir EXECUTE istek yükü gösterilmektedir.

{
  "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, bildirimi yalnızca kullanıcının başlangıçta etkileşimde bulunduğu cihazda yayınlamak ve kullanıcının tüm cihazlarında yayınlamamak için followUpToken kullanır.

API'yi çağırmak için aşağıdaki sekmelerden birindeki seçeneği belirleyin:

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

Günlük Kaydı

Bildirimler, Cloud-to-cloud için Cloud Logging bölümünde açıklandığı gibi olay günlüğünü destekler. Bu günlükler, Action'ınızdaki bildirim kalitesini test etmek ve korumak için kullanışlıdır.

Aşağıda, notificationLog girişinin şeması verilmiştir:

status alanı, bildirim yükünde hata olduğunu gösterebilecek çeşitli durumlar içerir. Bunlardan bazıları yalnızca üretime sunulmamış İşlemler'de kullanılabilir.

Örnek durumlar şunlardır:

Tüm bildirimler için geçerli olabilecek bu genel durumlara ek olarak status alanı, geçerli olduğu durumlarda özelliğe özgü durumları da (ör. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING) içerebilir.