تطبيق Home APIs التجريبي على Android

يعرض التطبيق النموذجي الإمكانات الأساسية لواجهات برمجة التطبيقات Google Home على Android.

المتطلبات الأساسية

لتصميم التطبيق وتثبيته واختباره، يجب استيفاء بعض المتطلبات الأساسية:

  • Android Studio، الإصدار 2024.2.1 ("Ladybug") أو الإصدارات الأحدث. يُرجى العِلم أنّ الإصدارات الأقدم من هذا الإصدار قد لا تعمل بشكلٍ صحيح مع حزمة تطوير البرامج (SDK) لواجهات برمجة التطبيقات Home.

    تنزيل "استوديو Android"

  • أداة تصحيح الأخطاء في Android‏ (adb)

    تثبيت adb.

    يمكن إجراء ذلك باستخدام مدير حزمة تطوير البرامج (SDK).

لاختبار واجهات برمجة التطبيقات Home، يجب أن يتوفّر ما يلي:

  • جهاز Android يعمل بالإصدار Android 10 أو الإصدارات الأحدث تم إعداده باستخدام حساب Google تنوي استخدامه للتطوير يُرجى التأكّد من تثبيت إصدار حديث من Android Studio وتسجيل الدخول إليه باستخدام حساب المطوّر هذا.
  • شبكة Wi-Fi
  • للوصول إلى أجهزة Matter والتحكّم فيها، تحتاج أيضًا إلى مركز Google متوافق مع واجهات برمجة التطبيقات Home. يُرجى الاطّلاع على مقالة الاتصال على Android لمزيد من التفاصيل.

  • جهاز واحد على الأقل متوافق في المنزل إذا كان هذا الجهاز (أو أي جهاز آخر تريد اختباره) يستخدم Thread، يجب أن يكون المركز أيضًا جهاز توجيه حدود Thread. تتوافق حزمة تطوير البرامج (SDK) للتطبيق النموذجي على Android مع أنواع الأجهزة والسمات التالية:

    • إضاءة درجة حرارة الألوان (تشغيل وإيقاف، سطوع)
    • مستشعر التلامس (الحالة المنطقية)
    • مصباح قابل للتعتيم (تشغيل وإيقاف، سطوع)
    • مصباح الألوان الموسَّعة (تشغيل وإيقاف، سطوع)
    • مفتاح عام
    • كاميرا Google
    • مستشعر إشغال المنزل (استشعار إشغال المنزل)
    • مصباح التشغيل/الإيقاف (تشغيل وإيقاف، سطوع)
    • مفتاح تشغيل/إيقاف المصباح
    • وحدة التشغيل/الإيقاف الإضافية (تشغيل وإيقاف)
    • مستشعر التشغيل/الإيقاف

تنزيل رمز المصدر

يتوفّر رمز المصدر للتطبيق النموذجي على GitHub.

انتقِل إلى المكان الذي تريد حفظ المشروع فيه، ثم استنسِخه:

git clone https://github.com/google-home/google-home-api-sample-app-android.git

إعداد حزمة تطوير البرامج (SDK)

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

لتنزيل حزمة تطوير البرامج (SDK) لواجهات برمجة التطبيقات Home على Android، يجب أولاً تسجيل الدخول إلى المطوّرين في Google Home.

تسجيل الدخول الآن

إنشاء التطبيق

  1. افتح Android Studio، ثم افتح مجلد مشروع google-home-api-sample-app-android الذي تم استنساخه على جهازك المحلي.

  2. أثناء الإعداد الأولي، قد يستغرق Android Studio ما يصل إلى 10 دقائق لتنزيل جميع تبعيات المشروع وإكمال إصدار Gradle.

  3. وصِّل جهاز الكمبيوتر بهاتف Android فعلي باستخدام كابل USB و فعِّل تصحيح أخطاء ADB في خيارات المطوّرين. تأكَّد من أنّ Android Studio يمكنه الاتصال بهاتف Android من خلال ADB.

  4. غيِّر اسم حزمة التطبيق النموذجي إلى اسم جديد لم يسبق تسجيله، مثل اسم يستند إلى اسم مؤسستك:

    1. افتح المشروع.
    2. وسِّع التسلسل الهرمي للمصدر.
    3. اختَر جزء الحزمة الذي تريد تغييره، أي com.example.
    4. انقر بزر الماوس الأيمن على الحزمة واختَر إعادة البنية > إعادة التسمية... Refactor > Rename menu
    5. أدخِل الاسم الجديد وانقر على إعادة البنية.
    6. عدِّل ملف build.gradle.kts، وغيِّر android namespace وapplicationId إلى اسم الحزمة الجديد.

  5. بعد تنزيل جميع المكتبات المطلوبة واكتمال مزامنة Gradle، انقر على الزر تشغيل لإنشاء التطبيق وتشغيله. عندما يعمل التطبيق بنجاح على هاتفك، ستظهر لك الصفحة الرئيسية للتطبيق النموذجي.

إنشاء شهادة توقيع

عند تشغيل تطبيق أو تصحيح أخطائه في Android Studio، يتم تلقائيًا إنشاء شهادة تصحيح أخطاء مخصّصة للتطوير وتصحيح الأخطاء. يُرجى الاطّلاع على مقالة استوديو Android: توقيع إصدار تصحيح الأخطاء للحصول على شرح كامل.

  1. أنشِئ شهادة توقيع لتطبيق تصحيح الأخطاء عن طريق تشغيل التطبيق في Android Studio. عند تشغيل تطبيق أو تصحيح أخطائه في Android Studio، ينشئAndroid Studio تلقائيًا شهادة توقيع تطبيق مخصّصة للتطوير وتصحيح الأخطاء. يُرجى الاطّلاع على مقالة "استوديو Android": توقيع إصدار مخصص لتصحيح الأخطاء للحصول على شرح كامل.

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

    للحصول على تعليمات أكثر تفصيلاً، يُرجى الاطّلاع على مقالة تشغيل التطبيقات على جهاز مادي على الموقع الإلكتروني لمطوّري تطبيقات Android.

    أوقِف الآن التطبيق قيد التشغيل.

  2. احصل على الملف المرجعي SHA-1 لشهادة تصحيح الأخطاء باتّباع التعليمات المفصّلة في إدارة عملاء OAuth / أنواع التطبيقات / التطبيقات الأصلية / Android على موقع مساعدة Google Cloud Console الإلكتروني.

  1. في Google Cloud Console، انتقِل إلى لوحة بيانات أداة اختيار المشاريع واختَر المشروع الذي تريد استخدامه لإنشاء بيانات اعتماد OAuth.
  2. انتقِل إلى صفحة واجهات برمجة التطبيقات والخدمات ، وانقر على بيانات الاعتماد في قائمة التنقّل.

  3. إذا لم تكن قد ضبطت شاشة طلب الموافقة لمشروع Google Cloud هذا، سيظهر الزر ضبط شاشة طلب الموافقة. في هذه الحالة، اضبط شاشة طلب الموافقة باستخدام الإجراء التالي. بخلاف ذلك، انتقِل إلى القسم التالي.

    1. انقر على ضبط شاشة طلب الموافقة. تظهر صفحة شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth.
    2. اختَر داخلي أو خارجي، حسب حالة الاستخدام، ثم انقر على إنشاء. تظهر لوحة شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth.
    3. أدخِل المعلومات في صفحة معلومات التطبيق وفقًا للتعليمات التي تظهر على الشاشة، ثم انقر على حفظ ومتابعة. تظهر لوحة النطاقات.
    4. لست بحاجة إلى إضافة أي نطاقات، لذا انقر على حفظ ومتابعة. تظهر لوحة المستخدمون الذين سيجرون الاختبار.
    5. انقر على الجمهور ، ثم انقر على الزر + إضافة مستخدمين.
    6. أدخِل عنوان البريد الإلكتروني للمستخدم الاختباري وانقر على الزر حفظ.
    7. انقر على حفظ ومتابعة. تظهر لوحة الملخّص.
    8. راجِع معلومات شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth، ثم انقر على الرجوع إلى لوحة البيانات.

يُرجى الاطّلاع على مقالة إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth على موقع مساعدة Google Cloud Console الإلكتروني للحصول على التفاصيل الكاملة. احرص على إضافة مستخدم واحد على الأقل سيُجري الاختبار قبل المتابعة.

إعداد بيانات اعتماد OAuth

  1. سجِّل التطبيق النموذجي لبروتوكول OAuth 2.0 وأنشِئ بيانات اعتماد OAuth باتّباع التعليمات الواردة في إعداد OAuth 2.0.
    1. حدِّد نوع التطبيق، وهو تطبيق أصلي/تطبيق Android.
    2. أضِف الملف المرجعي SHA-1 إلى عميل OAuth باتّباع التعليمات الواردة في إعداد OAuth 2.0 / التطبيقات الأصلية / Android على موقع مساعدة Google Cloud Console الإلكتروني. يجب إنشاء مفتاح SHA-1 من مفتاح "استوديو Android" التلقائي طوال عملية التطوير.

تشغيل التطبيق

  1. بعد توصيل جهازك الجوّال بجهازك المحلي، انقر على تشغيل المشروع مرة أخرى لتشغيل التطبيق النموذجي على جهازك الجوّال.

بعد التثبيت، يتوفّر التطبيق على جهازك الجوّال باسم Home API Sample App.