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

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

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

لإنشاء التطبيق وتثبيته واختباره، عليك استيفاء بعض المتطلبات الأساسية:

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

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

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

    ثبِّت adb.

    ويمكن إجراء ذلك باستخدام SDK Manager.

ولاختبار واجهات برمجة التطبيقات Home API، ستحتاج إلى ما يلي:

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

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

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

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

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

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

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

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

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

لتنزيل حزمة تطوير البرامج (SDK) الخاصة بواجهات Home API لنظام التشغيل Android، يجب أولاً تسجيل الدخول إلى Google Home Developers.

سجِّل الدخول الآن.

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

  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... قائمة "إعادة التصميم" > "إعادة التسمية"
    5. أدخِل الاسم الجديد وانقر على إعادة هيكلة.
    6. عدِّل ملف build.gradle.kts، وغيِّر android namespace وapplicationId إلى اسم الحزمة الجديد.

  5. اضبط نطاق OAuth في HomeModule.kt. يستخدم الرمز المصدر لنموذج التطبيق تلقائيًا النطاق https://www.googleapis.com/auth/home.platform.v2. تتوفّر العديد من الميزات في "نموذج التطبيق" من خلال نطاق home.platform.v2 وتتطلّب موافقة الشريك للوصول إليها. لتشغيل نموذج التطبيق باستخدام نطاق https://www.googleapis.com/auth/home.platform.selected.devices العادي، افتح HomeModule.kt وغيِّر homePlatformScope في HomeConfig إلى HOME_PLATFORM_SCOPE_VERSION_1:

    val homeConfig = HomeConfig(
  coroutineContext = Dispatchers.IO,
  factoryRegistryProvider = {
    FactoryConstants.factoryRegistryAllTraitsAllTypes
  },
  homePlatformScope =
    HomeConfig.HomePlatformScope.HOME_PLATFORM_SCOPE_VERSION_1
)

يمكنك أيضًا تعديل homePlatformScope إلى HOME_PLATFORM_SCOPE_VERSION_1 في switchAccount() في HomeClientProvider.kt. بخلاف ذلك، يؤدي النقر على رمز الملف الشخصي لتبديل الحسابات إلى إعادة التطبيق إلى HOME_PLATFORM_SCOPE_VERSION_2.

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

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

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

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

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

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

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

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

  1. في وحدة تحكّم Google Cloud، انتقِل إلى لوحة بيانات أداة اختيار المشاريع واختَر المشروع الذي تريد استخدامه لإنشاء بيانات اعتماد 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.