Tạo ứng dụng mẫu iOS

Ứng dụng iOS mẫu này sử dụng các API Google Home. Hãy tham khảo hướng dẫn này để tạo và chạy ứng dụng lần đầu tiên.

Điều kiện tiên quyết

Đảm bảo bạn đáp ứng các yêu cầu tối thiểu để sử dụng API Home cho iOS.

Để tạo và cài đặt Ứng dụng mẫu, bạn cần có một máy tính đã cài đặt Xcode phiên bản 15.3 trở lên.

Tải Xcode xuống

Để kiểm thử ứng dụng, bạn cần:

1. Một Tài khoản Google.
2. Một Apple ID đã đăng ký Chương trình nhà phát triển của Apple để tạo tệp cấu hình thiết bị thực. Nếu chưa tạo, bạn sẽ phải trả thêm phí đăng ký và có thể mất đến 48 giờ để hoàn tất.
3. Một thiết bị iOS (không phải trình mô phỏng) chạy iOS 16.4 trở lên được thiết lập bằng tài khoản thử nghiệm.
4. Mạng Wi-Fi.
5. Một trung tâm Google hỗ trợ các API Home.
6. Một Thread Border Router (TBR) nếu thiết bị của bạn yêu cầu Thread và trung tâm của bạn không có tính năng đó.
7. Ít nhất một loại thiết bị được hỗ trợ.

Để phát triển, bạn cần có một máy Mac đáp ứng các yêu cầu sau:

• macOS Sonoma trở lên
• Xcode 15.3 trở lên

Tạo tệp cấu hình triển khai của Apple

Trước tiên, một ứng dụng yêu cầu phải bật tính năng App Attest. Do đó, ứng dụng này không thể triển khai cho các thiết bị mô phỏng. Bạn cần tạo một hồ sơ cấp phép có quyền App Attest.

Thứ hai, ứng dụng này yêu cầu phải bật Nhóm ứng dụng để giao tiếp giữa ứng dụng và MatterExtension. Bạn cần đăng ký một giá trị nhận dạng nhóm ứng dụng.

Để biết thêm chi tiết, hãy xem bài viết Tạo hồ sơ cấp phép phát triển của Apple về hồ sơ cấp phép.

Sau đây là các bước tối thiểu cần thiết để triển khai một ứng dụng:

1. Tạo một giá trị nhận dạng nhóm ứng dụng để ứng dụng của bạn giao tiếp với MatterExtension.
   1. Đăng nhập vào cổng thông tin cho nhà phát triển của Apple.
   2. Thêm một giá trị nhận dạng nhóm ứng dụng. Ví dụ: giá trị nhận dạng này có thể được định dạng là group.com.company.commissioning.
2. Đăng ký thiết bị thử nghiệm vào tài khoản nhà phát triển.

3. Tạo một hồ sơ cho mục tiêu ứng dụng của bạn.

   1. Quyết định mã nhận dạng gói ứng dụng cho ứng dụng của bạn. Mã nhận dạng này phải là duy nhất và mang tính mô tả. Ví dụ: giá trị nhận dạng này có thể được định dạng là com.company.HomeApiSample. Giá trị nhận dạng này sẽ được sử dụng trong phần còn lại của phần này.
   2. Đăng ký Mã ứng dụng. Khi được nhắc, hãy thêm tính năng App Attest và App Groups.

   3. Chỉnh sửa Mã ứng dụng mới tạo và định cấu hình tính năng App Groups để thêm giá trị nhận dạng nhóm ứng dụng đã đăng ký.

   4. Tạo một hồ sơ cấp phép phát triển cho quá trình phát triển ứng dụng. Liên kết hồ sơ này với Mã ứng dụng mới tạo và các thiết bị thử nghiệm đã chọn. Đảm bảo bạn có chứng chỉ nhà phát triển để ký ứng dụng.

      • Nếu bạn chưa tạo chứng chỉ, hãy xem bài viết Tạo chứng chỉ ID nhà phát triển để biết hướng dẫn.

4. Tạo một hồ sơ cho mục tiêu MatterExtension.

   1. Quyết định mã nhận dạng gói ứng dụng cho MatterExtension. Giá trị nhận dạng này phải được kế thừa từ giá trị nhận dạng ứng dụng. Ví dụ: giá trị nhận dạng này có thể được định dạng là com.company.HomeApiSample.MatterExtension.
   2. Đăng ký Mã ứng dụng. Khi được nhắc, hãy thêm tính năng App Group.
   3. Chỉnh sửa Mã ứng dụng mới tạo và định cấu hình tính năng App Groups để thêm giá trị nhận dạng nhóm ứng dụng đã đăng ký được tạo ở các bước trước.
   4. Tạo một hồ sơ cấp phép phát triển cho MatterExtension.

Tạo mã ứng dụng khách OAuth và bật API Home

Ứng dụng OAuth của bạn cần có mã ứng dụng khách để xác định chính ứng dụng đó với phần phụ trợ xác thực của Google. Đối với iOS và các ứng dụng, loại Ứng dụng OAuth mã ứng dụng khách phải được định cấu hình là iOS. Ứng dụng này cũng sẽ gọi API Home. Để bật chức năng này, bạn phải bật API trong dự án Google Cloud.

1. Trong bảng điều khiển Google Cloud, hãy chuyển đến trang tổng quan trình chọn dự án rồi chọn dự án mà bạn muốn dùng để tạo thông tin xác thực OAuth.
2. Chuyển đến trang API và Dịch vụ bằng cách nhấp vào nút trình đơn ở phía trên cùng bên trái > Xem tất cả sản phẩm > API và Dịch vụ.
3. Trong trình đơn điều hướng, hãy nhấp vào Thông tin xác thực.

4. Nếu bạn chưa định cấu hình màn hình xin phép cho dự án này trên Google Cloud, thì nút Configure consent screen (Định cấu hình màn hình xin phép) sẽ xuất hiện. Trong trường hợp đó, hãy định cấu hình màn hình xin phép theo quy trình sau. Nếu màn hình xin phép bằng OAuth đã được định cấu hình và trạng thái xuất bản là Testing (Thử nghiệm), hãy đảm bảo rằng các tài khoản thử nghiệm mà bạn sẽ sử dụng đã được thêm vào nhóm Test users (Người dùng thử nghiệm). Nếu không, hãy chuyển sang bước tiếp theo.

   1. Tuỳ thuộc vào trường hợp sử dụng, hãy chọn Internal (Nội bộ) hoặc External (Bên ngoài), rồi nhấp vào Create (Tạo). Ngăn OAuth consent screen (Màn hình xin phép bằng OAuth) sẽ xuất hiện.
   2. Nhập thông tin trên App information page (Trang thông tin ứng dụng) theo hướng dẫn trên màn hình, rồi nhấp vào Save and continue (Lưu và tiếp tục). Ngăn Scopes (Phạm vi) sẽ xuất hiện.
   3. Bạn không cần thêm bất kỳ phạm vi nào, vì vậy hãy nhấp vào Save and continue (Lưu và tiếp tục). Ngăn Test users (Người dùng thử nghiệm) sẽ xuất hiện.
   4. Nếu chọn tạo màn hình xin phép nội bộ, bạn phải thêm người dùng để kiểm thử quyền truy cập vào ứng dụng của mình. Nhấp vào Add users (Thêm người dùng). Ngăn Add users (Thêm người dùng) sẽ xuất hiện. Người dùng thử nghiệm có đặc quyền cấp quyền trong ứng dụng của bạn. Trong trường trống, hãy thêm một hoặc nhiều email của Tài khoản Google Account, rồi nhấp vào Add (Thêm).
   5. Nhấp vào Save and continue (Lưu và tiếp tục). Ngăn Summary (Tóm tắt) sẽ xuất hiện.
   6. Xem lại thông tin trên màn hình xin phép bằng OAuth, rồi nhấp vào Back to dashboard (Quay lại trang tổng quan).

5. Trên bảng điều khiển bên trái, hãy nhấp vào Credentials (Thông tin xác thực) để tạo mã ứng dụng khách OAuth.

   

   

   1. Nhấp vào nút CREATE CREDENTIALS (TẠO THÔNG TIN XÁC THỰC), rồi chọn OAuth client ID (Mã ứng dụng OAuth).
      1. Trong mục application type (loại ứng dụng), hãy chọn iOS.
   2. Nhập Bundle ID (Mã nhận dạng gói) bằng giá trị nhận dạng ứng dụng và Apple Developer Team ID (Mã nhóm) của Nhà phát triển Apple. Bạn có thể để trống các trường khác.
   3. Nhấp vào CREATE (TẠO) rồi lưu ý Client ID (Mã ứng dụng khách) đã tạo hoặc DOWNLOAD PLIST (TẢI PLIST XUỐNG). Mã này sẽ được dùng sau này để bật chức năng quy trình cấp quyền. Để biết thêm thông tin, hãy xem phần Tạo thông tin xác thực uỷ quyền section.

Bật các API Home

Cho phép truy cập vào các API Home.

1. Trong thẻ APIs and Services (API và Dịch vụ), hãy nhấp vào Enabled APIs &Services (API và Dịch vụ đã bật).
2. Nhấp vào ENABLE APIS AND SERVICES (BẬT API VÀ DỊCH VỤ) ở đầu trang.
3. Tìm kiếm HOME API rồi chọn API đó.
4. Trên trang thông tin chi tiết Home API, hãy nhấp vào ENABLE (BẬT).

Tải mã nguồn xuống

Mã nguồn cho Ứng dụng mẫu có trên GitHub.

Chuyển đến vị trí bạn muốn lưu dự án, sau đó sao chép dự án đó:

git clone https://github.com/google-home/google-home-api-sample-app-ios.git

Để tải dự án trên Xcode, hãy nhấp vào File > Open rồi chọn GoogleHomeAPISampleIOS.xcodeproj ở gốc kho lưu trữ đã sao chép.

Thêm SDK vào dự án

Dự án Ứng dụng mẫu yêu cầu một số thông tin bổ sung để tạo. Trong đó có cả việc thêm tệp Khung SDK cục bộ, điền thông tin giá trị nhận dạng tài khoản nhà phát triển và điền mã ứng dụng khách OAuth.

Tạo ứng dụng

Để tải SDK API Home cho iOS xuống, trước tiên, bạn phải đăng nhập vào Nhà phát triển Google Home.

Đăng nhập ngay!

Định cấu hình dự án Xcode cho Ứng dụng mẫu:

1. Giải nén SDK đã tải xuống vào thư mục ThirdParty/GoogleHomeSDK tương ứng với thư mục gốc của dự án.
2. Định cấu hình Mã nhà phát triển và mã ứng dụng khách OAuth:
   1. Trong ngăn điều hướng, hãy tìm thư mục GoogleHomeAPISampleIOS rồi mở tệp Info.plist để chỉnh sửa.

3. Trong tệp Info.plist, hãy điền GIDClientID bằng mã ứng dụng khách OAuth (xem phần Thiết lập màn hình xin phép bằng OAuth), Cloud Project Number (Số dự án trên đám mây) tương ứng với dự án trên đám mây của bạn và GIDTeamID bằng Mã nhóm nhà phát triển của Apple của tài khoản nhà phát triển được dùng trong quá trình đăng ký OAuth.

4. Thêm tính năng App Attest:

   1. Trong ngăn điều hướng Xcode, hãy chọn tệp dự án GoogleHomeAPISampleIOS để chỉnh sửa cấu hình dự án.
   2. Nhấp vào thẻ Signing and Capabilities (Ký và các tính năng) ở trên cùng rồi chọn mục tiêu GoogleHomeAPISampleIOS ở bên trái trong phần TARGETS (MỤC TIÊU).
   3. Ngay bên dưới thẻ Signing and Capabilities (Ký và các tính năng), hãy nhấp vào + Capability rồi tìm kiếm App Attest.
   4. Nhấp vào App Attest để thêm. Nếu bạn không thấy tính năng này trong kết quả tìm kiếm, thì có thể dự án đã thêm tính năng này.

5. Thêm tính năng App Groups (Nhóm ứng dụng).

   

   

   1. Chuyển đến dự án GoogleHomeAPISampleIOS > mục tiêu GoogleHomeAPISampleIOS.
   2. Nhấp vào Signing & Capabilities (Ký và các tính năng) > + Capability (+ Tính năng).
   3. Chọn tính năng App Groups (Nhóm ứng dụng).
   4. Nhấp vào biểu tượng + trong phần App Groups (Nhóm ứng dụng) rồi thêm giá trị nhận dạng Nhóm ứng dụng cho ứng dụng mà bạn đã thêm trong cổng thông tin cho nhà phát triển của Apple.
   5. Lặp lại các bước này cho mục tiêu MatterAddDeviceExtension để thêm mục tiêu đó vào App Groups (Nhóm ứng dụng).

6. Cập nhật mã nhận dạng gói

   1. Để chạy và triển khai Ứng dụng mẫu trên phần cứng thành công bằng chứng chỉ nhà phát triển và hồ sơ cấp phép, bạn cần cung cấp một mã nhận dạng gói duy nhất. Giá trị nhận dạng này phải giống với giá trị nhận dạng được liên kết với thông tin xác thực Ứng dụng OAuth (xem ở trên).
   2. Trong ngăn điều hướng Xcode, hãy chọn tệp dự án GoogleHomeAPISampleIOS để chỉnh sửa cấu hình dự án.
   3. Nhấp vào thẻ Signing and Capabilities (Ký và các tính năng) ở trên cùng rồi chọn mục tiêu GoogleHomeAPISampleIOS ở bên trái trong phần TARGETS (MỤC TIÊU).
   4. Chọn trường Bundle Identifier (mã nhận dạng gói) trong phần Signing (Ký) rồi nhập giá trị nhận dạng riêng biệt cho Ứng dụng.
   5. Chọn hoặc cài đặt hồ sơ cấp phép liên quan đến gói đó có các quyền cần thiết.
   6. Lặp lại các bước này cho mục tiêu MatterAddDeviceExtension để nhập mã nhận dạng gói cho tiện ích và nhập hồ sơ cấp phép đã đăng ký của tiện ích đó.

7. Cập nhật giá trị nhận dạng nhóm ứng dụng đã đăng ký trong mã.

   1. Ứng dụng phải định cấu hình thực thể SDK để sử dụng giá trị nhận dạng Nhóm ứng dụng cho các tính năng như cấp phép thiết bị. Cập nhật ứng dụng để sử dụng Mã nhóm ứng dụng đã đăng ký trong Cổng thông tin nhà phát triển của Apple bằng cách tìm chuỗi HOME_API_TODO_ADD_APP_GROUP rồi thay thế từng thực thể bằng mã đó.

   Các cấu hình này được thực hiện trong các tệp sau:

   • GoogleHomeAPISampleIOS.swift khi SDK được khởi chạy.
   • RequestHandler.swift
   • CommissioningManager.swift

8. Định cấu hình phạm vi OAuth trong GoogleHomeAPISampleIOS.swift. Theo mặc định, mã nguồn Ứng dụng mẫu sử dụng phạm vi https://www.googleapis.com/auth/home.platform.v2. Nhiều tính năng trong Ứng dụng mẫu bị giới hạn bởi phạm vi home.platform.v2 và yêu cầu đối tác phê duyệt để truy cập. Để chạy Ứng dụng mẫu với phạm vi https://www.googleapis.com/auth/home.platform.selected.devices tiêu chuẩn, hãy mở GoogleHomeAPISampleIOS.swift rồi thay đổi homePlatformOAuthScope trong Home.configure thành HomePlatformOAuthScope.v1:

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