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

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

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

ตรวจสอบว่าคุณมีคุณสมบัติตรงตามข้อกำหนดขั้นต่ำในการใช้ 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

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

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

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

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

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

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

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

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

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

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

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

   

   

   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. แตก SDK ที่ดาวน์โหลดไปยังไดเรกทอรี ThirdParty/GoogleHomeSDK ที่สัมพันธ์กับไดเรกทอรีรากของโปรเจ็กต์
2. กำหนดค่ารหัสไคลเอ็นต์สำหรับนักพัฒนาแอปและไคลเอ็นต์ OAuth ดังนี้
   1. ในแผงการนำทาง ให้มองหาโฟลเดอร์ GoogleHomeAPISampleIOS แล้ว เปิดไฟล์ Info.plist เพื่อแก้ไข

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

4. เพิ่มความสามารถในการยืนยันแอป

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

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

   

   

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

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

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

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

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

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

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