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

Bildirimler, Cloud-to-cloud entegrasyonunuzun Google Assistant kullanarak kullanıcılarla önemli cihazla ilgili etkinlikler veya değişiklikler hakkında iletişim kurmasına olanak tanır. Kullanıcıları zamanında cihaz etkinlikleri konusunda uyarmak için bildirimler uygulayabilirsiniz. Örneğin, kapıda biri olduğunda veya istenen cihaz durumu değişikliği hakkında rapor vermek için (ör. kapı kilidi sürgüsü başarıyla takıldığında veya sıkıştığında) bildirimler uygulayabilirsiniz.

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

• Proaktif bildirimler: Kullanıcıyı, cihazlarına önceden herhangi bir istekte bulunmadan smart home cihaz etkinliği konusunda uyarır. Örneğin, kapı zili çaldığında bildirim gönderir.

• Takip yanıtları: Bir cihaz komut isteğinin başarılı veya başarısız olduğuna dair onay (ör. kapı kilitlenirken). Tamamlanması zaman alan cihaz komutları için bu uyarıları kullanın. Ek yanıtlar yalnızca akıllı hoparlörlerden ve akıllı ekranlardan cihaz komutu istekleri 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 devre dışıdır. Kullanıcılar, Google Home app (GHA) simgesine dokunarak tüm proaktif bildirimleri etkinleştirebilir veya devre dışı bırakabilir.

Bildirimleri tetikleyen etkinlikler

Cihaz etkinlikleri gerçekleştiğinde karşılamanız Google'a bir bildirim isteği gönderir. Cloud-to-cloud entegrasyonunuzun desteklediği cihaz özellikleri, hangi tür bildirim etkinliklerinin kullanılabileceğini ve bu bildirimlere hangi verileri ekleyebileceğinizi belirler.

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

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

Tüm cihaz türleri, geçerli özelliklerle ilgili bildirimleri destekler.

Buluttan buluta entegrasyonunuz için bildirimler oluşturma

Cloud-to-cloud entegrasyonunuza aşağıdaki aşamalarda bildirim ekleyin:

1. smart home cihaz uygulamanızda bildirimlerin etkin olup olmadığını 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. Bildirimi tetikleyen alakalı bir cihaz etkinliği veya durum değişikliği gerçekleştiğinde Report State reportStateAndNotification API'sini çağırarak bir 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ı belirtin

Kullanıcılar, GHA bölümünde bu özelliği etkinleştirerek proaktif bildirimler almayı tercih edebilir. smart home cihazınızın uygulamasında, kullanıcıların bildirimleri cihazdan (ör. uygulama ayarlarınızdan) açıkça etkinleştirmesine veya devre dışı bırakmasına olanak tanıyan bir özellik de ekleyebilirsiniz.

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

SYNC yanıtınızda şu güncellemelerden birini gönderin:

• Kullanıcı, cihaz uygulamanızda bildirimleri açıkça etkinleştirdiyse veya bir 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 üzerinde bildirimleri tetiklemek için Google Home Graph, Report State ve Notification API çağrısı aracılığıyla Google Home Graph'ye bir bildirim yükü gönderir.

Google HomeGraph API'yi etkinleştirme

1. Google Cloud Console bölümünde 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'dan hizmet hesabı anahtarı oluşturmak için aşağıdaki talimatları uygulayın:

1. Google Cloud Console bölümünde 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. 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. Rol açılır listesinden Hizmet Hesapları > Hizmet Hesabı OpenID Connect Kimlik Jetonu Oluşturucu'yu 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ü olarak 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önderin.

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

API çağrınızda ilettiğiniz notifications nesnesine, bildirimin nasıl sunulacağını 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 şu sekmelerden birinde bir seçenek 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ünde, isteğin durumu, varsa etkinlik hatalarıyla ilgili hata kodları ve EXECUTE amaç isteği sırasında sağlanan geçerli followUpToken bulunur. followUpToken, geçerliliğini korumak ve yanıtı orijinal istekle doğru şekilde ilişkilendirmek için beş dakika içinde kullanılmalıdır.

Aşağıdaki snippet'te, followUpToken alanı içeren bir örnek 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 ilk etkileşimde bulunduğu cihazda göstermek ve kullanıcının tüm cihazlarında yayınlamamak için followUpToken kullanır.

API'yi çağırmak için şu sekmelerden birinde bir seçenek 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'dan Cloud'a için Cloud Logging bölümünde belirtildiği gibi etkinlik günlüğünü destekler. Bu günlükler, işleminizdeki bildirim kalitesini test etmek ve korumak için yararlıdır.

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

status alanı, bildirim yükünde hatalar olabileceğini gösteren çeşitli durumları içerir. Bunlardan bazıları yalnızca üretime sunulmamış işlemler için geçerli olabilir.

Örnek durumlar:

Tüm bildirimler için geçerli olabilecek bu genel durumların yanı sıra, status alanı uygun durumlarda özelliğe özgü durumları da içerebilir (ör. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).