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

تتيح الإشعارات لـ "الإجراء" في "smart home" استخدام Google Assistant للتواصل مع المستخدمين بشأن الأمور المهمة الأحداث أو التغييرات المتعلقة بالجهاز. يمكنك تفعيل الإشعارات لإرسال تنبيهات المستخدمين إلى أحداث الجهاز في الوقت المناسب، على سبيل المثال عند وجود شخص على الباب، أو الإبلاغ عن التغيير المطلوب لحالة الجهاز، مثلاً عندما يحتوي برغي قفل الباب الذين واجهوا مشكلة أو عرقلة

يمكن أن يرسل الإجراء smart home الأنواع التالية من إشعارات للمستخدمين:

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

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

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

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

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

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

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

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

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

أضِف إشعارات إلى الإجراء "smart home" في المراحل التالية:

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

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

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

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

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

في ردّ SYNC، أرسِل أحد هذه التعديلات:

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

يوضِّح المقتطف التالي مثالاً على كيفية ضبط استجابة "المزامنة":

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. من قائمة حساب الخدمة، اختَر حساب خدمة جديد.
3. في حقل اسم حساب الخدمة، أدخِل اسمًا.
4. في حقل رقم تعريف حساب الخدمة، أدخِل رقم تعريف.

5. من قائمة الدور، اختَر حسابات الخدمة >. منشئ الرمز المميّز لحساب الخدمة

6. بالنسبة إلى نوع المفتاح، حدِّد الخيار JSON.

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

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

يمكنك الاتصال بطلب الإشعار باستخدام devices.reportStateAndNotification API. يجب أن يحتوي طلب 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).