تسمح الإشعارات لتطبيق smart home Action باستخدام Google Assistant للتواصل مع المستخدمين بشأن الأحداث أو التغييرات المهمة ذات الصلة بالجهاز. يمكنك تفعيل الإشعارات لتنبيه المستخدمين بأحداث الجهاز في الوقت المناسب، مثلاً عندما يكون شخص على الباب، أو للإبلاغ عن تغيير مطلوب لحالة الجهاز، مثلاً عند انخراط مسمار قفل الباب بنجاح أو انحشاره.
يمكن للإجراء smart home إرسال الأنواع التالية من الإشعارات إلى المستخدمين:
الإشعارات الاستباقية: تعمل على تنبيه المستخدم بشأن حدث على جهاز smart home بدون أي طلبات سابقة من المستخدم للوصول إلى أجهزته، مثل رنين جرس الباب.
استجابات المتابعة: تأكيد بنجاح طلب أمر الجهاز أو تعذّر تنفيذه، مثلاً عند قفل أحد الباب استخدم هذه التنبيهات لأوامر الجهاز التي يستغرق اكتمالها بعض الوقت. لا تعمل ردود المتابعة إلا عند إرسال طلبات طلبات الجهاز من مكبّرات الصوت والشاشات الذكية.
توفّر "Assistant" هذه الإشعارات للمستخدمين على شكل إعلانات على مكبّرات الصوت الذكية والشاشات الذكية. تكون الإشعارات الاستباقية متوقفة تلقائيًا يمكن للمستخدمين تفعيل جميع الإشعارات الاستباقية أو إيقافها من Google Home app (GHA).
الأحداث التي تؤدي إلى ظهور الإشعارات
عند وقوع أحداث على الجهاز، يرسل "تنفيذ الإجراء" طلب إشعار إلى Google. وتحدّد سمات الجهاز التي يتيحها إجراء smart home أنواع أحداث الإشعارات المتاحة والبيانات التي يمكنك تضمينها في هذه الإشعارات.
تتوافق السمات التالية مع الإشعارات الاستباقية:
سمة | فعاليات |
---|---|
ObjectDetection | الأجسام التي يرصدها الجهاز، مثلاً عند رصد وجه معروف عند الباب. على سبيل المثال: "يوسف وهبة عند الباب الأمامي". |
RunCycle | يكمل الجهاز دورة. على سبيل المثال: "اكتملت دورة الغسّالة". |
SensorState | يرصد الجهاز حالة جهاز استشعار متوافقة. على سبيل المثال: "رصد دخان الدخان" |
TemperatureControl | يصل الجهاز إلى درجة الحرارة المضبوطة. على سبيل المثال: "تمت تسخين الفرن مسبقًا إلى 350 درجة". |
ArmDisarm | يدخل النظام في حالة ما قبل المنبّه مع عد تنازلي للدخول، يتم تشغيله عند فتح باب. |
CameraStream | اربط بالبث المباشر للكاميرا بعد أن يرصد الجهاز جسمًا أو حركة. |
MotionDetection | "تم رصد حركة في الساعة 12 ظهرًا في 1 تموز (يوليو) 2020". |
السمات التالية تدعم ردود المتابعة:
سمة | فعاليات |
---|---|
ArmDisarm | حالة الإكمال والتغيير في الحالة بعد تنفيذ أمر action.devices.commands.ArmDisarm للجهاز على سبيل المثال:
"تم تشغيل جهاز الأمان".
|
LockUnlock | حالة الإكمال والتغيير في الحالة بعد تنفيذ أمر action.devices.commands.LockUnlock للجهاز على سبيل المثال: "تم قفل الباب الأمامي" أو "الباب الأمامي عالق."
|
NetworkControl | حالة الإكمال والتغيير في الحالة بعد تنفيذ أمر action.devices.commands.TestNetworkSpeed للجهاز على سبيل المثال: "انتهى اختبار سرعة الشبكة. تبلغ سرعة التنزيل حاليًا على
جهاز التوجيه في المكتب 80.2 كيلوبت في الثانية، وتبلغ سرعة التحميل 9.3 كيلوبت في الثانية".
|
OpenClose | حالة الإكمال والتغيير في الحالة بعد تنفيذ أمر action.devices.commands.OpenClose للجهاز على سبيل المثال: "تم فتح الباب الأمامي" أو "تعذّر فتح الباب الأمامي".
|
StartStop | حالة الإكمال والتغيير في الحالة بعد تنفيذ أمر action.devices.commands.StartStop للجهاز على سبيل المثال: "تم تشغيل المكنسة الكهربائية".
|
توفِّر جميع أنواع الأجهزة إشعارات للسمات السارية.
إنشاء إشعارات لمهام المنزل المزوّد بأجهزة ذكية
أضِف إشعارات إلى الإجراء "smart home" في المراحل التالية:
- أخبِر Google إذا تم تفعيل الإشعارات من تطبيق جهاز smart home. وفي حال تفعيل المستخدمين الإشعارات أو إيقافها في تطبيقك، يمكنك إرسال طلب
SYNC
لإبلاغ Google بتغيير الجهاز. - عند تغيير حدث أو حالة جهاز ذي صلة يؤدي إلى ظهور إشعار، يمكنك إرسال طلب إشعار من خلال طلب واجهة برمجة تطبيقات 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
-
في Google Cloud Console، انتقِل إلى صفحة HomeGraph API.
الانتقال إلى صفحة HomeGraph API - اختَر المشروع الذي يتطابق مع رقم تعريف مشروع "smart home".
- انقر على تفعيل.
إنشاء مفتاح حساب الخدمة
يُرجى اتّباع هذه التعليمات لإنشاء مفتاح حساب خدمة من Google Cloud Console:
-
في Google Cloud Console، انتقِل إلى صفحة إنشاء مفتاح حساب خدمة.
الانتقال إلى صفحة "إنشاء مفتاح حساب الخدمة" - من قائمة حساب الخدمة، اختَر حساب خدمة جديد.
- في حقل اسم حساب الخدمة، أدخِل اسمًا.
- في حقل رقم تعريف حساب الخدمة، أدخِل رقم تعريف.
من قائمة الدور، اختَر حسابات الخدمة > منشئ الرموز المميّزة لحساب الخدمة.
بالنسبة إلى نوع المفتاح، حدِّد الخيار JSON.
- انقر على إنشاء. ملف JSON يحتوي على المفتاح الذي يتم تنزيله على جهاز الكمبيوتر
إرسال الإشعار
يمكنك الاتصال بطلب الإشعار باستخدام واجهة برمجة تطبيقات
devices.reportStateAndNotification
.
يجب أن يشتمل طلب JSON على eventId
، وهو معرّف فريد تنشئه المنصّة للحدث الذي يؤدّي إلى ظهور الإشعار. يجب أن تكون السمة eventId
رقمًا تعريفيًا عشوائيًا يختلف في كل مرة ترسل فيها طلب إشعار.
في عنصر notifications
الذي تضبطه في طلب بيانات من واجهة برمجة التطبيقات، أدرِج القيمة priority
التي تحدّد طريقة عرض الإشعار. وقد يتضمّن
كائن notifications
حقولاً مختلفة بناءً على سمة الجهاز.
اتّبِع أحد هذه المسارات لضبط الحمولة وطلب واجهة برمجة التطبيقات:
إرسال حمولة الإشعارات الاستباقية
لاستدعاء واجهة برمجة التطبيقات، حدد خيارًا من إحدى علامات التبويب التالية:
HTTP
توفّر واجهة برمجة التطبيقات Home Graph نقطة نهاية HTTP
- استخدِم ملف JSON لحساب الخدمة الذي تم تنزيله لإنشاء رمز JSON المميّز للويب (JWT). لمزيد من المعلومات، يُرجى الاطّلاع على المصادقة باستخدام حساب الخدمة.
- يمكنك الحصول على رمز دخول OAuth 2.0 من خلال نطاق
https://www.googleapis.com/auth/homegraph
باستخدام oauth2l: - أنشِئ طلب JSON باستخدام
agentUserId
. في ما يلي نموذج لطلب JSON لملف "Report State" والإشعار: - ادمج Report State وإشعار JSON والرمز المميّز في طلب HTTP POST مع نقطة نهاية Google Home Graph. إليك مثال على طريقة إرسال الطلب في سطر الأوامر باستخدام
curl
كاختبار:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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 } } } } } } }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
gRPC
توفّر واجهة برمجة التطبيقات Home Graph API نقطة نهاية gRPC.
- احصل على تعريف خدمة المخزن المؤقت للبروتوكول لواجهة برمجة تطبيقات Home Graph.
- اتّبِع مستندات مطوّري برامج gRPC لإنشاء رموز بديلة للعميل لإحدى اللغات المعتمَدة.
- عليك استدعاء طريقة ReportStateAndNotification.
Node.js
يوفّر عميل Node.js API من Google عمليات ربط لواجهة برمجة تطبيقات Home Graph.
- ابدأ بإعداد خدمة
google.homegraph
باستخدام بيانات الاعتماد التلقائية للتطبيق. - استدعِ الطريقة
reportStateAndNotification
باستخدام ReportStateAndNotificationRequest. وتعرضPromise
مع ReportStateAndNotificationResponse.
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 } } } } } } } });
Java
توفّر مكتبة برامج HomeGraph API للغة Java عمليات ربط لواجهة برمجة تطبيقات Home Graph.
- عليك إعداد
HomeGraphApiService
باستخدام بيانات الاعتماد التلقائية للتطبيق. - يمكنك استدعاء الطريقة
reportStateAndNotification
باستخدامReportStateAndNotificationRequest
. وتعرضReportStateAndNotificationResponse
.
// 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
الصالحة، التي تم تقديمها في طلب intent لـ 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
لإخراج الإشعار فقط على الجهاز الذي كان المستخدم يتفاعل معه في الأصل، وليس على جميع أجهزة المستخدم.
لاستدعاء واجهة برمجة التطبيقات، حدد خيارًا من إحدى علامات التبويب التالية:
HTTP
توفّر واجهة برمجة التطبيقات Home Graph نقطة نهاية HTTP
- استخدِم ملف JSON لحساب الخدمة الذي تم تنزيله لإنشاء رمز JSON المميّز للويب (JWT). لمزيد من المعلومات، يُرجى الاطّلاع على المصادقة باستخدام حساب الخدمة.
- يمكنك الحصول على رمز دخول OAuth 2.0 من خلال نطاق
https://www.googleapis.com/auth/homegraph
باستخدام oauth2l: - أنشِئ طلب JSON باستخدام
agentUserId
. في ما يلي نموذج لطلب JSON لملف "Report State" والإشعار: - ادمج Report State وإشعار JSON والرمز المميّز في طلب HTTP POST مع نقطة نهاية Google Home Graph. إليك مثال على طريقة إرسال الطلب في سطر الأوامر باستخدام
curl
كاختبار:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "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": "PLACEHOLDER", "networkDownloadSpeedMbps": 23.3, "networkUploadSpeedMbps": 10.2 } } } } } } }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
gRPC
توفّر واجهة برمجة التطبيقات Home Graph نقطة نهاية gRPC.
- احصل على تعريف خدمة المخزن المؤقت للبروتوكول لواجهة برمجة تطبيقات Home Graph.
- اتّبِع مستندات مطوّري برامج gRPC لإنشاء رموز بديلة للعميل لإحدى اللغات المعتمَدة.
- عليك استدعاء طريقة ReportStateAndNotification.
Node.js
يوفّر عميل Node.js API من Google عمليات ربط لواجهة برمجة تطبيقات Home Graph.
- ابدأ بإعداد خدمة
google.homegraph
باستخدام بيانات الاعتماد التلقائية للتطبيق. - استدعِ الطريقة
reportStateAndNotification
باستخدام ReportStateAndNotificationRequest. وتعرضPromise
مع ReportStateAndNotificationResponse.
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, } } } } } } } });
Java
توفّر مكتبة برامج HomeGraph API للغة Java عمليات ربط لواجهة برمجة تطبيقات Home Graph.
- عليك إعداد
HomeGraphApiService
باستخدام بيانات الاعتماد التلقائية للتطبيق. - يمكنك استدعاء الطريقة
reportStateAndNotification
باستخدامReportStateAndNotificationRequest
. تعرض النتيجةReportStateAndNotificationResponse
.
// 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
:
الموقع | الوصف |
---|---|
requestId |
رقم تعريف طلب الإشعار |
structName |
اسم بنية الإشعار، مثل "ObjectDetection" |
status |
تشير إلى حالة الإشعار. |
يتضمّن الحقل status
حالات مختلفة قد تشير إلى أخطاء في حمولة الإشعار. وقد لا يتوفّر بعضها إلا ضمن المهام التي لم يتم إطلاقها في قناة الإصدار العلني.
تشمل أمثلة الحالات ما يلي:
الحالة | الوصف |
---|---|
EVENT_ID_MISSING |
يشير إلى عدم توفّر حقل eventId المطلوب.
|
PRIORITY_MISSING |
يشير إلى عدم توفّر حقل priority .
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
تشير هذه السمة إلى أنّ سمة notificationSupportedByAgent الخاصة بالجهاز الذي يتم إرسال إشعار به والتي تم تقديمها في "SYNC " غير صحيحة.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
وتشير هذه القيمة إلى أنّ المستخدم لم يفعّل الإشعارات على جهاز إرسال الإشعارات في GHA. لا تتوفّر هذه الحالة إلا في الإجراءات التي لم يتم إطلاقها في قناة الإصدار العلني. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
يشير هذا الرمز إلى أنّ المستخدم لم يعيّن جهاز الإشعار لمنزل أو بنية. لا تتوفّر هذه الحالة إلا في الإجراءات التي لم يتم إطلاقها في قناة الإصدار العلني. |
بالإضافة إلى هذه الحالات العامة التي يمكن أن تنطبق على جميع الإشعارات، قد يتضمّن الحقل status
أيضًا حالات خاصة بالسمات حيثما ينطبق ذلك (مثل OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).