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

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

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

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

إنشاء مثيل من Home

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

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

لإعداد واجهات برمجة التطبيقات لمنزل Google:

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. أخيرًا، أنشئ المثيل الأحادي من 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.

لإجراء ذلك، عليك الرجوع إلى مصادقة المستخدمين باستخدام ميزة "تسجيل الدخول باستخدام حساب Google" وإكمال الخطوات التالية:

إنشاء معرّف عميل لتطبيق ويب يستخدم البروتوكول OAuth

1. افتح Google Cloud Console.
   • انتقِل إلى صفحة بيانات الاعتماد في Google Cloud Console.
   • اختَر مشروعًا حاليًا أو أنشئ مشروعًا جديدًا.
2. اضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth (إذا لم تفعل ذلك)
   • قبل إنشاء بيانات الاعتماد، تأكَّد من ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth باستخدام تفاصيل تطبيقك، بما في ذلك عناوين URL لسياسة الخصوصية وبنود الخدمة.
3. أنشئ معرّف عميل OAuth (نوع تطبيق الويب)
   • في صفحة "بيانات الاعتماد"، انقر على + CREATE CREDENTIALS و اختر معرّف عميل OAuth من القائمة المنسدلة.
   • في حقل نوع التطبيق، اختَر تطبيق الويب.
   • أدخِل اسمًا لعميل الويب (مثل "الواجهة الخلفية لتطبيق الويب").
   • انقر على "إنشاء".
4. استرداد معرّف العميل
   • بعد الإنشاء، ستعرض وحدة التحكّم معرّف العميل الجديد. هذه هي القيمة التي ستستخدمها في تطبيق Android (مثل "{project number}-.....apps.googleusercontent.com")
   • ننصحك بتخزين معرّف العميل خارجيًا (مثل build.gradle) بدلاً من ترميزه مباشرةً.

إنشاء طلب تسجيل الدخول باستخدام حساب Google

استخدِم معرّف تطبيق الويب لإنشاء طلب "تسجيل الدخول بحساب Google":

// Your Google Cloud console Web Client ID for Google Sign-In
val serverClientId = BuildConfig.DEFAULT_WEB_CLIENT_ID

// Build the request for Google ID token
val googleIdOption = GetGoogleIdOption.Builder()
    .setFilterByAuthorizedAccounts(false) // Show all Google Accounts on the device
    .setServerClientId(serverClientId) // embed WebClientID in token
    .build()

// Build the GetCredentialRequest
val request = GetCredentialRequest.Builder().addCredentialOption(googleIdOption).build()

إنشاء مسار "تسجيل الدخول باستخدام حساب Google"

لتنفيذ مسار تسجيل الدخول، استخدِم CredentialManager لتنفيذ طلب Sign in with Google. بعد أن يختار المستخدم حسابًا، استخرِج عنوان بريده الإلكتروني من رمز تعريف Google الناتج لإنشاء android.accounts.Account. يُستخدَم هذا الحساب بعد ذلك لتهيئة مثيل من HomeClient مرتبط بشكلٍ خاص بالمستخدم الذي سجّل الدخول.

  try {
    // CredentialManager is responsible for interacting with various credential providers on the device
    val credentialManager = CredentialManager.create(context)
    // Credential returns when user has selected an account and the getCredential call completes
    val result = credentialManager.getCredential(context = context, request = request)
    val credential = result.credential

    if (
      credential is CustomCredential &&
      credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL
    ) {
      try {
        val googleCredential = GoogleIdTokenCredential.createFrom(credential.data)
        googleCredential.id.let { userEmail ->
          Log.i(TAG, "Email found in Google ID Token: $email")
          /*
           Why "com.google"?
           The string "com.google" is a standard identifier used in Android's android.accounts.
           Account system to represent accounts managed by Google. This is often used when
           interacting with Android's Account Manager or when using Google-specific APIs. So,
           even if the email ends in "@gmail.com", the underlying account type or provider is
           still considered "com.google" within the Android system.
          */
          val account = Account(userEmail, "com.google")
          Log.d(TAG,"Switched account to : $userEmail")
          // Get the new Home Client Instance with the userEmail
        }
        Log.i(TAG, "Account switch complete. Emitting navigation event.")
      } catch (e: Exception) {
        Log.e(TAG,"Could not convert CustomCredential to Google ID Token", e)
      }
    }
  } catch (e: Exception) {
    Log.e(TAG, "Google Sign-In failed with unexpected error", e)
  }

الحصول على مثيل جديد من HomeClient

اتّبِع الخطوات نفسها الموضّحة في إنشاء مثيل من 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(): يؤدي هذا الإجراء إلى ظهور شاشة طلب الموافقة في GHP، حيث يمكن للمستخدم منح الإذن.

يمكنك إنشاء 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)

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

إعادة تحميل النشاط بالكامل باستخدام HomeClient الجديد

بعد الحصول على مثيل جديد من HomeClient، عليك إعادة تحميل النشاط بالكامل لإعادة الاشتراك واسترداد البِنى والأجهزة والبيانات الأخرى ذات الصلة المرتبطة بحساب المستخدم هذا.

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

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

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