أسئلة عامة
س: أين يجب تنفيذ البنية الأساسية لتنفيذ "المهام مع مساعد Google" وبأي لغة؟
ج: ما دامت طبقة المقابس الآمنة (SSL) الحديثة (TLS) وOAuth 2.0 متوافقة، يمكنك تنفيذ البنية الأساسية على أي نظام أساسي وبأي لغة تختارها. ننصح بنشر التطبيق في أقرب وقت ممكن إلى بقية البنية الأساسية لتحسين الموثوقية وتقليل وقت الاستجابة لتنفيذ أجهزة المستخدمين الفعلية.
س: هل يجب أن تكون أرقام تعريف الأجهزة فريدة؟
ج: يجب أن تكون أرقام التعريف فريدة. إذا لم يكن لديك معرّفات فريدة على مستوى خدمتك، يجب أن تكون فريدة على الأقل على مستوى كل مستخدم. تخيل مستخدمًا لديه منازل متعددة، حيث يضم كلا المنزلين عمليات دمج لنفس المستخدم. إنّ طلب تشغيل مصباح في منزل واحد يجب ألا يؤدي إلى تشغيل مصباح يحمل نفس المعرّف في منزل آخر.
س: هل يجب أن تكون أسماء الأجهزة فريدة؟
ج: لا يجب أن تكون الأسماء فريدة، على الرغم من أننا قد نشجع الأشخاص بمرور الوقت على تحسين التسمية السيئة بعد الإعداد للحصول على تجربة مستخدم أفضل.
إليك دليل التسمية السريع:
- يجب أن تكون الأسماء كما يسمعها المستخدمون.
- ونتعرف على المجموعات الفرعية من السلاسل، لذلك إذا كان لديك "acme color light"، سنجيب أيضًا على "acme light".
- نحن نشجّع على إضافة اسم وصفي للمنتج واسم واحد أو أكثر من الأسماء التي يحدّدها المستخدم.
- لا يحتاج المستخدمون إلى إعطاء أسماء لغرف المصابيح لأنّ لدينا غرفًا لذلك. يجب أن يكون لديهم أسماء فريدة لكل غرفة، ولكن يمكنهم دائمًا استخدام صيغ الجمع لتوجيه جميع الأمور (على سبيل المثال، المصباحان في شمعدانات المكتب هما "الإضاءة الشمالية" و"الإضاءة الشرقية"، ولكن يمكن طلبها باسم "مصابيح" فقط).
س: كم مرة يتم تحديث حالة الجهاز؟
A: يتم استرداد الحالة المؤقتة عند إما QUERY أو EXECUTE، وهي إجراءات يبدأها المستخدم. إذا سأل المستخدم "هل الضوء قيد التشغيل؟" أو يريد زيادة سطوع الضوء، فسنحتاج إلى إجراء استعلام لمعرفة الحالة الحالية.
س: هل من الممكن تعديل Home Graph مباشرةً حسب الحالة الراهنة للجهاز؟
ج: نعم، استخدم طلب بيانات من واجهة برمجة التطبيقات Report State.
ربط الحساب وبروتوكول OAuth
س: هل علينا ربط الحسابات؟
ج: نعم، يجب ربط الحسابات لربط أجهزة المستخدم بخدمات السحابة الإلكترونية لدى مقدّم الخدمة.
س: بالنسبة إلى OAuth، تنتهي صلاحية رموز الدخول كل 15.213 ساعة، هل هذا مناسب؟
ج: نعم، ولكن يُرجى إجراء الاختبار على أن يكون وقت انتهاء الصلاحية قصير إلى حد ما، لنفترض 10-20 دقيقة. على عميل OAuth تحديث الرموز المميزة حسب الحاجة، وسيثبت الاختبار خلال فترة انتهاء صلاحية قصيرة أن الرمز يعمل.
مكان ووقت الاستماع إلى الموسيقى
س: متى تتم المزامنة؟
ج: تحدث المزامنة بعد اكتمال OAuth مباشرةً وبعد إجراء طلب طلب المزامنة.
س: لماذا لا يعمل SYNC؟
ج: هناك عدد من الأسباب الشائعة لفشل هذه العملية.
إرسال أنواع الأجهزة الخاطئة
- على سبيل المثال، نتوقع عرض
action.devices.types.LIGHT، ولكنّك ترسلaction.devices.types.Light.
- على سبيل المثال، نتوقع عرض
أنت ترسل أنواع الأجهزة غير المتوافقة.
- على سبيل المثال، إذا كنت ترسل
action.devices.types.FLASHLIGHT، فلا نتيح هذه الميزة.
- على سبيل المثال، إذا كنت ترسل
أنت ترسل حقولاً غير صالحة/غير متوافقة
- على سبيل المثال، لديك حقل إصدار أو حقل آخر غير محدد في مواصفاتنا.
هناك مشكلة أخرى متعلقة بالتنسيق في استجابة المزامنة.
- تحقق من الأقواس!
أنت تواجه مشكلة في ربط الحساب.
- يُرجى التأكّد من أنك تتلقّى رمز دخول صالحًا في عنوان المصادقة لطلب المزامنة.
تستغرق الاستجابة لطلب المزامنة وقتًا طويلاً جدًا.
- يُرجى التأكّد من الردّ على طلب "المزامنة" في غضون 5 ثوانٍ.
س: هل الردّ "في انتظار المراجعة" مقبول؟
ج: نفضّل بشدة تلقي استجابة النجاح/الفشل، بدلاً من الردّ في انتظار المراجعة، إذا كانت أجهزتك متاحة في الوقت الفعلي. يُرجى التواصل معنا إذا شعرت بأنك بحاجة إلى رد "في انتظار المراجعة"، فنحن ندرك أن بعض الأجهزة منخفضة الطاقة التي لا تعمل في الوقت الفعلي قد تتطلب استجابة معلّقة ونموذج تنفيذ غير متزامن.
الاختبار والإرسال
س: هل يمكننا إعداد بيئة مرحلية؟
ج: نعم، يرجى إنشاء مشروع منفصل واستكمال عملية الإعداد لهذا المشروع. لك مطلق الحرية في إنشاء أكبر عدد ممكن من المشروعات التي تحتاجها لتعيينها لعمليات التطوير والبنية التحتية لديك.
س: كم مرة أحتاج إلى تعديل مسودّة مشروعي؟
ج: يجب إعادة تحميل مسودة المشروع كل 3 أيام. بعد مرور 3 أيام، سيختفي وكيل الاختبار من إعدادات mobile-HomeControl. إذا صادفت هذا، انقر على زر اختبار المسودة لمشروعك في Actions on Google Console.
س: هل يمكنني الاختبار على أكثر من جهاز في وقت واحد؟
ج: لا تتيح خدمة Actions on Google سوى نقطة وصول واحدة "للتجربة على الجهاز" في المرّة الواحدة. إذا استخدمت أولاً مسودة اختبار على "ap1" وأجريت مزامنة للأجهزة، ثم (بدون إلغاء ربط ap1) شغِّل TEST DRAFT "ap2" مباشرةً، سيختفي "ap1" من إعدادات mobile-HomeControl. لتصحيح ذلك، شغِّل مسودة اختبار على "ap1" مرة أخرى ويمكنك إلغاء ربط "ap1" في الإعدادات.
يُرجى العِلم أنّ حزمة الإجراءات هذه ستكون متاحة لكل أجهزة Google Assistant الخاصة بك للمستخدم، على سبيل المثال، يمكنك اختبار التكامل الجديد للأجهزة على كل من مكبّرات الصوت التي تم تفعيل ميزة الصوت بها و"Android".
س: تم رفض طلب مشروع "المهام" بسبب الاسم أو طريقة اللفظ، فما الذي أحتاج إلى تغييره؟
ج: نتحقّق من طريقة لفظ الاسم للتأكّد من أنّه لن يتم استخدام اسم طريقة اللفظ من خلال إجراء آخر في المستقبل وأنّه يتطابق مع الاسم المعروض (لمنع حالات عدم التطابق التي تؤثر في عمليات تسجيل الأسماء في المستقبل).
لمواصلة استخدام الاسم نفسه، يُرجى التواصل مع فريق الدعم لكي يضيفه فريق الدعم المسؤول عن الكلام إلى Assistant.
س: الإجراء الخاص بي غير مرئي في قسم "الإدارة الآلية للمنزل" في تطبيق Google Home، فما الذي يحدث؟
ج: يمكن أن تكون المشكلة واحدة مما يلي:
- لم تنقر على زر اختبار المسودة لمشروعك في Actions Console.
- يمكنك الحصول على إجراء واحد فقط في ميزة "الاختبار على الجهاز" في آنٍ واحد.
- في Actions Console، يمكنك الانتقال إلى علامة التبويب "المحاكي" لمشروع الإجراءات، وتبديل مفتاح التبديل "نشط/غير نشط" إلى "غير نشط" ثم "نشط" مرة أخرى.
- إذا تمت مشاركة هذا الإجراء معك، يُرجى التأكّد من اتّباع جميع تعليمات المشاركة.
- تنتهي صلاحية الاختبار على الجهاز بعد ثلاثة أيام. انقر على زر اختبار المسودة لمشروعك في Actions Console.
س: لماذا تظهر لي رسالة خطأ عند كتابة "تحدث إلى <my agent name>" في المحاكي؟
ج: لا تستخدِم إجراءات المنزل المزوّد بأجهزة ذكية أسماء الاستدعاءات. لإجراء الاختبار في المحاكي، يجب إجراء ربط الحساب على هاتف Android أو هاتف iOS مثبَّت عليه "Google Home app (GHA)". يجب أن تكون لديك أيضًا أجهزة مرتبطة بحسابك قبل تنفيذ عملية ربط الحساب.
س: لماذا تظهر لي أخطاء عندما أحاول استخدام المحاكي؟
ج: لا يمكنك استخدام المحاكي لاختبار إجراءات smart home التي تم نشرها. إذا كنت تريد استخدام المحاكي لمشروع تشغيل آلي للمنزل قيد الإنتاج، يلزمك إنشاء مشروع جديد لأغراض الاختبار.
حالة التقرير
س: هل هناك متطلبات أساسية لتنفيذ "حالة التقرير"؟
ج: يحتاج المشروع إلى استخدام واجهة برمجة تطبيقات Smart Home، وأن يتوافق مع OAuth2، ويحتاج إلى سمات يجب أن يتم الإبلاغ عنها فيه.
س: كم مرة نحتاج إلى الإبلاغ عن الحالة على الجهاز؟
ج: تهتم Google بعملية النقل وحالة الوحدة الطرفية. ومع ذلك، إذا كانت هناك العديد من التغييرات في الحالة خلال فترة زمنية قصيرة (على سبيل المثال، عندما يفتح المستخدم الثلاجة ويغلقها ثلاث مرات في الدقيقة أو ينحدر من موضع أقل تعتيمًا)، لن نحتاج إلا إلى الحالة النهائية التي تم الإبلاغ عنها.
س: هل يلزم إرسال حالة الجهاز بالكامل عند إجراء مكالمات "حالة التقرير"؟
ج: لا تتوفّر ميزة التعديلات الجزئية للحالة، لذلك يجب أن تتضمّن طلبات Report State دائمًا جميع البيانات الخاصة بسمة معيّنة تم تعديلها. إذا كانت هناك سمتان ستخلق تناقضًا، فيجب الإبلاغ عنهما معًا مرة أخرى.
س: هل بإمكان محرّك بحث Google إرسال طلب بحث إلى جهازي للحصول على الحالة (أي استطلاع رأي الجهاز)؟
ج: هذه آلية احتياطية لا ننصح بها. وإذا احتجنا إلى العودة إلى إجراء فحص متكرر لأحد الأجهزة لهؤلاء المستخدمين، لا يمكننا ضمان حجم الحمل الإضافي. تأتي الحاجة من مساحات العرض المرئية الجديدة. بالإضافة إلى مشكلة التحميل غير المعروفة، سيكون هناك تدهور في تجربة المستخدم. ونعتقد أنّ Report State هو عامل أساسي في المنصة.
س: ما هي السمات التي تدعم "حالة التقرير" في الوقت الحالي؟
ج: تتم إتاحة جميع السمات العامة التي لها حالات مرتبطة بها. يجب أيضًا الإبلاغ عن أي تغيير في حالة اتصال الجهاز بالإنترنت.
لاحظ أن المشاهد ليس لها حالات. ومع ذلك، قد تؤدي إلى تغيير حالات الجهاز. إذا حدثت حالة تغيير في أي جهاز في Google Home Graph، يجب الإبلاغ عن ذلك مرة أخرى.
س: هل تتطلب حالة التقرير إرسال طابع زمني؟
ج: لا نطلب طابعًا زمنيًا، فالحالة الأخيرة المرسلة ستلغي المكالمات السابقة.
س: هل أحتاج إلى "الإبلاغ عن الحالة" بشكل منفصل إذا كنت أُرسِل الولاية في طلب البحث و/أو التنفيذ؟
ج: يحفظ "Home Graph" الولاية التي يتمّ إرسالها عبر Report State فقط. يتم استخدام الحالة التي يتم عرضها كاستجابة إلى EXECUTE وأغراض QUERY فقط للاستجابات الكلامية للمستخدم ولا يتم تخزينها. نتيجةً لذلك، يجب طلب Report State حتى إذا تم عرض الحالة الجديدة للجهاز كاستجابة للطلب EXECUTE أو QUERY.
س: ما هي عواقب عدم تنفيذ "حالة التقرير" بالكامل في الموعد النهائي المحدَّد؟
ج: سيؤدي ذلك إلى تدهور تجربة المستخدم، على سبيل المثال في GHA ومساحات العرض المرئية. هذا يعني أنه سيتم إرسال العديد من أغراض QUERY إلى استطلاع للولاية ولا يمكننا أن نضمن ما سيقابله من حمل إضافي على سحابة الشركاء.
س: كيف يمكنني اختبار تنفيذ "حالة التقرير"؟
الإجابة: استخدِم عارِض الرسم البياني المنزلي، وهي أداة اختبار ذاتية الخدمة تعرض لك حالات جهازك الحالية المخزَّنة في Home Graph.
س: هل يمكننا استخدام requestId عشوائي لحالة التقرير؟
ج: ننصح الشركاء باستخدام رقم تعريف الطلب نفسه الذي تلقّوه من الطلب "تنفيذ" إذا تم تفعيل Report State من خلال الطلب "تنفيذ"، وإلا يمكنك استخدام معرّف طلب عشوائي.
س: في حال كان المستخدم يمتلك أجهزة متعددة وتم تغيير حالة أحد هذه الأجهزة، هل علينا الإبلاغ عن أحدث حالة لجميع الأجهزة؟
ج: لا. ما عليك سوى الإبلاغ عن حالة هذا الجهاز بالتحديد.
أفضل الممارسات
س: ما نوع وقت الاستجابة المقبول؟
ج: العدد المثالي هو 200 ملّي ثانية، أو من 2 إلى 5 ثوانٍ. إذا كان وقت الاستجابة يتجاوز 5 ثوانٍ تقريبًا، تواصَل معنا.
س: كيف أجعل مكبّر الصوت الذي يتم تفعيله صوتيًا يستجيب بشكل صحيح عندما يكون غير متصل بالإنترنت؟
ج: إعادة حالة عدم الاتصال بالإنترنت للأجهزة غير المتصلة بالإنترنت. نعرض "غير متاح الآن" كـ TTS لهذا الخطأ. ولمزيد من المعلومات، يمكنك الاطّلاع على الأخطاء والاستثناءات.