สร้างแอปตัวอย่าง iOS

แอปพลิเคชัน iOS ตัวอย่างนี้ใช้ Google Home API ใช้คู่มือนี้เพื่อสร้างและเรียกใช้แอปเป็นครั้งแรก

ข้อกำหนดเบื้องต้น

ตรวจสอบว่าคุณมีคุณสมบัติตรงตามข้อกำหนดขั้นต่ำในการใช้ Home API สำหรับ iOS

หากต้องการสร้างและติดตั้งแอปตัวอย่าง คุณจะต้องมีคอมพิวเตอร์ที่ติดตั้ง Xcode เวอร์ชัน 15.3 ขึ้นไป

ดาวน์โหลด Xcode

หากต้องการทดสอบแอป คุณจะต้องมีสิ่งต่อไปนี้

  1. บัญชี Google
  2. รหัส Apple ที่ลงทะเบียนในโปรแกรมนักพัฒนาแอปของ Apple เพื่อสร้างไฟล์การกําหนดค่าอุปกรณ์จริง หากยังไม่ได้สร้าง การลงทะเบียนจะมีค่าใช้จ่ายเพิ่มเติมและอาจใช้เวลาถึง 48 ชั่วโมงจึงจะเสร็จสมบูรณ์
  3. อุปกรณ์ iOS (ไม่ใช่เครื่องจำลอง) ที่ใช้ iOS 16.4 ขึ้นไปซึ่งตั้งค่าด้วยบัญชีทดสอบ
  4. เครือข่าย Wi-Fi
  5. ฮับ Google ที่รองรับ Home API
  6. Thread Border Router หากอุปกรณ์ต้องใช้ Thread และฮับของคุณไม่มีความสามารถดังกล่าว
  7. ประเภทอุปกรณ์ที่รองรับอย่างน้อย 1 ประเภท

สำหรับการพัฒนา คุณจะต้องมี Mac ที่มีคุณสมบัติตรงตามข้อกำหนดต่อไปนี้

  • macOS Sonoma ขึ้นไป
  • Xcode 15.3 ขึ้นไป

สร้างไฟล์การกำหนดค่าสำหรับการติดตั้งใช้งาน Apple

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

ประการที่ 2 คุณต้องเปิดใช้ App Group เพื่อการสื่อสารระหว่างแอปกับ MatterExtension ซึ่งคุณจะต้องลงทะเบียนตัวระบุกลุ่มแอป

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

ต่อไปนี้เป็นขั้นตอนขั้นต่ำที่จำเป็นในการทำให้แอปใช้งานได้

  1. สร้างตัวระบุกลุ่มแอปเพื่อให้แอปสื่อสารกับ MatterExtension
    1. ลงชื่อเข้าใช้พอร์ทัลนักพัฒนาแอปของ Apple
    2. เพิ่มตัวระบุกลุ่มแอป เช่น อาจอยู่ในรูปแบบ group.com.company.commissioning
  2. ลงทะเบียนอุปกรณ์ทดสอบกับบัญชีนักพัฒนาแอป

  3. สร้างโปรไฟล์สําหรับเป้าหมายแอป

    1. เลือกตัวระบุกลุ่มแอปพลิเคชันสำหรับแอปของคุณ ตัวระบุควรไม่ซ้ำกันและสื่อความหมาย เช่น อาจอยู่ในรูปแบบ com.company.HomeApiSample ระบบจะใช้ตัวระบุนี้ในส่วนที่เหลือของส่วนนี้
    2. ลงทะเบียนรหัสแอป เมื่อได้รับข้อความแจ้ง ให้เพิ่มความสามารถการรับรองแอปและกลุ่มแอป

    3. แก้ไขรหัสแอปที่สร้างขึ้นใหม่และกำหนดค่าความสามารถของกลุ่มแอปเพื่อเพิ่มตัวระบุกลุ่มแอปที่ลงทะเบียน

    4. สร้างโปรไฟล์การจัดสรรสำหรับการพัฒนาเพื่อการพัฒนาแอป เชื่อมโยงกับรหัสแอปที่สร้างขึ้นใหม่และอุปกรณ์ทดสอบที่เลือก ตรวจสอบว่าคุณมีใบรับรองนักพัฒนาแอปเพื่อใช้ลงชื่อแอป

  4. สร้างโปรไฟล์สําหรับเป้าหมาย MatterExtension

    1. เลือกตัวระบุ App Bundle สำหรับ MatterExtension ตัวระบุควรรับค่ามาจากตัวระบุแอป เช่น อาจมีการจัดรูปแบบเป็น com.company.HomeApiSample.MatterExtension
    2. ลงทะเบียนรหัสแอป เมื่อได้รับข้อความแจ้ง ให้เพิ่มความสามารถของApp Group
    3. แก้ไขรหัสแอปที่สร้างขึ้นใหม่และกำหนดค่าความสามารถของกลุ่มแอปเพื่อเพิ่มตัวระบุกลุ่มแอปที่ลงทะเบียนซึ่งสร้างขึ้นในขั้นตอนก่อนหน้า
    4. สร้างโปรไฟล์การจัดสรรสำหรับการพัฒนา สำหรับ MatterExtension

สร้างรหัสไคลเอ็นต์ OAuth และเปิดใช้ Home API

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

สร้างรหัสไคลเอ็นต์ OAuth

  1. ในคอนโซล Google Cloud ให้ไปที่แดชบอร์ดตัวเลือกโปรเจ็กต์ แล้วเลือกโปรเจ็กต์ที่ต้องการใช้สร้างข้อมูลเข้าสู่ระบบ OAuth
  2. ไปที่หน้า API และบริการโดยคลิกปุ่มเมนูทางด้านซ้ายบน > ดูผลิตภัณฑ์ทั้งหมด > API และบริการ
  3. ในเมนูการนำทาง ให้คลิกข้อมูลเข้าสู่ระบบ

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

    1. เลือกภายในหรือภายนอก ทั้งนี้ขึ้นอยู่กับกรณีการใช้งาน แล้วคลิกสร้าง แผงหน้าจอขอความยินยอม OAuth จะปรากฏขึ้น
    2. ป้อนข้อมูลในหน้าข้อมูลแอปตามวิธีการบนหน้าจอ แล้วคลิกบันทึกและดำเนินการต่อ แผงขอบเขตจะปรากฏขึ้น
    3. คุณไม่จําเป็นต้องเพิ่มขอบเขตใดๆ เพียงคลิกบันทึกและดําเนินการต่อ แผงผู้ใช้ทดสอบจะปรากฏขึ้น
    4. หากเลือกสร้างหน้าจอขอความยินยอมภายใน คุณต้องเพิ่มผู้ใช้เพื่อทดสอบสิทธิ์เข้าถึงแอป โดยคลิกเพิ่มผู้ใช้ แผงเพิ่มผู้ใช้จะปรากฏขึ้น ผู้ใช้ทดสอบมีสิทธิ์ให้สิทธิ์ในแอปของคุณ ให้เพิ่มอีเมลบัญชี Google อย่างน้อย 1 รายการในช่องว่าง แล้วคลิกเพิ่ม
    5. คลิกบันทึกและต่อไป บานหน้าต่างสรุปจะปรากฏขึ้น
    6. ตรวจสอบข้อมูลหน้าจอขอความยินยอม OAuth แล้วคลิกกลับไปยังแดชบอร์ด

  5. ในแผงเมนูด้านซ้าย ให้คลิกข้อมูลเข้าสู่ระบบเพื่อสร้างรหัสไคลเอ็นต์ OAuth

    ตั้งค่าหน้าจอ OAuth

    1. คลิกปุ่มสร้างข้อมูลเข้าสู่ระบบ แล้วเลือกรหัสไคลเอ็นต์ OAuth
      1. ในส่วนประเภทแอปพลิเคชัน ให้เลือก iOS
    2. ป้อนรหัสกลุ่มที่มีตัวระบุแอปและรหัสทีมนักพัฒนาแอปของ Apple ช่องอื่นๆ นั้นไม่บังคับและสามารถเว้นว่างไว้ได้
    3. คลิกสร้าง แล้วจดบันทึกรหัสไคลเอ็นต์ที่สร้างขึ้นหรือดาวน์โหลด PLIST ซึ่งจะใช้ในภายหลังเพื่อเปิดใช้ฟังก์ชันการทำงานต่างๆ ของขั้นตอนการขอสิทธิ์ ดูข้อมูลเพิ่มเติมได้ที่ส่วนสร้างข้อมูลเข้าสู่ระบบเพื่อขอสิทธิ์

เปิดใช้ Home API

เปิดใช้การเข้าถึง Home API

  1. ในแท็บ API และบริการ ให้คลิก API และบริการที่เปิดใช้
  2. คลิกเปิดใช้ API และบริการที่ด้านบนของหน้า
  3. ค้นหา HOME API แล้วเลือก
  4. ในหน้ารายละเอียด Home API ให้คลิกเปิดใช้

ดาวน์โหลดซอร์สโค้ด

ซอร์สโค้ดของแอปตัวอย่างมีอยู่ใน GitHub

ไปที่ตำแหน่งที่ต้องการบันทึกโปรเจ็กต์ แล้วทําการโคลนดังนี้

git clone https://github.com/google-home/google-home-api-sample-app-ios.git

หากต้องการโหลดโปรเจ็กต์ใน Xcode ให้คลิกไฟล์ > เปิด แล้วเลือก GoogleHomeAPISampleIOS.xcodeproj ที่รูทของที่เก็บข้อมูลที่โคลน

ตั้งค่า SDK

โปรเจ็กต์แอปตัวอย่างต้องใช้ข้อมูลเพิ่มเติมในการสร้าง ซึ่งรวมถึงการเพิ่มไฟล์เฟรมเวิร์ก SDK ในเครื่อง การป้อนข้อมูลตัวระบุบัญชีนักพัฒนาแอป และการป้อนข้อมูลรหัสไคลเอ็นต์ OAuth

สร้างแอป

หากต้องการดาวน์โหลด Home APIs iOS SDK คุณต้องลงชื่อเข้าใช้ Google Developer Console สำหรับ Home ก่อน

ลงชื่อเข้าใช้เลย

กำหนดค่าโปรเจ็กต์ Xcode สำหรับแอปตัวอย่าง

  1. ในแผงการนำทางด้านซ้ายของ Xcode ให้เลือกไฟล์ GoogleHomeAPISampleIOS เพื่อแก้ไขการกำหนดค่าโปรเจ็กต์

    ตั้งค่าแอปตัวอย่าง SDK

  2. คลิกแท็บทั่วไปที่ด้านบน แล้วเลือกเป้าหมาย GoogleHomeAPISampleIOS ทางด้านซ้าย

  3. เลื่อนลงจนกว่าจะเห็นส่วนเฟรมเวิร์ก ไลบรารี และเนื้อหาที่ฝัง คุณควรเห็นเฟรมเวิร์ก Home API 2 รายการแสดงอยู่

  4. ในคอลัมน์ฝัง ให้เลือกฝังและลงชื่อสำหรับ GoogleHomeSDK.xcframework ส่วนเฟรมเวิร์กอีกเฟรมหนึ่ง GoogleHomeTypes.xcframework ควรเป็นไม่ฝัง

  5. คลิกไอคอน + ที่ด้านล่างของรายการ

  6. เมื่อได้รับข้อความแจ้ง ให้ค้นหา SafariServices.framework แล้วคลิกเพิ่ม ตรวจสอบว่าได้ตั้งค่าคอลัมน์ฝังเป็นไม่ฝังสําหรับรายการนี้

    ฝังและลงนาม

  7. คลิก MatterAddDeviceExtension ในส่วนเป้าหมายเพื่อแก้ไขเป้าหมาย

  8. เลื่อนลงจนกว่าจะเห็นส่วนเฟรมเวิร์กและไลบรารี คุณควรเห็น GoogleHomeSDK.xcframework แสดงอยู่

  9. ในคอลัมน์ฝัง ให้เลือกไม่ฝัง

  10. กำหนดค่ารหัสไคลเอ็นต์ OAuth และนักพัฒนาแอป ดังนี้

    1. ในแผงการนำทาง ให้มองหาโฟลเดอร์ GoogleHomeAPISampleIOS แล้วเปิดไฟล์ Info.plist เพื่อแก้ไข

  11. ในไฟล์ Info.plist ให้ป้อนรหัสไคลเอ็นต์ OAuth ของคุณใน GIDClientID (ดูส่วนตั้งค่าความยินยอม OAuth) และป้อน Apple Developer Team ID ของบัญชีนักพัฒนาแอปที่ใช้ในระหว่างกระบวนการลงทะเบียน OAuth ใน GIDTeamID

  12. กำหนดค่าระบบบิลด์

    เพิ่ม Flag ของ Linker

    1. ในแผงการนำทางด้านซ้ายของ Xcode ให้เลือกไฟล์โปรเจ็กต์ GoogleHomeAPISampleIOS เพื่อแก้ไขการกำหนดค่าโปรเจ็กต์
    2. คลิกแท็บการตั้งค่าการสร้างที่ด้านบน แล้วเลือกเป้าหมาย GoogleHomeAPISampleIOS ทางด้านซ้ายมือในส่วนเป้าหมาย
    3. ค้นหาFlag Linker อื่นๆ แล้วเพิ่มรายการ 2 รายการต่อไปนี้
      • -lc++
      • -ObjC

  13. เพิ่มความสามารถในการรับรองแอป

    1. ในแผงการนำทางด้านซ้ายของ Xcode ให้เลือกไฟล์โปรเจ็กต์ GoogleHomeAPISampleIOS เพื่อแก้ไขการกำหนดค่าโปรเจ็กต์
    2. คลิกแท็บการรับรองและความสามารถที่ด้านบน แล้วเลือกเป้าหมาย GoogleHomeAPISampleIOS ทางด้านซ้ายมือในส่วนเป้าหมาย
    3. ใต้แท็บการรับรองและการรองรับ ให้คลิก + ความสามารถ แล้วค้นหาการรับรองแอป
    4. คลิกการรับรองแอปเพื่อเพิ่ม หากไม่พบความสามารถนี้ในการค้นหา แสดงว่าโปรเจ็กต์อาจเพิ่มความสามารถนี้ไปแล้ว

  14. เพิ่มความสามารถของ App Groups

    เพิ่มกลุ่มแอป

    1. ไปที่โปรเจ็กต์ GoogleHomeAPISampleIOS > เป้าหมาย GoogleHomeAPISampleIOS
    2. คลิกการลงนามและความสามารถ > + ความสามารถ
    3. เลือกความสามารถกลุ่มแอป
    4. คลิกไอคอน + ในส่วน App Group แล้วเพิ่มตัวระบุ App Group ของแอปที่คุณเพิ่มในพอร์ทัลนักพัฒนาแอปของ Apple
    5. ทําตามขั้นตอนเหล่านี้ซ้ำสําหรับเป้าหมาย MatterAddDeviceExtension เพื่อเพิ่มเป้าหมายนั้นลงใน App Group

  15. อัปเดตรหัส Bundle

    1. หากต้องการเรียกใช้และติดตั้งใช้งานแอปตัวอย่างในฮาร์ดแวร์โดยใช้ใบรับรองนักพัฒนาแอปและโปรไฟล์การจัดสรรให้สำเร็จ คุณจะต้องระบุตัวระบุแพ็กเกจที่ไม่ซ้ำกัน ซึ่งควรเป็นตัวระบุเดียวกันกับที่เชื่อมโยงกับข้อมูลเข้าสู่ระบบไคลเอ็นต์ OAuth (ดูด้านบน)
    2. ในแผงการนำทางด้านซ้ายของ Xcode ให้เลือกไฟล์โปรเจ็กต์ GoogleHomeAPISampleIOS เพื่อแก้ไขการกำหนดค่าโปรเจ็กต์
    3. คลิกแท็บการรับรองและความสามารถที่ด้านบน แล้วเลือกเป้าหมาย GoogleHomeAPISampleIOS ทางด้านซ้ายมือในส่วนเป้าหมาย
    4. เลือกช่องตัวระบุกลุ่มในส่วนตัวการรับรอง แล้วป้อนรหัสที่ไม่ซ้ำสำหรับแอปพลิเคชัน
    5. เลือกหรือติดตั้งโปรไฟล์การจัดสรรที่เกี่ยวข้องกับแพ็กเกจนั้นพร้อมการให้สิทธิ์ที่จําเป็น
    6. ทำตามขั้นตอนเหล่านี้ซ้ำสำหรับเป้าหมาย MatterAddDeviceExtension เพื่อป้อนตัวระบุกลุ่มสำหรับส่วนขยายและนําเข้าโปรไฟล์การจัดสรรที่ลงทะเบียนไว้

  16. อัปเดตตัวระบุกลุ่มแอปที่ลงทะเบียนในโค้ด

    1. แอปพลิเคชันต้องกําหนดค่าอินสแตนซ์ SDK เพื่อใช้ประโยชน์จากตัวระบุ App Group สําหรับฟีเจอร์ต่างๆ เช่น การจัดเตรียมอุปกรณ์ อัปเดตแอปเพื่อใช้รหัสกลุ่มแอปที่ลงทะเบียนไว้ในพอร์ทัลนักพัฒนาแอปของ Apple โดยค้นหาสตริง HOME_API_TODO_ADD_APP_GROUP แล้วแทนที่แต่ละอินสแตนซ์ด้วยสตริงดังกล่าว

    การกำหนดค่าเหล่านี้ทำในไฟล์ต่อไปนี้

    • GoogleHomeAPISampleIOS.swift เมื่อเริ่มต้น SDK
    • RequestHandler.swift
    • CommissioningManager.swift