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

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

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

ตรวจสอบว่าคุณมีคุณสมบัติตรงตามข้อกำหนดขั้นต่ำในการใช้ Home APIs สำหรับ 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. A Thread Border Router (TBR) หากอุปกรณ์ของคุณต้องใช้ Thread และฮับ ไม่มีความสามารถดังกล่าว
7. อุปกรณ์ประเภทที่รองรับอย่างน้อย 1 ประเภท

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

แอปของคุณต้องมีรหัสไคลเอ็นต์ 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 APIs

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

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 Framework ในเครื่อง การป้อนข้อมูลตัวระบุบัญชีนักพัฒนาแอป และการป้อนรหัสไคลเอ็นต์ 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. เพิ่มความสามารถ App Attest โดยทำดังนี้

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

5. เพิ่มความสามารถ App Groups โดยทำดังนี้

   

   

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

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

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

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

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

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

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

8. กำหนดค่าขอบเขต OAuth ใน GoogleHomeAPISampleIOS.swift โดยค่าเริ่มต้น ซอร์สโค้ดของแอปตัวอย่างจะใช้ขอบเขต https://www.googleapis.com/auth/home.platform.v2 ฟีเจอร์หลายอย่างในแอปตัวอย่างถูกจำกัดด้วยขอบเขต home.platform.v2 และต้องได้รับการอนุมัติจากพาร์ทเนอร์จึงจะเข้าถึงได้ หากต้องการเรียกใช้แอปตัวอย่างด้วยขอบเขต https://www.googleapis.com/auth/home.platform.selected.devices มาตรฐาน ให้เปิด GoogleHomeAPISampleIOS.swift แล้วเปลี่ยน homePlatformOAuthScope ใน Home.configure เป็น HomePlatformOAuthScope.v1 ดังนี้

   Home.configure {
     $0.sharedAppGroup = "HOME_API_TODO_ADD_APP_GROUP"
     $0.homePlatformOAuthScope = HomePlatformOAuthScope.v1
     ...
   }