เริ่มต้นบ้านใน Android

ก่อนใช้ Home API สำหรับ Android คุณต้องเริ่มต้นบ้านในแอปของคุณ ในขั้นตอนนี้ คุณจะสร้างอินสแตนซ์ Singleton ของ Home สำหรับบริบทในเครื่อง

ควรใช้งาน Home เพียงครั้งละ 1 รายการเท่านั้น

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

สร้างอินสแตนซ์บ้าน

ก่อนอื่น ให้นำเข้าแพ็กเกจต่อไปนี้ลงในแอป

import android.content.Context
import com.google.home.FactoryRegistry
import com.google.home.HomeConfig
import com.google.home.Home

วิธีเริ่มต้น Home API

1. รับข้อมูลอ้างอิงไปยัง Application บริบท บริบทนี้ไม่ขึ้นอยู่กับวงจรการทำงานของกิจกรรมใดๆ และจะ คงอยู่ตราบเท่าที่แอปของคุณยังทำงานอยู่ คุณขอรับรหัสได้โดยโทรหา getApplicationContext() ภายใน Activity หรือ Service

   val context = getApplicationContext()
   

2. สร้างFactoryRegistry อินสแตนซ์ที่มีลักษณะและประเภทอุปกรณ์ทั้งหมดที่คุณต้องการใช้ในแอป

   สำหรับคำแนะนำนี้ เราได้แนะนำอุปกรณ์ที่ใช้กันทั่วไป (ประเภทอุปกรณ์หลอดไฟ ปลั๊ก เซ็นเซอร์ สวิตช์ และตัวควบคุมอุณหภูมิ ลักษณะการแสดงตนและลักษณะของ Assistant สำหรับ การทำงานอัตโนมัติ) ในกรณีที่คุณไม่แน่ใจว่าต้องการอะไร ดูข้อมูลเพิ่มเติมได้ที่ การลงทะเบียนลักษณะและประเภทอุปกรณ์

   val registry = FactoryRegistry(
     traits = listOf(
               AirQuality,
               AreaAttendanceState,
               AreaPresenceState,
               AssistantBroadcast,
               AssistantFulfillment,
               BooleanState,
               ColorControl,
               ExtendedColorControl,
               FlowMeasurement,
               IlluminanceMeasurement,
               LevelControl,
               Notification,
               OccupancySensing,
               OnOff,
               RelativeHumidityMeasurement,
               Switch,
               TemperatureMeasurement,
               Thermostat),
     types = listOf(
               AirQualitySensorDevice,
               ColorDimmerSwitchDevice,
               ColorTemperatureLightDevice,
               ContactSensorDevice,
               DimmableLightDevice,
               DimmablePlugInUnitDevice,
               DimmerSwitchDevice,
               ExtendedColorLightDevice,
               FlowSensorDevice,
               GenericSwitchDevice,
               HumiditySensorDevice,
               LightSensorDevice,
               OccupancySensorDevice,
               OnOffLightDevice,
               OnOffLightSwitchDevice,
               OnOffPluginUnitDevice,
               OnOffSensorDevice,
               SpeakerDevice,
               TemperatureSensorDevice,
               ThermostatDevice))
   

   คุณต้องนำเข้าคำสั่งสำหรับลักษณะเฉพาะและประเภทอุปกรณ์แต่ละรายการที่ลงทะเบียนไว้ที่นี่ (Android Studio ควรแจ้งให้คุณเพิ่มคำสั่งเหล่านี้)

3. สร้างอินสแตนซ์ของ HomeConfig โดยใช้ Dispatchers.IO บริบทของโครูทีนและอินสแตนซ์รีจิสทรี

   val homeConfig = HomeConfig(
           coroutineContext = Dispatchers.IO,
           factoryRegistry = registry)
   

4. สุดท้าย ให้สร้างอินสแตนซ์ singleton ของ Home ซึ่งเป็นจุดแรกเข้าของ API โดยใช้บริบทและ HomeConfig

   val homeManager: HomeClient = Home.getClient(context, homeConfig)
   

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

ตัวอย่างเช่น Sample App จะดำเนินการดังนี้

internal object HomeClientModule {
  @Provides
  @Singleton
  fun provideHomeClient(@ApplicationContext context: Context): HomeClient {
    return Home.getClient(
      context,
      HomeConfig(
        coroutineContext = IODispatcherModule.provideIoDispatcher(),
        factoryRegistry = registry,
      ),
    )
  }
}

Google Sign-In ที่แอปเริ่มต้น

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

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

นอกจากนี้ วิธีนี้ยังช่วยป้องกันไม่ให้ผู้ใช้เห็นหน้าจอการเลือกบัญชี 2 หน้าจอที่แตกต่างกัน ได้แก่ หน้าจอหนึ่งจากการลงชื่อเข้าใช้ของแอป และอีกหน้าจอหนึ่งจาก Google Home

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

สร้างรหัสไคลเอ็นต์ OAuth สำหรับเว็บแอปพลิเคชัน

1. เปิด Google Cloud Console
   • ไปที่หน้าข้อมูลเข้าสู่ระบบของ Google Cloud Console
   • เลือกโปรเจ็กต์ที่มีอยู่หรือสร้างโปรเจ็กต์ใหม่
2. กำหนดค่าหน้าจอขอความยินยอม OAuth (หากยังไม่ได้ดำเนินการ)
   • ก่อนสร้างข้อมูลเข้าสู่ระบบ โปรดตรวจสอบว่าได้กำหนดค่าหน้าจอขอความยินยอม OAuth ด้วยรายละเอียดของแอป ซึ่งรวมถึง URL ของนโยบายความเป็นส่วนตัวและข้อกำหนดในการให้บริการแล้ว
3. สร้างรหัสไคลเอ็นต์ OAuth (ประเภทเว็บแอปพลิเคชัน)
   • ในหน้าข้อมูลเข้าสู่ระบบ ให้คลิก + CREATE CREDENTIALS แล้วเลือกรหัสไคลเอ็นต์ OAuth จากเมนูแบบเลื่อนลง
   • ในส่วนประเภทแอปพลิเคชัน ให้เลือกเว็บแอปพลิเคชัน
   • ป้อนชื่อไคลเอ็นต์เว็บ (เช่น "แบ็กเอนด์ของเว็บแอปของฉัน")
   • คลิกสร้าง
4. เรียกข้อมูลรหัสไคลเอ็นต์
   • หลังจากสร้างแล้ว คอนโซลจะแสดงรหัสไคลเอ็นต์ใหม่ นี่คือค่าที่คุณจะใช้ในแอปพลิเคชัน Android (เช่น "{project number}-.....apps.googleusercontent.com")
   • ขอแนะนําให้คุณจัดเก็บรหัสลูกค้าภายนอก (เช่น ใน build.gradle) แทนที่จะฮาร์ดโค้ดโดยตรง

สร้างอินสแตนซ์คำขอ Google Sign-In

ใช้รหัสเว็บแอปเพื่อสร้างคำขอลงชื่อเข้าใช้ด้วย Google โดยทำดังนี้

// Your Google Cloud console Web Client ID for Google Sign-In
val serverClientId = BuildConfig.DEFAULT_WEB_CLIENT_ID

// Build the request for Google ID token
val googleIdOption = GetGoogleIdOption.Builder()
    .setFilterByAuthorizedAccounts(false) // Show all Google Accounts on the device
    .setServerClientId(serverClientId) // embed WebClientID in token
    .build()

// Build the GetCredentialRequest
val request = GetCredentialRequest.Builder().addCredentialOption(googleIdOption).build()

สร้างขั้นตอนการลงชื่อเข้าใช้ด้วย Google

หากต้องการติดตั้งใช้งานโฟลว์การลงชื่อเข้าใช้ ให้ใช้ CredentialManager เพื่อดำเนินการคำขอ Sign in with Google เมื่อผู้ใช้เลือกบัญชีแล้ว ให้ดึงข้อมูล อีเมลจากโทเค็นรหัส Google ที่ได้เพื่อสร้าง android.accounts.Account จากนั้นระบบจะใช้บัญชีนี้เพื่อเริ่มต้นอินสแตนซ์ HomeClient ที่เชื่อมโยงกับผู้ใช้ที่ลงชื่อเข้าใช้รายนั้นโดยเฉพาะ

  try {
    // CredentialManager is responsible for interacting with various credential providers on the device
    val credentialManager = CredentialManager.create(context)
    // Credential returns when user has selected an account and the getCredential call completes
    val result = credentialManager.getCredential(context = context, request = request)
    val credential = result.credential

    if (
      credential is CustomCredential &&
      credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL
    ) {
      try {
        val googleCredential = GoogleIdTokenCredential.createFrom(credential.data)
        googleCredential.id.let { userEmail ->
          Log.i(TAG, "Email found in Google ID Token: $email")
          /*
           Why "com.google"?
           The string "com.google" is a standard identifier used in Android's android.accounts.
           Account system to represent accounts managed by Google. This is often used when
           interacting with Android's Account Manager or when using Google-specific APIs. So,
           even if the email ends in "@gmail.com", the underlying account type or provider is
           still considered "com.google" within the Android system.
          */
          val account = Account(userEmail, "com.google")
          Log.d(TAG,"Switched account to : $userEmail")
          // Get the new Home Client Instance with the userEmail
        }
        Log.i(TAG, "Account switch complete. Emitting navigation event.")
      } catch (e: Exception) {
        Log.e(TAG,"Could not convert CustomCredential to Google ID Token", e)
      }
    }
  } catch (e: Exception) {
    Log.e(TAG, "Google Sign-In failed with unexpected error", e)
  }

รับอินสแตนซ์ HomeClient ใหม่

ทำตามขั้นตอนเดียวกันกับที่ระบุไว้ใน สร้างอินสแตนซ์ Home แต่แทนที่จะเรียกใช้ Home.getClient(context, homeConfig) ในขั้นตอนที่ 4 ให้เรียกใช้ Home.getClient(context, userAccount, homeConfig) โดยที่พารามิเตอร์ที่ 2 คือ Lazy<UserAccount> ซึ่งจะแสดงอินสแตนซ์ของ HomeClientWithProvidedAccount ซึ่งเป็นคลาสย่อยของ HomeClient ที่เชื่อมโยงกับบัญชี Google ที่ระบุอย่างชัดเจน

val client =
     Home.getClient(
       context = context.applicationContext,
       account =
         lazy {
         // 1. Create the Account object.
           val androidAccount = Account(userEmail,
                                        GoogleAuthUtil.GOOGLE_ACCOUNT_TYPE)
         // 2. Wrap it in UserAccount.GoogleAccount.
           UserAccount.GoogleAccount(androidAccount)
         },
       homeConfig = HomeConfig()
     )

หากผู้ใช้ที่ระบุไม่ได้รับอนุญาต ให้แจ้งให้ผู้ใช้ขอสิทธิ์โดย เรียกใช้เมธอดต่อไปนี้ในอินสแตนซ์ HomeClientWithProvidedAccount

1. registerActivityResultCallerForPermissions() โดยอ้างอิงถึง ActivityResultCaller ที่คุณต้องการใช้
2. requestPermissions() ซึ่งจะแสดงหน้าจอคำยินยอมของ GHP ที่ผู้ใช้สามารถให้ สิทธิ์ได้

คุณสามารถสร้าง HomeClient ด้วย UserAccount แล้วเรียกใช้ requestPermissions() ด้วย forceLaunch==true เพื่อเปิดหน้าจอขอความยินยอม อีกครั้งเพื่อให้ผู้ใช้อัปเดตการให้สิทธิ์ได้

val client =
     Home.getClient(
       context = context.applicationContext,
       account =
         lazy {
              UserAccount.GoogleAccount(androidAccount)
         },
       homeConfig = HomeConfig()
     )

client.registerActivityResultCallerForPermissions(this)
client.requestPermissions(forceLaunch= true)

ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการสิทธิ์ของ Home API ได้ที่ Permissions API

รีเฟรชกิจกรรมทั้งหมดด้วย HomeClient ใหม่

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

การลงทะเบียนลักษณะและประเภทอุปกรณ์

คลาส FactoryRegistry ช่วยให้นักพัฒนาแอปเพิ่มประสิทธิภาพไบนารีของแอปได้โดย การระบุลักษณะและประเภทอุปกรณ์ที่แอปใช้โดยชัดแจ้ง

โปรดทราบว่าสิทธิ์และการลงทะเบียนจากโรงงานจะแยกออกจากกัน ดังนั้น ลักษณะและประเภทที่ไม่ได้ลงทะเบียนซึ่งแอปของคุณเข้าถึงได้โดยใช้สิทธิ์ แต่ไม่ได้รวมอยู่ในรีจิสทรีของโรงงานจะเข้าถึงไม่ได้โดยใช้ Automation API และจะไม่แสดงในการเรียกเมธอดแบบกลุ่ม traits() หรือ types()