Permissions API ใน Android

ก่อนใช้ Home API สำหรับ Android แอปต้องมีสิทธิ์เข้าถึงอุปกรณ์ในบ้านของผู้ใช้ ซึ่งใน API จะเรียกว่าโครงสร้าง เมื่อใช้ Permissions API ผู้ใช้จะใช้บัญชี Google เพื่อให้สิทธิ์แอป Home APIs เข้าถึงอุปกรณ์ในบ้านได้

ขั้นตอนการให้สิทธิ์ช่วยให้ผู้ใช้สร้างโครงสร้างได้หากยังไม่ได้ตั้งค่าไว้ โดยไม่ต้องใช้ Google Home app (GHA)

ผสานรวม Permissions API

ก่อนดำเนินการต่อ โปรดตรวจสอบว่าคุณได้ทำตามขั้นตอนในหัวข้อ เริ่มต้นใช้งานบ้านใน Android แล้ว อินสแตนซ์ homeManager จากขั้นตอนนั้นจะใช้ในตัวอย่างสิทธิ์ทั้งหมด ที่นี่

ก่อนอื่น ให้ลงทะเบียน ActivityResultCaller ด้วย SDK ตัวอย่างเช่น แอปตัวอย่างจะจัดการดังนี้

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

ตรวจสอบสิทธิ์

ก่อนขอสิทธิ์ เราขอแนะนำให้คุณตรวจสอบว่าผู้ใช้ ของแอปได้ให้ความยินยอมในการเข้าถึงโครงสร้างแล้วหรือไม่ โดยเรียกใช้เมธอด hasPermissions() ของอินสแตนซ์หน้าแรกเพื่อรับ 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 of GRANTED แต่การเรียกใช้ structures() ในภายหลังไม่แสดงโครงสร้าง แสดงว่าผู้ใช้ได้เพิกถอนสิทธิ์เข้าถึง แอปผ่านหน้าการตั้งค่า GHA หรือผู้ใช้ ไม่มีสิทธิ์เข้าถึงที่จำเป็น

ขอสิทธิ์

คุณต้องให้สิทธิ์แก่แอปเพื่อเข้าถึงบ้านและ อุปกรณ์ภายในบ้านที่กำหนด

หากผู้ใช้ยังไม่ได้ให้สิทธิ์ ให้ใช้เมธอด requestPermissions() ของอินสแตนซ์ Home เพื่อเปิด 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 สำหรับแอปเรียบร้อยแล้วเพื่อให้ UI ของสิทธิ์เปิดตัวได้อย่างถูกต้อง

ให้สิทธิ์

ตอนนี้คุณควรจะเรียกใช้แอปและให้ผู้ใช้ให้สิทธิ์ได้แล้ว ประเภทของผู้ใช้ที่ให้สิทธิ์ได้และประเภทอุปกรณ์ที่ใช้ได้ ในการให้สิทธิ์จะแตกต่างกันไป ขึ้นอยู่กับว่าคุณได้ ลงทะเบียนแอปใน Google Home Developer Console หรือไม่

คุณต้องลงทะเบียน Developer Console เพื่อเผยแพร่แอปโดยใช้ Home API คุณไม่จำเป็นต้องทดสอบและใช้ Home API

หากแอปไม่ได้ลงทะเบียนใน Developer Console แอปจะอยู่ในสถานะไม่ได้รับการยืนยัน เราขอแนะนําให้ใช้สิ่งต่อไปนี้เพื่อทดสอบการใช้ Home API

• เฉพาะผู้ใช้ที่ลงทะเบียนเป็นผู้ใช้ทดสอบในคอนโซล OAuth เท่านั้นที่ให้สิทธิ์ สำหรับแอปได้ โดยแอปที่ไม่ได้รับการยืนยัน จะมีผู้ใช้ทดสอบได้สูงสุด 100 ราย

• แอปที่ไม่ได้รับการยืนยันจะมีสิทธิ์เข้าถึงอุปกรณ์ประเภทใดก็ได้ที่ OAuth รองรับสำหรับ Home API (รายการประเภทอุปกรณ์ในDeveloper Console) โดยจะให้สิทธิ์แก่อุปกรณ์ทั้งหมดในโครงสร้าง

หาก แอปได้รับการลงทะเบียนใน Developer Console และ ได้รับการอนุมัติให้เข้าถึงอุปกรณ์ประเภทอย่างน้อย 1 ประเภท และการยืนยัน แบรนด์เสร็จสมบูรณ์แล้วสำหรับ OAuth แอปจะอยู่ในสถานะยืนยันแล้ว คุณต้องมีสถานะนี้จึงจะเปิดตัวแอปไปยังเวอร์ชันที่ใช้งานจริงได้

• ระบบจะไม่ใช้ขีดจำกัดของผู้ใช้ทดสอบอีกต่อไป ผู้ใช้ทุกคนสามารถให้สิทธิ์แก่ แอปได้
• ผู้ใช้จะให้สิทธิ์ได้เฉพาะกับอุปกรณ์ประเภทที่ได้รับอนุมัติใน Developer Console

เมื่อตั้งค่า OAuth แล้ว การเรียกใช้ requestPermissions() ของแอปจะทําให้เกิดกล่องโต้ตอบต่อไปนี้

1. ระบบจะแจ้งให้ผู้ใช้เลือกบัญชี Google ที่ต้องการใช้
2. ผู้ใช้จะได้รับข้อความแจ้งให้เลือกโครงสร้างที่ต้องการให้สิทธิ์แอป เข้าถึง
   1. สำหรับแอปที่ไม่ได้รับการยืนยัน แอปจะใช้ได้กับอุปกรณ์ทุกประเภทที่ API ของ Home รองรับ
   2. สำหรับแอปที่ยืนยันแล้ว ผู้ใช้จะให้สิทธิ์ได้เฉพาะประเภทอุปกรณ์ ที่ได้รับอนุมัติใน Developer Console
   3. สำหรับอุปกรณ์ประเภทที่มีความละเอียดอ่อนซึ่งแอปมีสิทธิ์เข้าถึงเพื่อจัดการ ผู้ใช้จะ จำกัดการเข้าถึงทีละอุปกรณ์ได้ ตัวอย่างเช่น หากผู้ใช้มีล็อก 3 ตัว ผู้ใช้จะให้สิทธิ์เข้าถึงได้เพียงล็อกตัวเดียวเท่านั้น

เมื่อได้รับสิทธิ์แล้ว แอปจะใช้ Home API เพื่ออ่านสถานะและควบคุมอุปกรณ์ในโครงสร้างได้ หากผู้ใช้ไม่ให้สิทธิ์ แก่แอปสำหรับอุปกรณ์ประเภทใดประเภทหนึ่งหรืออุปกรณ์ที่มีความละเอียดอ่อน แอป จะใช้ Home API เพื่อเข้าถึง ควบคุม หรือทำให้ทำงานอัตโนมัติไม่ได้

เปลี่ยนแปลงสิทธิ์

หากต้องการให้สิทธิ์เข้าถึงอุปกรณ์ในโครงสร้างอื่น คุณสามารถเปิดตัวตัวเลือกบัญชี เพื่ออนุญาตให้ผู้ใช้เลือกบัญชี Google และ โครงสร้างที่จะเปลี่ยนไปใช้ ในกระบวนการนี้ ผู้ใช้จะเห็นหน้าจอขอความยินยอมอีกครั้ง แม้ว่าจะให้ความยินยอมไปแล้วก่อนหน้านี้ก็ตาม

โดยทำได้ด้วยการเรียกใช้ requestPermissions() อีกครั้งโดยตั้งค่าแฟล็ก forceLaunch เป็น true ดังนี้

homeManager.requestPermissions(forceLaunch=true)

เพิกถอนสิทธิ์

ผู้ใช้สามารถเพิกถอนสิทธิ์เข้าถึงที่ให้ไว้ก่อนหน้านี้ได้โดยทำดังนี้

1. ผ่าน หน้าบัญชีของฉันใน Google > ข้อมูลและความเป็นส่วนตัว > แอปและบริการของบุคคลที่สาม การดำเนินการนี้จะเพิกถอนโทเค็น OAuth ที่ออกให้เมื่อได้รับความยินยอมครั้งแรก และจะเพิกถอน สิทธิ์เข้าถึงอินสแตนซ์ของแอปที่ผู้ใช้ใช้ในทุกแพลตฟอร์ม (โทรศัพท์) และโครงสร้าง

   ระบบอาจนำผู้ใช้ไปยังหน้าย่อยแอปและบริการของบุคคลที่สามด้วย Deep Link โดยใช้รูปแบบ URL ต่อไปนี้

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

2. ผ่านหน้าGHA > การตั้งค่า > แอปที่ลิงก์ การคลิก settings ใน GHA จะนำคุณไปยัง หน้าการตั้งค่า จากนั้นคลิกการ์ดแอปที่ลิงก์ ซึ่งจะนำคุณไปยังหน้าเว็บที่มีลักษณะคล้ายกับหน้าจอขอความยินยอม จากหน้านี้ ผู้ใช้สามารถนำสิทธิ์เข้าถึงแอปออกได้ และยังใช้หน้านี้เพื่อ เปลี่ยนประเภทอุปกรณ์หรืออุปกรณ์ที่มีความละเอียดอ่อนที่เฉพาะเจาะจงซึ่งแอป เข้าถึงได้ด้วย

สิทธิ์ OkGoogle

คำสั่ง okGoogle เป็นคำสั่งระดับอุปกรณ์และใช้เพื่อทำให้การทำงานของอุปกรณ์ใดก็ได้ใน โครงสร้างเป็นแบบอัตโนมัติ อย่างไรก็ตาม แอป Home APIs อาจไม่มีสิทธิ์เข้าถึงอุปกรณ์บางเครื่อง ตารางต่อไปนี้อธิบายวิธีบังคับใช้สิทธิ์ในกรณีดังกล่าว

คำแนะนำในกรณีที่ผู้ใช้เพิกถอนสิทธิ์เต็ม

หากผู้ใช้เพิกถอนสิทธิ์แบบเต็ม ระบบจะหยุดการทำงานของระบบอัตโนมัติที่มีอยู่ทั้งหมด นอกจากนี้ หากผู้ใช้เพิกถอนสิทธิ์เข้าถึงอุปกรณ์ที่เฉพาะเจาะจง เงื่อนไขเริ่มต้น เงื่อนไข และการดำเนินการที่เชื่อมโยงกับอุปกรณ์เหล่านั้นจะ หยุดทำงาน

ทุกครั้งที่แอปเริ่มทำงาน ให้ตรวจสอบว่าสิทธิ์ ยังคงมีผลอยู่ หากมีการเพิกถอนแล้ว โปรดตรวจสอบว่าได้นำข้อมูลก่อนหน้านี้ทั้งหมดออกแล้ว รวมถึงข้อมูลที่แคชไว้ในแอปพลิเคชันด้วย