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

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

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

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

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

ดาวน์โหลด Xcode

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

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

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

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

      • หากยังไม่ได้สร้าง โปรดดูวิธีการที่หัวข้อสร้างใบรับรอง Developer ID

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

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

สร้างแอป

หากต้องการดาวน์โหลด iOS SDK ของ Home API คุณต้องลงชื่อเข้าใช้ Google Home Developers ก่อน

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

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

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

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

4. เพิ่มความสามารถ App Attest:

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

5. เพิ่มความสามารถ App Groups

   

   

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

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

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

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

   1. แอปพลิเคชันต้องกำหนดค่าอินสแตนซ์ SDK เพื่อใช้ตัวระบุกลุ่มแอปสำหรับฟีเจอร์ต่างๆ เช่น การคอมมิชชันอุปกรณ์ อัปเดตแอปเพื่อใช้รหัสกลุ่มแอปที่ลงทะเบียนไว้ในพอร์ทัลนักพัฒนาแอปของ 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
     ...
   }