Permissions API ใน Android

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

ผสานรวม 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 ->
    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) แล้ว และคุณควร ขอสิทธิ์ ไม่เช่นนั้นผู้ใช้ควรมีสิทธิ์เข้าถึงอยู่แล้ว

ขอสิทธิ์

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

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