API สิทธิ์

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

ผสานรวม Permissions API

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

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

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

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

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

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

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

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

homeManager.requestPermissions(forceLaunch=true)

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

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

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

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

3. ผ่านหน้าแอปที่ลิงก์ไว้ในเว็บโดยตรง

สิทธิ์ OkGoogle

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