Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

جمع سجلّات Android

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

تثبيت أداة adb

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

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

المكوّن الإضافي Google Home في "استوديو Android"

Google Home Plugin for Android Studio هي أداة مفيدة لجمع السجلّات وتحليلها، وقد تم إنشاؤها خصيصًا لمطوّري Google Home platform. يتيح لك هذا المكوّن الإضافي الوصول إلى Google Assistant Simulator وCloud Logging وأدوات أخرى لتبسيط عملية تطوير smart home.

استخدِم هذه الأداة مع adb لتحليل سجلات جهاز Matter بشكل أكبر.

لمزيد من المعلومات والحصول على الأداة، يُرجى الاطّلاع على Google Home Plugin for Android Studio.

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

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

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

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

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

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

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

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

versionfile=$logtimestamp"_versions.txt"
echo "Saving version info to $versionfile"

echo "Container version:" >> $versionfile
echo $containerinfo >> $versionfile
echo "" >> $versionfile

echo "Home Module version:" >> $versionfile
echo $homemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Optional Home Module version:" >> $versionfile
echo $optionalhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Policy Home Module version:" >> $versionfile
echo $policyhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Thread Module version:" >> $versionfile
echo $threadinfo >> $versionfile
echo "" >> $versionfile

echo "GHA version:" >> $versionfile
echo $ghainfo >> $versionfile
echo "" >> $versionfile

echo "Android version: " >> $versionfile
echo $androidversion >> $versionfile
echo "" >> $versionfile

echo "Android API version: " >> $versionfile
echo $androidapiversion >> $versionfile
echo "" >> $versionfile

echo "Found enabled features (blank if missing):" >> $versionfile
echo $enabledfeatures >> $versionfile
echo "" >> $versionfile

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

cat _versions.txt

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

Container version:
versionName=23.19.12 (190400-530524295) versionName=22.46.17 (190408-491726958)

Home Module version:
com.google.android.gms.home [v230508900]

Optional Home Module version:


Policy Home Module version:
com.google.android.gms.policy_home [230508900] [230508900065.505615668.505615668] [Download:000003be/dl-Home.integ_230508900100400.apk] [download:/Home.integ/230508900100400:Home.integ:230508900100400]

Thread Module version:
com.google.android.gms.threadnetwork [v231912000]

GHA version:
versionName=3.2.32.1

Android version:
13

Android API version:
33

Found enabled features (blank if missing):

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

جمع السجلّات

لجمع السجلات، أغلِق جميع التطبيقات التي تعمل على الجهاز الجوّال. بعد ذلك:

افتح نافذة المحطة الطرفية وامحُ سجلّات الجهاز الحالية:
```
adb logcat -b all -c
```
ابدأ عملية جمع السجلات:
```
adb logcat >> _logs.txt
```
اترك هذه الوحدة الطرفية مفتوحة. سيؤدي ذلك إلى جمع السجلات من جهازك طالما أنّ العملية قيد التشغيل.
شغِّل التطبيق النموذجي وسجِّل جميع إجراءات واجهة المستخدم. بعد الانتهاء، أوقِف عملية logcat التي يتم تشغيلها على الوحدة الطرفية من خلال الضغط على Ctrl+C (أو Cmd+C على جهاز Mac).
يتم حفظ السجلّات من هذه الجلسة في ملف باسم _logs.txt.

يمكنك تحليل المعلومات الواردة في هذا الملف بطرق مختلفة، بما في ذلك البحث عن كلمات رئيسية مثل error أو exception أو crash.

نصوص السجلّ

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

تتوفّر هذه السجلّات في الدليل scripts في شجرة مصدر "التطبيق النموذجي". نفِّذ الخطوات التالية من دليل جذر المشروع:

الحصول على رقم تعريف جهازك الجوّال:
```
adb devices -l
```
```
List of devices attached
device-id device
```

شغِّل النص البرمجي get_logs.sh:

 ./scripts/get_logs.sh device-id

Cleared previous logs from device.
Saving version information to home_api_sample_logs_20240605233243.txt...
Saving logs to home_api_sample_logs_20240605233243.txt...
(Press CTRL+C to stop the script)

أعِد إظهار المشكلة.
اضغط على CTRL+C لإيقاف النص البرمجي.

سينشئ النص البرمجي ملف سجلّ يتضمّن طابعًا زمنيًا ويحتوي على جميع المعلومات ذات الصلة. أرفِق هذه السجلّات بأي تقارير عن الأخطاء التي تواجهها.

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

يمكنك الاطّلاع على سجلات جهاز 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 لاختبار واجهات برمجة التطبيقات الخاصة بمنصة Home واستخدامها، ولكن سيظلّ عليك الحصول على تسجيل 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.