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

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

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

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

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

ดาวน์โหลด Xcode

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      • หากยังไม่ได้สร้าง ให้ดูวิธีการในหัวข้อสร้างใบรับรองรหัสนักพัฒนาแอป

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

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

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

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

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

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

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

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

5. ในแผงเมนูด้านซ้าย ให้คลิกข้อมูลเข้าสู่ระบบเพื่อสร้างรหัสไคลเอ็นต์ 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 Home Developers ก่อน

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

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

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

   

   

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 ให้ป้อน GIDClientID ด้วยรหัสไคลเอ็นต์ OAuth (ดูส่วนตั้งค่าความยินยอมของ OAuth) หมายเลขโปรเจ็กต์ Cloud ที่สอดคล้องกับโปรเจ็กต์ Cloud และ GIDTeamID ด้วยรหัสทีมของนักพัฒนาแอป Apple ของบัญชีนักพัฒนาแอปที่ใช้ในกระบวนการลงทะเบียน OAuth

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

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

13. เพิ่มความสามารถของกลุ่มแอป

    

    

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

14. อัปเดตรหัสชุดซอฟต์แวร์

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

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

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

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

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