إعداد المنزل على Android

قبل استخدام أي من واجهات برمجة التطبيقات Home لنظام التشغيل Android، يجب تهيئة المنزل في تطبيقك. في هذه الخطوة، ستنشئ مثيلاً مفرداً من Home للسياق المحلي.

يجب أن يكون مثيل واحد فقط من Home نشطًا في كل مرة.

هذه هي نقطة الدخول إلى واجهات برمجة تطبيقات Home، وتشمل أيضًا تحديد السمات وأنواع الأجهزة التي تنوي استخدامها مع واجهات برمجة تطبيقات Device & Structure وAutomation. إذا كنت مبتدئًا في استخدام منظومة Google Home المتكاملة ولا تعرف السمات أو أنواع الأجهزة التي يجب تسجيلها، قدّمنا بعضًا من السمات وأنواع الأجهزة الأكثر شيوعًا في هذا الدليل.

إنشاء مثيل Home

للبدء، استورِد هذه الحِزم إلى تطبيقك:

import android.content.Context
import com.google.home.FactoryRegistry
import com.google.home.HomeConfig
import com.google.home.Home

لإعداد واجهات Home API، اتّبِع الخطوات التالية:

1. الحصول على مرجع إلى سياق Application لا يعتمد سياق التطبيق هذا على أي دورة حياة للنشاط، وسيظل نشطًا طالما أنّ تطبيقك نشط. يمكنك الحصول عليه من خلال الاتصال بالرقم getApplicationContext() خلال Activity أو Service:

   val context = getApplicationContext()
   

2. أنشئ مثيلاً FactoryRegistry يتضمّن جميع السمات وأنواع الأجهزة التي تنوي استخدامها في تطبيقك.

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

   val registry = FactoryRegistry(
     traits = listOf(
               AirQuality,
               AreaAttendanceState,
               AreaPresenceState,
               AssistantBroadcast,
               AssistantFulfillment,
               BooleanState,
               ColorControl,
               ExtendedColorControl,
               FlowMeasurement,
               IlluminanceMeasurement,
               LevelControl,
               Notification,
               OccupancySensing,
               OnOff,
               RelativeHumidityMeasurement,
               Switch,
               TemperatureMeasurement,
               Thermostat),
     types = listOf(
               AirQualitySensorDevice,
               ColorDimmerSwitchDevice,
               ColorTemperatureLightDevice,
               ContactSensorDevice,
               DimmableLightDevice,
               DimmablePlugInUnitDevice,
               DimmerSwitchDevice,
               ExtendedColorLightDevice,
               FlowSensorDevice,
               GenericSwitchDevice,
               HumiditySensorDevice,
               LightSensorDevice,
               OccupancySensorDevice,
               OnOffLightDevice,
               OnOffLightSwitchDevice,
               OnOffPluginUnitDevice,
               OnOffSensorDevice,
               SpeakerDevice,
               TemperatureSensorDevice,
               ThermostatDevice))
   

   يجب توفير عبارات الاستيراد لكل سمة فردية ونوع جهاز مسجّلين هنا (يجب أن يطلب منك Android Studio إضافة هذه العبارات).

3. أنشئ مثيلاً من HomeConfig باستخدام سياق الروتين الفرعي Dispatchers.IO ومثيل التسجيل.

   val homeConfig = HomeConfig(
           coroutineContext = Dispatchers.IO,
           factoryRegistry = registry)
   

4. أخيرًا، أنشئ مثيلاً singleton من Home، وهو نقطة الدخول إلى واجهات برمجة التطبيقات، باستخدام السياق وHomeConfig.

   val homeManager: HomeClient = Home.getClient(context, homeConfig)
   

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

على سبيل المثال، يتبع التطبيق النموذجي الطريقة التالية:

internal object HomeClientModule {
  @Provides
  @Singleton
  fun provideHomeClient(@ApplicationContext context: Context): HomeClient {
    return Home.getClient(
      context,
      HomeConfig(
        coroutineContext = IODispatcherModule.provideIoDispatcher(),
        factoryRegistry = registry,
      ),
    )
  }
}

تسجيل الدخول باستخدام حساب Google من خلال التطبيق

قد تحتاج إلى إدارة عمليات المصادقة التي يجريها المستخدم على Google داخل تطبيقك، ما يتيح لك استخدام حساب المستخدم نفسه على مختلف خدمات Google، مثل Google Home وDrive و"خرائط Google" وما إلى ذلك.

باستخدام ميزة "تسجيل الدخول إلى Google من خلال التطبيق"، يمكنك الحصول على مثيل HomeClient مرتبط بشكل صريح بمستخدم معيّن، وبالتالي تجاوز أداة اختيار حساب Google وشاشة الموافقة عندما يكون الحساب معتمدًا.

بالإضافة إلى ذلك، يمنع هذا الأسلوب المستخدمين من رؤية شاشتَي اختيار حساب مختلفتَين، إحداهما من عملية تسجيل الدخول إلى التطبيق والأخرى من Google Home.

لإجراء ذلك، اتّبِع الخطوات نفسها الموضّحة في إنشاء مثيل Home، ولكن بدلاً من استدعاء Home.getClient(context, homeConfig) في الخطوة 4، استدعِ Home.getClient(context, userAccount, homeConfig)، حيث تكون المَعلمة الثانية Lazy<UserAccount>. تعرض هذه الطريقة مثيلاً من HomeClientWithProvidedAccount، وهو فئة فرعية من HomeClient، ويكون مرتبطًا بشكل صريح بحساب Google المحدّد:

val client =
     Home.getClient(
       context = context.applicationContext,
       account =
         lazy {
         // 1. Create the Account object.
           val androidAccount = Account(userEmail,
                                        GoogleAuthUtil.GOOGLE_ACCOUNT_TYPE)
         // 2. Wrap it in UserAccount.GoogleAccount.
           UserAccount.GoogleAccount(androidAccount)
         },
       homeConfig = HomeConfig()
     )

إذا لم يكن المستخدم المحدّد مخوّلاً، اطلب منه الحصول على الإذن من خلال استدعاء الطرق التالية في مثيل HomeClientWithProvidedAccount:

1. registerActivityResultCallerForPermissions() مع الإشارة إلى ActivityResultCaller الذي تريد استخدامه.
2. requestPermissions(). سيؤدي ذلك إلى فتح شاشة الموافقة على "منصة Google للتسويق"، حيث يمكن للمستخدم منح الإذن.

يمكنك إنشاء HomeClient باستخدام UserAccount ثم استدعاء requestPermissions() باستخدام forceLaunch==true لإعادة عرض شاشة الموافقة ليتمكّن المستخدم من تعديل الأذونات التي منحها:

val client =
     Home.getClient(
       context = context.applicationContext,
       account =
         lazy {
              UserAccount.GoogleAccount(androidAccount)
         },
       homeConfig = HomeConfig()
     )

client.registerActivityResultCallerForPermissions(this)
client.requestPermissions(forceLaunch= true)

لمزيد من المعلومات حول إدارة أذونات واجهات برمجة التطبيقات الخاصة بمنزل Google، يُرجى الاطّلاع على Permissions API.

تسجيل السمات وأنواع الأجهزة

تساعد الفئة FactoryRegistry المطوّرين في تحسين حجم الرمز الثنائي لتطبيقاتهم من خلال السماح لهم بتحديد السمات وأنواع الأجهزة التي يستخدمها تطبيقهم بشكل صريح.

يُرجى العِلم أنّ الأذونات وسجلّ المصنع منفصلان. وبالتالي، لا يمكن الوصول إلى السمات والأنواع غير المسجّلة والمتاحة لتطبيقك باستخدام الأذونات ولكن غير المضمّنة في سجلّ المصنع باستخدام Automation API، كما لا يتم عرضها في طلبات الطريقتَين المجمّعة traits() أو types().