واجهة Permissions API على Android

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

يتيح مسار الأذونات للمستخدم إنشاء بنية وتعيين عنوان الشارع الخاص بها إذا لم يتم إعداده مسبقًا، بدون الحاجة إلى استخدام Google Home app (GHA).

دمج واجهة Permissions API

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

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

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

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

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

val permissionsReadyState =
homeManager.hasPermissions().collect { state ->
    when (state) {
      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")

      PermissionsState.PERMISSIONS_STATE_UNINITIALIZED -> println(
          "Permissions state is not initialized yet. Clients should wait for another status update"
      )
      else ->
          throw IllegalStateException("""
            HomeClient.hasPermissions state should be PermissionsState.GRANTED,
            PermissionState.PERMISSIONS_STATE_UNINITIALIZED, or
            PermissionsState.PERMISSIONS_STATE_UNAVAILABLE. Actual state: $state
          """.trimIndent())
    }
}

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

طلب الحصول على الأذونات

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

إذا لم يمنح المستخدم الأذونات من قبل، استخدِم طريقة 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 لتطبيقك.

يتم عرض واجهة مستخدم الموافقة على الأذونات باللغة التي تم ضبطها باستخدام HomeClient.setLocale()، أو يتم ضبطها تلقائيًا على لغة التطبيق أو الجهاز في حال عدم ضبطها. لعرض شاشة طلب الموافقة بلغة معيّنة، يمكنك استدعاء setLocale() في مثيل HomeClient قبل استدعاء requestPermissions(). لمزيد من المعلومات، يُرجى الاطّلاع على مقالة ضبط لغة التطبيق.

منح الأذونات

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

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

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

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

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

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

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

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

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

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

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

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

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

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

تغيير الأذونات باستخدام ميزة "التلميح إلى البنية"

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

تتم إدارة ميزة "التلميح إلى البنية" باستخدام فئة البيانات ConsentScreenOptions. تقبل الفئة ConsentScreenOptions مَعلمات الضبط التالية:

• ‫structureId: رقم تعريف البنية المحدّد الذي سيتم اختياره مسبقًا في مربّع حوار الإذن يمكنك الحصول على هذه القيمة من خلال الاطّلاع على سمات البنية للبنية التي يتم تعديلها.
• ‫allowedStructureIds: قائمة بأرقام تعريف البُنى في حال توفّر هذه القائمة، سيعرض مربّع حوار الأذونات البُنى المتاحة فيها فقط. يمكن ترك هذه السمة بدون تحديد في معظم الحالات، إلا إذا أردت التأكّد من أنّ المستخدم يظل ضمن قائمة البُنى التي تم منحها مسبقًا.
• ‫allowStructureChange: يحدّد ما إذا كان يُسمح للمستخدم بتغيير البنية المحدّدة مسبقًا. اضبط هذه السمة على true إذا تم تحديد سمة واحدة على الأقل من allowedStructureIds وstructureId في معظم الحالات لإتاحة السلوك الطبيعي للمستخدم.

مرِّر هذا العنصر كمَعلمة اختيارية في طلب requestPermissions()، مع ضبط forcePermissionFlow على ForcePermissionFlow.FORCE_LAUNCH:

import com.google.home.ConsentScreenOptions

// Create the ConsentScreenOptions class, allowing structure changes while
// ensuring the permissions dialog pre-selects the target structure on launch
val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowStructureChange = true
)

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH, consentScreenOptions = consentOptions)

ستظهر للمستخدم شاشة طلب الموافقة التي تمت فلترتها مسبقًا وفقًا للبنية المحدّدة في عنصر ConsentScreenOptions.

السماح للمستخدم بتبديل البُنى باستخدام ميزة "التلميح إلى البنية"

إذا كان لدى المستخدم عدة هياكل في تطبيق وأردت اختيار أحدها مسبقًا مع السماح له بالتبديل بين الهياكل المتاحة، يمكنك تفعيل تغييرات الهياكل باستخدام العلامة allowStructureChange وتقديم قائمة بالهياكل في allowedStructureIds:

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

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

يمكن للمستخدمين إبطال أذونات الوصول التي سبق لهم منحها:

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

   قد يتم توجيه المستخدم من خلال رابط لصفحة في التطبيق إلى الصفحة الفرعية التطبيقات والخدمات التابعة لجهات خارجية باستخدام مخطّط عنوان URL التالي:

   https://myaccount.google.com/connections/link?project_number=Cloud project_number
   

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

حذف بيانات المستخدمين وتصديرها

تدير المنصة تلقائيًا حذف البيانات في الخلفية عندما يحذف المستخدم حسابه على Google أو يغادر بنية:

• إذا كان المستخدم المحذوف هو المالك الوحيد للمنزل، ستحذف المنصة المنزل والأجهزة المرتبطة به.
• إذا بقي مالكون آخرون في منزل مشترَك، سيظل المنزل وأجهزته المشترَكة متاحَين للأعضاء المتبقّين. تزيل المنصة عضوية المستخدم المغادر وتلغي ربط أي أجهزة تابعة لجهات خارجية Cloud-to-cloud متصلة فقط من خلال بيانات اعتماد هذا المستخدم.
• يؤدي حذف الحساب إلى إزالة بيانات البنية وأذونات التطبيق الخاصة بالمستخدم فورًا وبشكل نهائي. حتى إذا استعاد المستخدم حسابه على Google لاحقًا، لن تتم استعادة بنياته وأذوناته.

لا توفّر واجهات برمجة تطبيقات Home نقاط نهاية لتصدير بيانات حساب Google الخاص بالمستخدم أو حذفها. وجِّه المستخدمين الذين لديهم حساب على Google إلى Google Takeout لتصدير بيانات Google Home وإلى إعدادات حساب Google لإدارة حذف الحساب.

عرض أنواع الأجهزة التي منح المستخدم أذونات لها

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

لتحديد ما إذا كان المستخدم قد منح الإذن بالوصول إلى نوع جهاز حسّاس أو مقيّد، استخدِم دالة consentedDeviceTypes() على مستوى البنية:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

أذونات OkGoogle

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

إرشادات في حال ألغى المستخدم الأذونات الكاملة

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

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

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