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

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

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

Đảm bảo rằng bạn đáp ứng các yêu cầu tối thiểu để sử dụng Home API 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. Tài khoản Google.
2. Một Apple ID đã đăng ký tham gia 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 được 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ợ Home API.
6. Biểu tượng Thread Border Router (TBR) nếu thiết bị của bạn cần có Thread và trung tâm của bạn không có chức 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, ứng dụng cần bật tính năng App Attest. Do đó, bạn không thể triển khai thư viện này cho các thiết bị mô phỏng. Để làm việc này, bạn cần tạo một hồ sơ cấp phép có quyền App Attest.

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

Để biết thêm thông tin, 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 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ã nhận dạng nhóm ứng dụng. Ví dụ: mã 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 hồ sơ cho mục tiêu ứng dụng.

   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 phải là duy nhất và mang tính mô tả. Ví dụ: mã này có thể được định dạng là com.company.HomeApiSample. Giá trị nhận dạng này sẽ được dùng trong phần còn lại của mục này.
   2. Đăng ký Mã ứng dụng. Khi được nhắc, hãy thêm chức năng App Attest (Chứng thực ứng dụng) và App Groups (Nhóm ứng dụng).

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

   4. Tạo 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ơ đó 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ỉ Mã nhận dạng nhà phát triển để biết hướng dẫn.

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

   1. Chọn một mã nhận dạng gói ứng dụng cho MatterExtension của bạn. Giá trị nhận dạng phải được kế thừa từ giá trị nhận dạng ứng dụng. Ví dụ: tệp 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 chức năng Nhóm ứng dụng.
   3. Chỉnh sửa Mã ứng dụng mới tạo và định cấu hình chức năng Nhóm ứng dụng để 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 hồ sơ cấp phép phát triển cho MatterExtension.

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

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

Tạo mã ứng dụng OAuth

1. Trong Google Cloud Console, hãy chuyển đến trang tổng quan của bộ 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 Đị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 bằng quy trình sau. Nếu bạn đã định cấu hình màn hình xin phép OAuth và trạng thái xuất bản của màn hình này là Đang 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 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 Nội bộ hoặc Bên ngoài, sau đó nhấp vào Tạo. Ngăn Màn hình xin phép bằng OAuth sẽ xuất hiện.
   2. Nhập thông tin trên trang Thông tin ứng dụng theo hướng dẫn trên màn hình, sau đó nhấp vào Lưu và tiếp tục. Ngăn Phạm vi sẽ xuất hiện.
   3. Bạn không cần thêm phạm vi nào, vì vậy, hãy nhấp vào Lưu và tiếp tục. Ngăn 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 Thêm người dùng. Ngăn 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 địa chỉ email của Tài khoản Google Account, rồi nhấp vào Thêm.
   5. Nhấp vào 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 Quay lại trang tổng quan.

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

   

   

   1. Nhấp vào nút CREATE CREDENTIALS (TẠO THÔNG TIN ĐĂNG NHẬP) rồi chọn OAuth client ID (Mã ứng dụng OAuth).
      1. Trong mục loại ứng dụng, hãy chọn iOS.
   2. Nhập Mã nhận dạng gói cùng với giá trị nhận dạng ứng dụng và Mã nhóm nhà phát triển Apple. Các trường khác là không bắt buộc và có thể để trống.
   3. Nhấp vào TẠO và ghi lại Mã ứng dụng khách đã tạo hoặc TẢI PLIST XUỐNG. Hàm này sẽ được dùng sau để 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.

Bật Home API

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

1. Trong thẻ API và dịch vụ, hãy nhấp vào API và dịch vụ đã bật.
2. Nhấp vào BẬT API VÀ DỊCH VỤ ở đầu trang.
3. Tìm HOME API rồi chọn.
4. Trong trang thông tin chi tiết về Home API, hãy nhấp vào 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 đó nhân bản 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 (Tệp) > Open (Mở) rồi chọn GoogleHomeAPISampleIOS.xcodeproj trong thư mục gốc của kho lưu trữ được sao chép.

Thêm SDK vào dự án

Dự án Ứng dụng mẫu cần thêm một số thông tin để tạo bản dựng. Việc này bao gồm việc thêm các tệp Khung SDK trên thiết 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 OAuth.

Tạo ứng dụng

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

Đă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 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 mã ứng dụng khách OAuth vào GIDClientID (xem phần Thiết lập sự đồng ý OAuth), 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 cùng với Mã nhóm nhà phát triển 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 chức 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à chức 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à chức năng), hãy nhấp vào + Capability (+ Chức năng) rồi tìm App Attest (Chứng thực ứng dụng).
   4. Nhấp vào App Attest (Chứng thực ứng dụng) để thêm. Nếu không tìm thấy chức năng này, thì có thể dự án đã thêm chức năng này.

5. Thêm chức 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 chức năng) > + Capability (+ Chức năng).
   3. Chọn chức năng 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 Nhóm ứng dụng.

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

   1. Để chạy và triển khai thành công ứng dụng mẫu trên phần 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 của bạn (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à chức 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 cần 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ư uỷ quyền 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 cho nhà phát triển của Apple bằng cách tìm chuỗi HOME_API_TODO_ADD_APP_GROUP và thay thế từng thực thể bằng chuỗi đó.

   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 của Ứ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 được kiểm soát bằng phạm vi home.platform.v2 và cần có sự phê duyệt của đối tác để truy cập. Để chạy Ứng dụng mẫu với phạm vi https://www.googleapis.com/auth/home.platform.selected.devices chuẩn, hãy mở GoogleHomeAPISampleIOS.swift và thay đổi homePlatformOAuthScope trong Home.configure thành HomePlatformOAuthScope.v1:

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