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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

الأحداث التي تؤدي إلى ظهور الإشعارات

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

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

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

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

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

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

1. أبلِغ Google إذا كانت الإشعارات مفعّلة من تطبيق smart home جهازك. إذا فعّل المستخدمون الإشعارات أو أوقفوها في تطبيقك، أرسِل طلبًا SYNC لإعلام Google بتغيير الجهاز.
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 API

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

التسجيل

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

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

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

تشمل أمثلة الحالات ما يلي:

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