واجهة برمجة تطبيقات الأذونات

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

دمج Permissions API

قبل المتابعة، تأكَّد من اتّباع خطوات إعداد home. يتم استخدام مثيل homeManager من تلك الخطوة في جميع أمثلة الأذونات الواردة هنا.

أولاً، سجِّل ActivityResultCaller باستخدام حزمة تطوير البرامج (SDK). على سبيل المثال، في ما يلي كيفية تعامل التطبيق النموذجي مع ذلك:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

التحقّق من الأذونات

قبل طلب الأذونات، ننصحك بالتحقّق ممّا إذا كان مستخدم التطبيق قد منح الموافقة من قبل. لإجراء ذلك، استخدِم الأسلوب hasPermissions() لمثيل Home للحصول على Flow من قيم PermissionsState:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

إذا أظهر الفحص PermissionsState من NOT_GRANTED أو PERMISSIONS_STATE_UNAVAILABLE، عليك طلب الأذونات. إذا أظهرت عملية التحقّق PermissionsState من GRANTED ولكن لم تُظهر أيّ بنية في المكالمة اللاحقة إلى structures()، يعني ذلك أنّ المستخدم ألغى إذن الوصول إلى التطبيق من خلال صفحة إعدادات Google Home app (GHA)، وعليك طلب الأذونات. بخلاف ذلك، من المفترض أن يكون لدى المستخدم إذن الوصول.

طلب الأذونات

يجب منح تطبيقك الإذن بالوصول إلى الهياكل وال devices ضمن بنية معيّنة.

إذا لم يمنح المستخدم الأذونات، استخدِم الأسلوب requestPermissions() لمثيل Home لتشغيل واجهة مستخدم "الأذونات" ومعالجة النتيجة:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

لكي يتم تشغيل واجهة مستخدم "الأذونات" بشكلٍ صحيح، يجب أن تكون قد أعددت بروتوكول OAuth لتطبيقك.

منح الأذونات

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

يجب تسجيل Developer Console لنشر تطبيق باستخدام واجهات برمجة تطبيقات Home. ليس من الضروري اختبار واجهات برمجة التطبيقات Home API واستخدامها.

إذا لم يكن التطبيق مسجَّلاً في Developer Console، ستكون حالته غير تم التحقّق منه. ننصحك بإجراء ما يلي لاختبار استخدام واجهات برمجة التطبيقات في Home:

• يمكن فقط للمستخدمين المسجَّلين كمستخدمين اختباريين في وحدة تحكّم OAuth منح الأذونات للتطبيق. ويمكن إضافة 100 مستخدم اختباري كحد أقصى لتطبيق لم يتم إثبات ملكيته.

• سيتمكّن تطبيق لم يتم إثبات ملكيته من الوصول إلى الأجهزة من أي أنواع أجهزة متوافقة مع OAuth لواجهات برمجة التطبيقات في Home (قائمة أنواع الأجهزة في Developer Console). سيتم منح جميع الأجهزة في بنية معيّنة.

إذا تم تسجيل تطبيق في Developer Console و تمت الموافقة على وصوله إلى نوع جهاز واحد أو أكثر، وتم إكمال عملية التحقّق من العلامة التجارية لبروتوكول OAuth، سيكون التطبيق في حالة تم التحقّق منه. يجب أن تكون هذه الحالة مفعّلة لإطلاق تطبيق في مرحلة التطوير:

• لم تعُد الحدود المفروضة على المستخدمين التجريبيين سارية. يمكن لأي مستخدم منح الإذن للتطبيق.
• لا يمكن للمستخدم منح الإذن إلا لأنواع الأجهزة التي تمت الموافقة عليها في Developer Console.

بعد إعداد OAuth، يؤدي طلب التطبيق إلى requestPermissions() إلى بدء مربّعات الحوار التالية:

1. سيُطلَب من المستخدم اختيار حساب Google الذي يريد استخدامه.
2. يُطلَب من المستخدم اختيار البنية التي يريد منح التطبيق إذنًا بالوصول إليها.
   1. بالنسبة إلى التطبيق الذي لم يتم إثبات ملكيته، تصبح جميع أنواع الأجهزة المتوافقة مع واجهات برمجة تطبيقات Home API متاحة للتطبيق.
   2. بالنسبة إلى التطبيق الذي تم التحقّق منه، يمكن للمستخدم منح الإذن لأنواع الأجهزة التي تمت الموافقة عليها في Developer Console فقط.
   3. بالنسبة إلى أنواع الأجهزة الحسّاسة التي يمكن للتطبيق الوصول إليها وإدارتها، يمكن للمستخدم تقييد الوصول على أساس كل جهاز. على سبيل المثال، إذا كان لدى المستخدم ثلاثة أقفال، يمكنه منح إذن الوصول إلى قفل واحد فقط من هذه الأقفال.

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

تغيير الأذونات

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

ويمكن تنفيذ ذلك من خلال استدعاء requestPermissions() مرة أخرى مع ضبط العلامة forceLaunch على true:

homeManager.requestPermissions(forceLaunch=true)

إبطال الأذونات

يمكن للمستخدمين إلغاء الإذن الذي منحته لهم سابقًا:

1. من خلال صفحة"حساباتي " في Google > البيانات والخصوصية > التطبيقات والخدمات التابعة لجهات خارجية. سيؤدي ذلك إلى إبطال رمز OAuth المميّز الذي تم إصداره عند منح الموافقة الأولية، وإبطال إمكانية الوصول إلى أي مثيل من التطبيق كان يستخدمه المستخدم على جميع مساحات العرض (الهواتف) والهياكل.

2. من خلال صفحة GHA > الإعدادات > التطبيقات المرتبطة سيؤدي النقر على settings في GHA إلى نقلك إلى صفحة الإعدادات. من هناك، انقر على مربّع التطبيقات المرتبطة الذي بدوره ينقلك إلى صفحة تشبه شاشة الموافقة. من هذه الصفحة، يمكن للمستخدم إزالة إمكانية الوصول إلى التطبيق. ويمكن للمستخدم استخدام هذه الصفحة نفسها لتغيير أنواع الأجهزة أو الأجهزة الحساسة المحددة التي يمكن للتطبيق الوصول إليها.

3. من خلال صفحة "التطبيقات المرتبطة" على الويب مباشرةً

أذونات OkGoogle

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