تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

تحديد المشاكل وحلّها

نموذج التطبيق

إذا واجهت أي مشاكل عند استخدام واجهات برمجة التطبيقات Home، يمكنك جمع السجلات لتحديد المشاكل وحلّها بشكل أكبر. يتطلّب جمع السجلّات من الجهاز الجوّال استخدام أداة Android Debug Bridge (adb). إذا كنت بحاجة إلى مساعدة من Google، اجمع السجلّات من أجهزة Android ولوحة الوصل، ثم افتح تذكرة في أداة تتبُّع المشاكل مع تضمين المعلومات والسجلّات ذات الصلة.

جمع سجلّات Android

يجب أن يكون جهازك الجوّال متصلاً بجهازك المحلي في جميع الخطوات التي تتضمّن adb.

تثبيت أداة adb

إذا لم يسبق لك إجراء ذلك، عليك إعداد Android Debug Bridge على جهازك:

ثبِّت "adb" على الكمبيوتر.
فعِّل "خيارات المطوّرين" و"تصحيح أخطاء الجهاز عبر USB" على هاتف Android.

الحصول على رقم تعريف الجهاز الجوّال

الحصول على رقم تعريف جهازك الجوّال:
```
adb devices
```
```
List of devices attached
device-id    device
```
خزِّن هذه القيمة في متغيّر باسم phoneid:
```
phoneid=device-id
```

معلومات الإصدار

ننصحك بجمع كل معلومات الإصدار ذات الصلة بعملية الإعداد كلما قررت جمع السجلات. هذا الإجراء مطلوب إذا كنت بحاجة إلى مشاركة المشاكل مع Google.

احفظ معلومات الجهاز المختلفة في متغيرات:

containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep -m 1 "versionName" || true); ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep -m 1 "versionName" || true); androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true); androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true); chimeradump=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider || true); homemoduleinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.home" || true); optionalhomemoduleinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.optional_home" || true); threadinfo=$(echo "$chimeradump" | grep -w "com.google.android.gms.threadnetwork" || true); enabledfeatures=$(echo "$chimeradump" | grep "Enabled features" | grep -i "home" | sort -u || true)

احفظ جميع المتغيرات في ملف باسم _versions.txt:

توسيع لعرض أوامر حفظ المتغيرات في ملف

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

versionfile="_versions.txt"
echo "Saving version info to $versionfile"
echo "Container version: $containerinfo" > $versionfile
echo "Home Module version: $homemoduleinfo" >> $versionfile
echo "Optional Home Module version: $optionalhomemoduleinfo" >> $versionfile
echo "Thread Module version: $threadinfo" >> $versionfile
echo "GHA version: $ghainfo" >> $versionfile
echo "Android version: $androidversion" >> $versionfile
echo "Android API version: $androidapiversion" >> $versionfile
echo "Found enabled features: $enabledfeatures" >> $versionfile

تحقَّق من محتوى _versions.txt:

cat _versions.txt

توسيع القسم لعرض ناتج الملف النموذجي

Container version:     versionName=26.26.34 (190400-945364269)
Home Module version:             com.google.android.gms.home [v262634001]
Optional Home Module version:         com.google.android.gms.optional_home [262634025] ...
Thread Module version:             com.google.android.gms.threadnetwork [v262634001]
GHA version:     versionName=4.22.28.0
Android version: 14
Android API version: 34
Found enabled features:             Enabled features: appsearch_impl, brella_dynamite, dck_management...

يمكن الآن تقديم هذا الملف إلى Google عند الحاجة لتحديد المشاكل وحلّها.

تفعيل علامات تصحيح الأخطاء المطوَّلة

قبل جمع سجلات أجهزة Android أو تشغيل تقرير عن الخطأ، اضبط حجم ذاكرة التخزين المؤقت للمسجّل وفعِّل علامات تصحيح الأخطاء التفصيلية لمكوّنات Google Home وخدمات Google للأجهزة الجوّالة:

# Clear existing device logs and expand logger buffer size
adb -s $phoneid logcat -b all -c
adb -s $phoneid logcat -G 8M

# Enable GMS Service ID verbose flags
adb -s $phoneid shell setprop log.tag.gms_svc_id:168 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:304 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:305 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:319 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:336 VERBOSE
adb -s $phoneid shell setprop log.tag.gms_svc_id:360 VERBOSE

# Enable GHP and Matter log tags
adb -s $phoneid shell setprop log.tag.CameraCommissioningPlugin VERBOSE
adb -s $phoneid shell setprop log.tag.HomeSdk VERBOSE
adb -s $phoneid shell setprop log.tag.HomeClient VERBOSE
adb -s $phoneid shell setprop log.tag.InteractionApiChimeraService VERBOSE
adb -s $phoneid shell setprop log.tag.MatterCommissioner VERBOSE
adb -s $phoneid shell setprop log.tag.SampleApp VERBOSE

جمع سجلّات Android باستخدام النصوص البرمجية

لالتقاط سجلّات جهاز Android المباشرة أثناء جلسة تصحيح الأخطاء، اتّبِع الخطوات التالية:

اتّبِع التعليمات الواردة في تفعيل علامات تصحيح الأخطاء المطوَّل لمحو السجلات الحالية وتوسيع حجم ذاكرة التخزين المؤقت وضبط علامات التسجيل المطوَّل.
أغلِق جميع التطبيقات التي تعمل على الجهاز الجوّال.
محو التشويش الحالي في مخزن سجلّ البيانات المؤقت قبل بدء الاختبار:
```
adb -s $phoneid logcat -c
```
ابدأ عملية جمع السجلات في نافذة طرفية:
```
adb -s $phoneid logcat | tee android-logs_$(date +%Y%m%d%H%M%S).txt
```
يُرجى ترك نافذة المحطة الطرفية هذه مفتوحة. سيؤدي ذلك إلى تسجيل البيانات من جهازك طوال مدة تشغيل العملية.
شغِّل تطبيقك ونفِّذ جميع إجراءات واجهة المستخدم اللازمة لإعادة إنتاج المشكلة.
بعد الانتهاء، أوقِف عملية logcat في الوحدة الطرفية بالضغط على Ctrl+C (أو Cmd+C على جهاز Mac).
يتم حفظ السجلّات من هذه الجلسة في android-logs_YYYYMMDDmmss.txt. أرفِق كلاً من android-logs_YYYYMMDDmmss.txt و_versions.txt بأي تقارير أخطاء.

جمع سجلات Android باستخدام الأمر adb bugreport

يمكنك تسجيل تقرير خطأ كامل في Android عندما تحتاج إلى مشاركة معلومات تشخيصية تفصيلية تغطي المشاكل على مستوى النظام أو عمليات تفريغ الأعطال أو تصحيح أخطاء الشبكة والبلوتوث على مستوى منخفض:

إعداد Matter عبر البلوتوث المنخفض الطاقة (BLE): عند الإبلاغ عن مشكلة في إعداد Matter عبر البلوتوث المنخفض الطاقة، فعِّل سجلّ التتبُّع لواجهة تحكّم مضيف البلوتوث في "خيارات المطوّرين" (الإعدادات > خيارات المطوّرين > تفعيل سجلّ التتبُّع لواجهة تحكّم مضيف البلوتوث) قبل إعادة إنتاج المشكلة.
إعداد الاختبار المُسبَق: قبل إجراء الاختبار، اتّبِع الخطوات الواردة في تفعيل علامات تصحيح الأخطاء التفصيلية لتفعيل خصائص تصحيح الأخطاء التفصيلية على جهازك.
تسجيل تقرير خطأ: بعد إجراء الاختبار وإعادة إنتاج المشكلة، نفِّذ الأمر التالي لإنشاء أرشيف كامل لتقرير الخطأ:
```
adb -s $phoneid bugreport ./android-bugreport_$(date +%Y%m%d%H%M%S).zip
```
معلومات تصحيح الأخطاء المتقدّمة: يحتوي ملف android-bugreport_YYYYMMDDmmss.zip الذي تم إنشاؤه على بيانات تشخيصية شاملة على مستوى النظام، بما في ذلك عمليات تفريغ النظام الكاملة وإحصاءات الذاكرة وبيانات تشخيص البطارية وعمليات تتبُّع الأنظمة الفرعية المنخفضة المستوى، ما يوفّر معلومات أكثر تقدّمًا لتصحيح الأخطاء.

سجلات جهاز مركز البث

يمكنك الاطّلاع على سجلات جهاز Google Nest Hub باستخدام هذه الطريقة المتوافقة مع الطُرز التالية:

Google Home
Google Nest Audio
Google Nest Hub
Google Nest Mini

لتفعيل مركز Cast لاسترداد السجلات المحلية، اتّبِع الخطوات التالية:

إعداد Android Debug Bridge
احصل على عنوان IP الخاص بلوحة الوصل باتّباع الخطوات التالية:
- من الجهاز الرئيسي، إذا كان مزوّدًا بشاشة:
  1. التمرير سريعًا لأسفل الشاشة من أعلاها
  2. انقر على رمز الإعدادات .
  3. ابحث عن عنوان IP للجهاز: على Nest Hub (2nd gen)، انتقِل إلى معلومات الجهاز > المعلومات الفنية > عنوان IP
- من GHA على هاتفك:
  1. انقر على الجهاز لعرض صفحة تفاصيله
  2. انقر على رمز "الإعدادات" لفتح صفحة الإعدادات
  3. ابحث عن عنوان IP للجهاز: انتقِل إلى معلومات الجهاز > المعلومات الفنية > عنوان IP
على جهاز كمبيوتر متصل بشبكة Wi-Fi نفسها التي يتصل بها الجهاز:
```
  adb connect ip-address
  adb logcat
```
لتزويد مستخدم بالسجلات، نفِّذ العملية التي يتعذّر إجراؤها، ثم أرسِل الناتج إلى ملف نصي:
```
  adb logcat -d > platform-logs.txt
```

عمليات التشغيل الآلي

رصد الحواف

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

على سبيل المثال، إذا كان تشغيل مصباح هو إجراء بدء، تتحقّق ميزة "رصد الحواف" من أنّ إجراء البدء لا يتم تنفيذه إلا إذا تغيّرت حالة جهاز المصباح من "إيقاف" إلى "تشغيل"، وليس من "تشغيل" إلى "تشغيل" (بدون تغيير).

لا تعمل ميزة التشغيل الآلي على النحو المتوقّع

بعد أخذ ميزة "رصد الحواف" في الاعتبار، إذا لم يعمل أحد أنظمة التشغيل الآلي على النحو المتوقّع، اتّبِع الخطوات التالية:

تحقَّق من كل جهاز للتأكّد من أنّه يعمل بشكل سليم بغض النظر عن عملية التشغيل الآلي.
ألقِ نظرة على الرسم البياني للتشغيل الآلي الخاص بك، وقارِنه بلغة DSL الخاصة بالتشغيل الآلي، وذلك للكشف عن أي افتراضات غير صحيحة محتملة من جانبك.
مراقبة حالة الجهاز في تطبيق Google Home أثناء تنفيذ عملية التشغيل الآلي
تأكَّد من أنّ جميع الأجهزة التي تشير إليها عملية التشغيل الآلي متوفّرة في البنية التي تتوقّع أن تكون فيها. قد يؤدي حذف جهاز تعتمد عليه عملية تشغيل آلي إلى حدوث عواقب غير مقصودة. اطّلِع على تأثير حذف الجهاز في عمليات التشغيل الآلي.

بدء عملية التشغيل الآلي في حالات غير مناسبة

إذا تم تشغيل عملية التشغيل الآلي في وقت غير مناسب، راجِع معايير البدء. قد يكون من الضروري إضافة منطق إضافي للتأكّد من تسجيل تغيير الحالة مرة واحدة فقط وتشغيل عملية التشغيل الآلي مرة واحدة فقط.

لا يتم تجميع عملية التشغيل الآلي

تأكَّد من أنّ تطبيقك يتضمّن جميع عمليات الاستيراد اللازمة، بما في ذلك كل فئة تتوافق مع أنواع العُقد المختلفة، بالإضافة إلى السمات التي تشير إليها.

تعذُّر التحقّق من صحة إنشاء عملية تشغيل آلي

إذا لم يتم اجتياز عملية إنشاء التشغيل الآلي، ستوفّر رسالة تحذير أو خطأ معلومات حول المشكلة. لمزيد من المعلومات، راجِع مرجع ValidationIssueType.

تعرض دالة القائمة استثناءات

عند استدعاء دالة القائمة في Automation API، قد تعرض معالجات القراءة استثناءات بسبب عدم توفّر ميزات واجهة برمجة التطبيقات. لحلّ هذه المشكلة، احذف عملية التشغيل الآلي المتأثرة.

ولإجراء ذلك:

تأكَّد من تثبيت adb. اطّلِع على مقالة تثبيت adb.

استرداد معرّف التشغيل الآلي من سجلّات Android عن طريق استدعاء:

adb logcat -s GhpNative

أمثلة على السجلّات:

adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse

INTERACTION RESPONSE -> SendCommandsResponse:
1 {
1: "automation@global"
3 {
  1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse"
  2:
  5 {
    1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse"
    1 {
        1: "1111-2222-3333-44444-55555" // Automation ID to delete
        2: "structure@2222-3333-4444-5555-6666"
...

إذا كان يجب حذف عدّة معرّفات أتمتة، يمكنك استخدام برنامج عرض الصفحات في سطر الأوامر للتحكّم في الإخراج:

adb logcat -s GhpNative level:debug | less

احذف عملية التشغيل الآلي باستخدام معرّفها:

structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))

تسجّل Discovery API تحذيرًا عند إلغاء تسجيل سمة

إذا سجّلت Discovery API تحذيرًا بشأن Trait not found، يعني ذلك أنّ واجهة برمجة التطبيقات تحاول استخدام السمة للمرشحين في Discovery، ولكن لن تنجح لأنّه لم يتم تسجيل السمة أثناء عملية الإعداد. على سبيل المثال:

09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582

معرّف السمة هو home.matter.6006.clusters.fc43، وهو يتوافق مع RelativeHumidityControl. لتحديد اسم السمة من رقم تعريف، اطّلِع على فهرس السمات.

من هذا المثال، يجب تسجيل RelativeHumidityControl أثناء تهيئة التطبيق. راجِع تسجيل السمات لإضافة السمة إلى قاعدة بيانات المسجّلين.

OAuth

إذا كان لديك عميل OAuth حالي

إذا كان لديك معرّف عميل OAuth تم إثبات ملكيته لتطبيق منشور، يمكنك استخدام معرّف عميل OAuth الحالي لاختبار واجهات برمجة التطبيقات الخاصة بمنصة Home.

لا يلزم التسجيل في Google Home Developer Console لاختبار واجهات برمجة التطبيقات الخاصة بالمنزل واستخدامها. ومع ذلك، سيظلّ عليك الحصول على تسجيل Developer Console معتمَد لنشر تطبيقك، حتى إذا كان لديك عميل OAuth تم التحقّق منه من عملية دمج أخرى.

تنطبق الاعتبارات التالية:

يتم فرض حد أقصى يبلغ 100 مستخدم عند استخدام عميل OAuth حالي. للحصول على معلومات حول إضافة مستخدمين تجريبيين، يُرجى الرجوع إلى إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth بغض النظر عن عملية التحقّق من OAuth، تفرض واجهات برمجة تطبيقات Home حدًا أقصى يبلغ 100 مستخدم يمكنهم منح الأذونات لتطبيقك. ويتم رفع هذا القيد عند إكمال عملية التسجيل في Developer Console.
يجب إرسال طلبDeveloper Console للحصول على الموافقة عندما تكون مستعدًا لحظر منح أذونات حسب نوع الجهاز من خلال OAuth استعدادًا لتعديل تطبيقك باستخدام واجهات برمجة تطبيقات Home.

ملاحظة مهمة: لا تتوفّر Google Home Developer Console للتسجيل بعد.

بالنسبة إلى تطبيقات Google Cloud التي لا تزال في انتظار إكمال عملية التحقّق من OAuth، لن يتمكّن المستخدمون من إكمال عملية OAuth إلى أن تكتمل عملية التحقّق. ستتعذّر محاولات منح الأذونات وسيظهر الخطأ التالي:

Access blocked: <Project Name> has not completed the Google verification process.