إشعارات بشأن إجراءات المنزل المزوّد بأجهزة ذكية

تسمح الإشعارات لعملية دمج Cloud-to-cloud باستخدام Google Assistant للتواصل مع المستخدمين بشأن الأحداث أو التغييرات المهمة المتعلقة بالجهاز. يمكنك تنفيذ الإشعارات لتنبيه المستخدمين بشأن أحداث الجهاز في الوقت المناسب، مثلاً عندما يكون شخص ما عند الباب، أو للإبلاغ عن تغيير في حالة الجهاز تم طلبه، مثلاً عندما يتم إغلاق مزلاج الباب بنجاح أو عندما يتعطّل.

يمكن لعملية دمج Cloud-to-cloud إرسال الأنواع التالية من الإشعارات إلى المستخدمين:

• الإشعارات الاستباقية: تنبّه المستخدم بشأن smart homeحدث على الجهازsmart home بدون أن يسبقه أي طلب من المستخدم إلى أجهزته، مثل رنين جرس الباب.

• الردود المتابعة: تأكيد على نجاح طلب تنفيذ أمر على جهاز أو فشله، مثلاً عند قفل باب استخدِم هذه التنبيهات لأوامر الجهاز التي تستغرق وقتًا طويلاً لإكمالها. لا تتوفّر الردود اللاحقة إلا عند إرسال طلبات أوامر الأجهزة من مكبّرات الصوت والشاشات الذكية.

تقدّم Assistant هذه الإشعارات للمستخدمين على شكل إعلانات على مكبّرات الصوت والشاشات الذكية. تكون الإشعارات الاستباقية غير مفعّلة تلقائيًا. يمكن للمستخدمين تفعيل جميع الإشعارات الاستباقية أو إيقافها من خلال Google Home app (GHA).

الأحداث التي تؤدي إلى إرسال إشعارات

عند وقوع أحداث على الجهاز، يرسل نظام التنفيذ طلب إشعار إلى Google. تحدّد سمات الجهاز التي يتوافق معها تكامل Cloud-to-cloud أنواع أحداث الإشعارات المتاحة والبيانات التي يمكنك تضمينها في تلك الإشعارات.

تتيح السمات التالية إرسال الإشعارات الاستباقية:

تتيح السمات التالية الردود اللاحقة:

تتيح جميع أنواع الأجهزة تلقّي إشعارات بشأن السمات السارية.

إنشاء إشعارات لعملية الدمج بين الخدمات المستندة إلى السحابة الإلكترونية

أضِف إشعارات إلى عملية دمج Cloud-to-cloud في المراحل التالية:

1. يجب إبلاغ Google بما إذا كانت الإشعارات مفعّلة من تطبيقك على الجهاز. إذا فعّل المستخدمون الإشعارات أو أوقفوها في تطبيقك، أرسِل طلب SYNC لإبلاغ Google بالتغيير الذي تم إجراؤه على الجهاز.smart home
2. عند حدوث حدث ذي صلة بالجهاز أو تغيير في الحالة يؤدي إلى تشغيل إشعار، أرسِل طلب إشعار من خلال استدعاء واجهة برمجة التطبيقات Report State reportStateAndNotification. إذا تغيّرت حالة الجهاز، يمكنك إرسال حمولة الحالة والإشعار معًا في طلب Report State وطلب الإشعار.

تتناول الأقسام التالية هذه الخطوات بمزيد من التفصيل.

تحديد ما إذا كانت الإشعارات مفعّلة في تطبيقك

يمكن للمستخدمين اختيار ما إذا كانوا يريدون تلقّي إشعارات استباقية من خلال تفعيل هذه الميزة في GHA. في تطبيق جهازك smart home، يمكنك أيضًا إضافة خيار يتيح للمستخدمين تفعيل الإشعارات أو إيقافها بشكل صريح من الجهاز، مثلاً من إعدادات تطبيقك.

أخبِر Google بأنّ الإشعارات مفعّلة على جهازك من خلال إجراء طلب مزامنة لتعديل بيانات الجهاز. عليك إرسال طلب SYNC مشابه كلما غيّر المستخدمون هذا الإعداد في تطبيقك.

في ردّك على SYNC، أرسِل أحد التحديثات التالية:

• إذا فعّل المستخدم الإشعارات بشكل صريح في تطبيق الجهاز، أو إذا لم توفّر خيارًا لتفعيل الإشعارات أو إيقافها، اضبط قيمة السمة devices.notificationSupportedByAgent على true.
• إذا أوقف المستخدم الإشعارات بشكل صريح في تطبيق الجهاز، اضبط قيمة السمة devices.notificationSupportedByAgent على false.

يعرض المقتطف التالي مثالاً على كيفية ضبط استجابة SYNC:

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

إرسال طلبات الإشعارات إلى Google

لتفعيل الإشعارات على Assistant، يرسل نظام تنفيذ الطلبات حمولة إشعار إلى Google Home Graph عبر Report State وطلب Notification API.

تفعيل واجهة برمجة التطبيقات Google HomeGraph

1. في Google Cloud Console، انتقِل إلى صفحة HomeGraph API.

   الانتقال إلى صفحة HomeGraph API
2. اختَر المشروع الذي يتطابق مع رقم تعريف مشروع smart home.
3. انقر على تفعيل.

إنشاء مفتاح حساب خدمة

اتّبِع التعليمات التالية لإنشاء مفتاح حساب خدمة من Google Cloud Console:

1. في Google Cloud Console، انتقِل إلى صفحة حسابات الخدمة.

   انتقِل إلى صفحة "حسابات الخدمة".

   قد تحتاج إلى اختيار مشروع قبل الانتقال إلى صفحة "حسابات الخدمة".

2. انقر على addإنشاء حساب خدمة.

3. في حقل اسم حساب الخدمة، أدخِل اسمًا.

4. في حقل معرّف حساب الخدمة، أدخِل معرّفًا.

5. في حقل وصف حساب الخدمة، أدخِل وصفًا.

6. انقر على إنشاء ومتابعة.

7. من القائمة المنسدلة الدور، اختَر حسابات الخدمة > أداة إنشاء الرمز المميز لهوية OpenID Connect لحساب الخدمة.

8. انقر على متابعة.

9. انقر على تم.

10. اختَر حساب الخدمة الذي أنشأته للتو من قائمة حسابات الخدمة، ثم اختَر إدارة المفاتيح من قائمة more_vert الإجراءات.

11. انقر على إضافة مفتاح > إنشاء مفتاح جديد.

12. بالنسبة إلى نوع المفتاح، اختَر الخيار JSON.

13. انقر على إنشاء. سيتم تنزيل ملف JSON يحتوي على مفتاحك إلى جهاز الكمبيوتر.

إرسال الإشعار

إجراء طلب الإشعار باستخدام واجهة برمجة التطبيقات devices.reportStateAndNotification يجب أن يتضمّن طلب JSON eventId، وهو رقم تعريف فريد تنشئه منصتك للحدث الذي يؤدي إلى تشغيل الإشعار. يجب أن يكون eventId معرّفًا عشوائيًا يختلف في كل مرة ترسل فيها طلب إشعار.

في العنصر notifications الذي ترسله في طلب البيانات من واجهة برمجة التطبيقات، أدرِج قيمة priority تحدّد طريقة عرض الإشعار. قد يتضمّن العنصر notifications حقولاً مختلفة حسب سمة الجهاز.

اتّبِع أحد المسارات التالية لضبط الحمولة واستدعاء واجهة برمجة التطبيقات:

• إرسال حمولة إشعار استباقي
• إرسال حمولة ردّ للمتابعة

إرسال حمولة إشعار استباقي

لطلب بيانات من واجهة برمجة التطبيقات، اختَر خيارًا من إحدى علامات التبويب التالية:

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

إرسال حمولة ردّ المتابعة

تحتوي حمولة الردّ اللاحق على حالة الطلب ورموز الخطأ في حال حدوث أي أخطاء في الأحداث، بالإضافة إلى followUpToken الصالح الذي تم تقديمه أثناء طلب الغرض EXECUTE. يجب استخدام followUpToken في غضون خمس دقائق ليبقى صالحًا ولربط الرد بالطلب الأصلي بشكل صحيح.

يعرض المقتطف التالي مثالاً على حمولة طلب EXECUTE مع حقل 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 followUpToken لعرض الإشعار على الجهاز الذي كان المستخدم يتفاعل معه في الأصل فقط، وليس على جميع أجهزة المستخدم.

لطلب بيانات من واجهة برمجة التطبيقات، اختَر خيارًا من إحدى علامات التبويب التالية:

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

التسجيل

تتيح الإشعارات تسجيل الأحداث كما هو موضّح في تسجيل الأحداث في السحابة الإلكترونية من السحابة الإلكترونية. تكون هذه السجلات مفيدة لاختبار جودة الإشعارات والحفاظ عليها ضمن تطبيقك على "أعمال Google".

في ما يلي مخطط إدخال notificationLog:

يتضمّن الحقل status حالات مختلفة قد تشير إلى حدوث أخطاء في حمولة الإشعار. قد لا تتوفّر بعض هذه الميزات إلا في الإجراءات التي لم يتم إطلاقها في مرحلة الإنتاج.

تشمل حالات التحديث ما يلي:

بالإضافة إلى الحالات العامة التي يمكن أن تنطبق على جميع الإشعارات، قد يتضمّن الحقل status أيضًا حالات خاصة بالسمات حيثما ينطبق ذلك (على سبيل المثال، OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).