API مجوزها

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

Permissions API را یکپارچه کنید

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

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

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

مجوزها را بررسی کنید

قبل از درخواست مجوز، توصیه می‌کنیم بررسی کنید که آیا کاربر برنامه قبلاً رضایت داده است یا خیر. برای انجام این کار، متد hasPermissions() نمونه Home را فراخوانی کنید تا یک Flow of 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 of GRANTED را برگرداند اما یک فراخوان بعدی به structures() هیچ ساختاری را برگرداند، در این صورت کاربر از طریق صفحه تنظیمات Google Home app (GHA) دسترسی به برنامه را لغو کرده است و شما باید مجوزها را درخواست کنید. در غیر این صورت، کاربر از قبل باید دسترسی داشته باشد.

درخواست مجوزها

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

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

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 API ضروری است. آزمایش و استفاده از APIهای Home الزامی نیست.

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

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

• یک برنامه تأیید نشده به دستگاه‌هایی با هر نوع دستگاهی که توسط OAuth برای APIهای Home پشتیبانی می‌شوند (فهرست انواع دستگاه‌ها در Developer Console ) دسترسی خواهد داشت. تمام دستگاه ها در یک ساختار اعطا خواهند شد.

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

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

اکنون که OAuth راه اندازی شده است، فراخوانی برنامه به requestPermissions() دیالوگ های زیر را راه اندازی می کند:

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

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

تغییر مجوزها

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

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

homeManager.requestPermissions(forceLaunch=true)

لغو مجوزها

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

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

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

3. از طریق صفحه برنامه های پیوندی مستقیماً در وب.

مجوزهای OkGoogle

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