بنود عامة
س: أين وأين يجب تطبيق البنية الأساسية لتنفيذ "المهام مع مساعد Google" في قسم "المهام مع مساعد Google"؟
ج: طالما أنّ هذا البروتوكول يتوافق مع طبقة المقابس الآمنة (SSL) وOAuth 2.0 الحديثة، يمكنك تنفيذ البنية الأساسية على أي نظام أساسي وبأي لغة تختارها. وننصحك بالنشر في أقرب وقت ممكن من بقية البنية الأساسية لتحسين الموثوقية وتقليل وقت الاستجابة للتنفيذ على أجهزة المستخدمين الفعلية.
س: هل يجب أن تكون أرقام تعريف الأجهزة فريدة؟
ج: يجب أن تكون المعرّفات فريدة. إذا لم تكن لديك معرّفات فريدة في خدمتك، يجب أن تكون فريدة على الأقل على مستوى كل مستخدم. تخيل مستخدمًا لديه منازل متعددة، حيث يحتوي كلا المنزلين على تكامل للمستخدم نفسه. إنّ طلب تشغيل مصباح في أحد المنازل يجب ألا يؤدي إلى إضاءة مصباح يحمل المعرّف نفسه في منزل آخر.
س: هل يجب أن تكون أسماء الأجهزة فريدة؟
ج: ليس من الضروري أن تكون الأسماء فريدة، على الرغم من أنّنا قد نشجّع المستخدمين بمرور الوقت على تحسين صياغة الأسماء السيئة بعد عملية الإعداد لتقديم تجربة أفضل للمستخدم.
فيما يلي دليل تسمية سريع:
- يجب أن تكون الأسماء ردودًا على أشخاص
- ونحن نتعرف على مجموعات فرعية من السلاسل، لذلك إذا كان لديك "acme color light" سنجيب أيضًا عن "acme light".
- نشجعك على استخدام اسم وصفي للمنتج واسم واحد أو أكثر من الأسماء التي يحددها المستخدم.
- لا يحتاج المستخدمون إلى تسمية غُرف مصابيح، لأنّ لدينا غرفًا لذلك. يجب أن يكون لديهم أسماء فريدة لكل غرفة، ولكن يمكنهم دائمًا استخدام صيغ الجمع للتوجيه إلى كل شيء (على سبيل المثال، المصباحان في شموع المكتب هما "المصباح الشمالي" و"المصباح الشرقي"، ولكن يمكن استخدامهما باعتبارهما "أضواء" فقط).
س: كم مرة يتم تحديث حالة الجهاز؟
أ: يتم استرداد الحالة المؤقتة إما من خلال 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) شغِّل المسودة "ap2" مباشرةً، ستختفي "ap1" من إعدادات "mobile-HomeControl-settings". لتصحيح هذه المشكلة، شغِّل مسودّة اختبارية على "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 API، والتوافق مع OAuth2، ويجب أن تتوفر سمات لها حالات يتم الإبلاغ عنها.
س: كم مرة نحتاج إلى الإبلاغ عن حالة الجهاز على الجهاز؟
ج: تهتم Google بعملية الانتقال وحالة الوحدة الطرفية، ولكن إذا حدث العديد من التغييرات في الحالة خلال فترة زمنية قصيرة (على سبيل المثال، يفتح أحد المستخدمين الثلاجة ويغلقها ثلاث مرات خلال دقيقة واحدة أو يعرض زيادة تعتيم الشاشة)، لن نحتاج سوى إلى الإبلاغ عن الحالة النهائية.
س: هل يلزم إرسال حالة الجهاز بالكامل عند إجراء مكالمات حالة التقرير؟
ج: لا يمكن إجراء تعديلات جزئية على الحالة، لذا يجب أن تتضمّن الطلبات Report State دائمًا جميع البيانات الخاصة بسمة معيّنة تم تعديلها. إذا كانت هناك سمتان ستنشئان تناقضًا، يجب الإبلاغ عنهما معًا مرة أخرى.
س: هل يمكن لـ Google إجراء طلب بحث عن جهازي لمعرفة الحالة (أي استطلاع رأي الجهاز)؟
ج: هذه آلية احتياطية لا ننصح بها. إذا احتجنا إلى العودة لإجراء استطلاع رأي على أحد الأجهزة بشكلٍ متكرر لهؤلاء المستخدمين، لا يمكننا ضمان مقدار الحِمل الإضافي. وهذه الحاجة تأتي من المنصّات المرئية الجديدة. بالإضافة إلى مشكلة التحميل غير المعروفة، تترك انطباعًا سيئًا لدى المستخدم. نعتبر أنّ Report State مهم بالنسبة إلى المنصة.
س: ما السمات التي تدعم "حالة التقرير" في الوقت الحالي؟
ج: يتم دعم جميع السمات العامة التي لها حالات مرتبطة. يجب أيضًا الإبلاغ عن أي تغيير في حالة الاتصال بالإنترنت للجهاز.
يُرجى العِلم أنّ المشاهد لا تتضمّن حالات. ومع ذلك، قد تؤدي إلى تغيير حالات الأجهزة. إذا كانت هناك حالة تغيير في أي جهاز في Google Home Graph، يجب الإبلاغ عن ذلك.
س: هل تتطلّب "حالة التقرير" إرسال طابع زمني؟
ج: لا نحتاج إلى طابع زمني، لأنّ آخر حالة تم إرسالها ستحلّ محلّ المكالمات السابقة.
س: هل يجب الإبلاغ عن الحالة بشكل منفصل إذا كنت أُرسِل الحالة في "طلب البحث" و/أو "التنفيذ"؟
ج: يخزِّن Home Graph الولاية التي يتم إرسالها عبر Report State فقط. ولا يتم استخدام الحالة التي يتم إرجاعها كاستجابة للطلب EXECUTE وQUERY intent إلا للردود على الكلام للمستخدم ولا يتم تخزينها. نتيجةً لذلك، يجب استدعاء Report State حتى إذا تم إرجاع الحالة الجديدة للجهاز كاستجابة لطلب تنفيذ أو QUERY.
س: ما هي النتائج المترتبة على عدم تنفيذ "حالة التقرير" بالكامل خلال الموعد النهائي المحدد؟
ج: سيؤدي ذلك إلى انخفاض تجربة المستخدم، على سبيل المثال في GHA ومساحات العرض المرئية. يعني ذلك أنّه سيتم إرسال العديد من نوايا QUERY لاستطلاع الولاية ولا يمكننا ضمان ما يقابل ذلك التحميل الإضافي على السحابة الإلكترونية للشريك.
س: كيف يمكنني اختبار عملية تنفيذ "حالة التقرير"؟
ج: استخدم Home Graph Viewer - أداة اختبار ذاتية الخدمة تعرض لك حالات جهازك الحالية المخزّنة في Home Graph.
س: هل يمكننا استخدام رقم تعريف طلب عشوائي لحالة التقرير؟
ج: ننصح الشركاء باستخدام رقم requestId نفسه الذي تلقّوه من طلب التنفيذ إذا تم تفعيل Report State من خلال طلب التنفيذ، وإلّا يمكنك استخدام رقم تعريف طلب عشوائي.
س: إذا كان لدى المستخدم عدة أجهزة وتم تغيير حالة أحدها، هل علينا الإبلاغ عن أحدث حالة لجميع الأجهزة؟
ج: لا، ما عليك سوى الإبلاغ عن حالة هذا الجهاز المحدّد.
أفضل الممارسات
س: ما نوع وقت الاستجابة المقبول؟
ج: المدة المثالية هي أقلّ من 200 ملي ثانية، ولكن يمكن أن تتراوح المدة بين ثانيتين و5 ثوانٍ. إذا كان وقت الاستجابة يمر حوالي 5 ثوانٍ، اتصل بنا.
س: كيف أجعل مكبّر الصوت الذي يتم تفعيله بالصوت يستجيب بشكل صحيح عندما يكون غير متصل بالإنترنت؟
ج: يتيح لك هذا الخيار عرض حالة عدم الاتصال بالإنترنت للأجهزة غير المتصلة بالإنترنت. نرجع الرسالة "غير متاح الآن" كتحويل النص إلى كلام لهذا الخطأ. لمزيد من المعلومات، يُرجى الاطِّلاع على الأخطاء والاستثناءات.