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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  6. อัปเดตตัวระบุชุดซอฟต์แวร์โดยทำดังนี้

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

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

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

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

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