Permissions API ใน Android

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

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

ผสานรวม 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 ->
    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 เป็น 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}")
      }
    }
  }
}

เพื่อให้ UI สิทธิ์เปิดขึ้นอย่างถูกต้อง คุณต้องตั้งค่า OAuth สำหรับแอปไว้แล้ว

UI ความยินยอมให้สิทธิ์จะแสดงผลในภาษาที่กำหนดค่าด้วย HomeClient.setLocale() หรือค่าเริ่มต้นเป็นภาษาของแอปหรืออุปกรณ์หากไม่ได้ตั้งค่าไว้ หากต้องการแสดงหน้าจอขอความยินยอมในภาษาที่เฉพาะเจาะจง ให้เรียก setLocale() ในอินสแตนซ์ HomeClient ก่อนเรียก requestPermissions() ดูข้อมูลเพิ่มเติมได้ที่กำหนดค่าภาษาของแอป

ให้สิทธิ์

ตอนนี้คุณควรจะเรียกใช้แอปและให้ผู้ใช้ให้สิทธิ์ได้แล้ว ประเภทของผู้ใช้ที่ให้สิทธิ์ได้และประเภทอุปกรณ์ที่ให้สิทธิ์ได้จะแตกต่างกันไป ขึ้นอยู่กับว่าคุณได้ลงทะเบียนแอปใน 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() อีกครั้งโดยตั้งค่า forcePermissionFlow เป็น ForcePermissionFlow.FORCE_LAUNCH ดังนี้

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH)

เปลี่ยนสิทธิ์ด้วยการระบุบ้านล่วงหน้า

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

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

• structureId — รหัสบ้านที่เฉพาะเจาะจงที่จะเลือกไว้ล่วงหน้าในกล่องโต้ตอบสิทธิ์ ดูข้อมูลนี้ได้โดยตรวจสอบพร็อพเพอร์ตี้ของบ้านสำหรับบ้านที่กำลังอัปเดต
• allowedStructureIds — รายการรหัสบ้าน หากระบุไว้ กล่องโต้ตอบสิทธิ์จะกรองโครงสร้างที่พร้อมใช้งานเพื่อแสดงเฉพาะโครงสร้างในรายการนี้ ในกรณีส่วนใหญ่ คุณสามารถปล่อยให้ไม่มีการระบุได้ เว้นแต่คุณต้องการตรวจสอบว่าผู้ใช้ยังคงอยู่ในรายการโครงสร้างที่ได้รับอนุญาตแล้ว
• allowStructureChange — กำหนดว่าผู้ใช้ได้รับอนุญาตให้เปลี่ยนโครงสร้างที่เลือกไว้ล่วงหน้าหรือไม่ ตั้งค่านี้เป็น true หากมีการระบุ allowedStructureIds และ structureId อย่างน้อย 1 รายการในกรณีส่วนใหญ่เพื่อรองรับลักษณะการทำงานตามธรรมชาติของผู้ใช้

ส่งออบเจ็กต์นี้เป็นพารามิเตอร์ที่ไม่บังคับในการเรียก requestPermissions() โดยตั้งค่า forcePermissionFlow เป็น ForcePermissionFlow.FORCE_LAUNCH ดังนี้

import com.google.home.ConsentScreenOptions

// Create the ConsentScreenOptions class, allowing structure changes while
// ensuring the permissions dialog pre-selects the target structure on launch
val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowStructureChange = true
)

homeManager.requestPermissions(forcePermissionFlow = ForcePermissionFlow.FORCE_LAUNCH, consentScreenOptions = consentOptions)

ผู้ใช้จะเห็นหน้าจอขอความยินยอมที่กรองตามโครงสร้างที่ระบุไว้ในออบเจ็กต์ ConsentScreenOptions แล้ว

อนุญาตให้ผู้ใช้เปลี่ยนบ้านด้วยการระบุบ้านล่วงหน้า

หากผู้ใช้มีบ้านหลายหลังในแอปและคุณต้องการเลือกไว้ล่วงหน้า 1 หลังโดยที่ยังอนุญาตให้ผู้ใช้สลับไปมาระหว่างบ้านที่มีอยู่ได้ ให้เปิดใช้การเปลี่ยนแปลงบ้านด้วยแฟล็ก allowStructureChange และระบุรายการบ้านใน allowedStructureIds ดังนี้

val consentOptions = ConsentScreenOptions(
    structureId = target-structure-id,
    allowedStructureIds = listOf(target-structure-id, another-structure-id),
    allowStructureChange = true
)

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

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

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

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

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

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

การลบและการส่งออกข้อมูลผู้ใช้

แพลตฟอร์มจะจัดการการลบข้อมูลแบ็กเอนด์โดยอัตโนมัติเมื่อผู้ใช้ลบบัญชี Google หรือออกจากบ้าน:

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

Home API ไม่มีปลายทางสำหรับส่งออกหรือลบข้อมูลในบัญชี Google ของผู้ใช้ แจ้งให้ผู้ใช้ที่มีบัญชี Google ไปที่ Google Takeout เพื่อส่งออกข้อมูล Google Home และไปที่การตั้งค่าบัญชี Google เพื่อจัดการการลบบัญชี

ดูประเภทอุปกรณ์ที่ผู้ใช้ให้สิทธิ์

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

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

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

สิทธิ์ OkGoogle

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

คำแนะนำหากผู้ใช้เพิกถอนสิทธิ์ทั้งหมด

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

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

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