Permissions API در اندروید

قبل از استفاده از هر یک از APIهای Home برای اندروید، برنامه باید مجوز دسترسی به دستگاه‌های موجود در خانه کاربر را داشته باشد که در API به آن ساختار گفته می‌شود. با استفاده از API مجوزها، کاربر می‌تواند با استفاده از حساب گوگل خود، به برنامه‌های APIهای Home اجازه دسترسی به دستگاه‌های موجود در خانه خود را بدهد.

ادغام API مجوزها

قبل از ادامه، مطمئن شوید که از دستور Initialize the home on Android پیروی کرده‌اید. نمونه homeManager از آن مرحله در تمام مثال‌های Permissions در اینجا استفاده می‌شود.

ابتدا، یک ActivityResultCaller با SDK ثبت کنید. برای مثال، نحوه مدیریت آن توسط برنامه نمونه به این صورت است:

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

بررسی مجوزها

قبل از درخواست مجوز، توصیه می‌کنیم بررسی کنید که آیا کاربر برنامه قبلاً رضایت خود را برای دسترسی به ساختار داده است یا خیر. برای انجام این کار، متد hasPermissions() از نمونه Home را فراخوانی کنید تا Flow of PermissionsState values ​​را دریافت کنید:

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 » (PermissionsState) را برابر با GRANTED برگرداند، اما فراخوانی بعدی تابع structures() هیچ ساختاری را برنگرداند، یا کاربر دسترسی به برنامه را از طریق صفحه تنظیمات Google Home app (GHA) لغو کرده است، یا کاربر دسترسی لازم را ندارد.

درخواست مجوز

برای دسترسی به ساختارها و دستگاه‌های درون یک ساختار مشخص، باید به برنامه شما مجوز داده شود.

اگر کاربر هنوز مجوزی اعطا نکرده است، از متد requestPermissions() از نمونه Home برای اجرای رابط کاربری Permissions و پردازش نتیجه استفاده کنید:

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 ثبت کرده‌اید یا خیر، متفاوت خواهد بود.

برای انتشار یک برنامه با استفاده از APIهای Home، ثبت نام Developer Console الزامی است. برای آزمایش و استفاده از APIهای Home نیازی به این کار نیست.

اگر برنامه‌ای در Developer Console ثبت نشده باشد ، در حالت تأیید نشده قرار خواهد گرفت. این حالت برای آزمایش استفاده از رابط‌های برنامه‌نویسی کاربردی خانگی (Home APIs) توصیه می‌شود:

• فقط کاربرانی که به عنوان کاربر آزمایشی در کنسول OAuth ثبت نام کرده‌اند می‌توانند مجوزهای لازم را برای برنامه اعطا کنند. برای یک برنامه تأیید نشده، محدودیت ۱۰۰ کاربر آزمایشی وجود دارد.

• یک برنامه‌ی تأیید نشده به دستگاه‌هایی از هر نوع که توسط OAuth برای رابط‌های برنامه‌نویسی کاربردی خانگی (لیست انواع دستگاه‌ها در Developer Console ) پشتیبانی می‌شوند، دسترسی خواهد داشت. به تمام دستگاه‌های موجود در یک ساختار، این دسترسی اعطا خواهد شد.

اگر برنامه‌ای در Developer Console ثبت شده باشد و برای دسترسی به یک یا چند نوع دستگاه تأیید شده باشد، و تأیید برند برای OAuth تکمیل شده باشد ، در حالت تأیید شده قرار خواهد گرفت. این حالت برای راه‌اندازی یک برنامه در محیط عملیاتی ضروری است:

• محدودیت‌های کاربر آزمایشی دیگر اعمال نمی‌شود. هر کاربری می‌تواند به برنامه مجوز بدهد.
• کاربر فقط می‌تواند به انواع دستگاه‌هایی که در Developer Console تأیید شده‌اند، مجوز بدهد.

اکنون که OAuth تنظیم شده است، فراخوانی برنامه به requestPermissions() پنجره‌های محاوره‌ای زیر را فعال می‌کند:

1. از کاربر خواسته می‌شود حساب گوگل مورد نظر خود را انتخاب کند.
2. از کاربر خواسته می‌شود ساختاری را که می‌خواهد به برنامه دسترسی بدهد، انتخاب کند.
   1. برای یک برنامه تأیید نشده، همه انواع دستگاه‌های پشتیبانی شده توسط APIهای Home برای برنامه در دسترس هستند.
   2. برای یک برنامه تأیید شده، کاربر می‌تواند فقط به انواع دستگاه‌هایی که در Developer Console تأیید شده‌اند، مجوز بدهد.
   3. برای انواع دستگاه‌های حساس که برنامه به آنها دسترسی مدیریت دارد، کاربر می‌تواند دسترسی را بر اساس هر دستگاه محدود کند. به عنوان مثال، اگر کاربری سه قفل داشته باشد، می‌تواند فقط به یکی از آن قفل‌ها دسترسی بدهد.

پس از اعطای مجوز، برنامه می‌تواند از APIهای Home برای خواندن وضعیت و کنترل دستگاه‌های موجود در ساختار استفاده کند. اگر کاربر برای یک نوع دستگاه خاص یا دستگاه حساس به برنامه اجازه ندهد، برنامه قادر به استفاده از APIهای Home برای دسترسی، کنترل یا خودکارسازی آن نخواهد بود.

تغییر مجوزها

برای اعطای مجوز دسترسی به دستگاه‌ها در ساختاری متفاوت، می‌توان انتخابگر حساب کاربری را اجرا کرد تا کاربر بتواند حساب گوگل و ساختار مورد نظر برای تغییر را انتخاب کند. در طول این فرآیند، حتی اگر قبلاً به کاربر رضایت داده شده باشد، دوباره صفحه رضایت‌نامه نمایش داده می‌شود.

این کار را می‌توان با فراخوانی مجدد requestPermissions() با تنظیم پرچم forceLaunch روی true انجام داد:

homeManager.requestPermissions(forceLaunch=true)

لغو مجوزها

کاربران می‌توانند دسترسی‌های قبلاً اعطا شده را لغو کنند:

1. از طریق صفحه حساب‌های کاربری گوگل > داده‌ها و حریم خصوصی > برنامه‌ها و سرویس‌های شخص ثالث . این کار توکن OAuth که هنگام اعطای رضایت اولیه صادر شده بود را لغو می‌کند و دسترسی به هر نمونه از برنامه‌ای را که کاربر در تمام سطوح (تلفن‌ها) و ساختارها استفاده می‌کرد، لغو می‌کند.

   کاربر می‌تواند با استفاده از طرح URL زیر، با یک لینک عمیق به زیرصفحه برنامه‌ها و سرویس‌های شخص ثالث هدایت شود:

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

2. از طریق صفحه GHA > تنظیمات > برنامه‌های مرتبط . کلیک روی settings در GHA شما را به صفحه تنظیمات می‌برد. از آنجا، روی کاشی برنامه‌های مرتبط کلیک کنید که شما را به صفحه‌ای مشابه صفحه رضایت‌نامه می‌برد. از این صفحه، کاربر می‌تواند دسترسی به برنامه را حذف کند. کاربر می‌تواند از همین صفحه برای تغییر نوع دستگاه یا دستگاه‌های حساس خاص قابل دسترسی برای برنامه استفاده کند.

مجوزهای OkGoogle

دستور okGoogle یک دستور در سطح دستگاه است و می‌تواند برای خودکارسازی هر دستگاهی در ساختار مورد استفاده قرار گیرد. با این حال، یک برنامه Home API ممکن است به هر دستگاهی دسترسی نداشته باشد. جدول زیر نحوه اعمال مجوزها در چنین مواردی را شرح می‌دهد.