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 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 ID Apple đã đăng ký trong 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 kiểm thử.
  4. Mạng Wi-Fi.
  5. Một trung tâm Google hỗ trợ API Home.
  6. Một bộ định tuyến biên theo giao thức Thread nếu thiết bị của bạn yêu cầu giao thức 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 (Chứng thực ứng dụng). Do đó, bạn không thể triển khai ứng dụng này cho các thiết bị trình mô phỏng. Điều này yêu cầu bạn phải 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. Điều này yêu cầu bạn phải đăng ký một giá trị nhận dạng nhóm ứng dụng.

Để biết thêm thông tin 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 trên 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 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ị 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ột 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ụ: giá trị 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 để 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ị kiểm thử đã chọn. Đảm bảo bạn có chứng chỉ nhà phát triển để ký ứng dụng.

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

    1. Quyết định một mã nhận dạng gói ứng dụng cho MatterExtension. Giá trị nhận dạng phải được kế thừa từ giá trị nhận dạng ứng dụng. Ví dụ: giá trị 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 trong 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 OAuth và bật API Home

Ứng dụng của bạn cần có mã ứng dụng OAuth để xác định chính ứng dụng đó cho 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 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 API Home. Để 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 bảng điều khiển Cloud, hãy chuyển đến trang tổng quan bộ chọn dự án rồi chọn dự án mà bạn muốn sử 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 màn hình xin phép bằng OAuth đã được định cấu hình và trạng thái phát hành là Đang kiểm thử, hãy đảm bảo rằng các tài khoản kiểm thử mà bạn sẽ sử dụng được thêm vào nhóm Người dùng kiểm thử. 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, và rồi 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, rồi 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 bất kỳ 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 kiểm thử 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. 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 kiểm thử 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 Thêm.
    5. Nhấp vào Lưu và tiếp tục. Ngăn Tóm tắt sẽ xuất hiện.
    6. Xem lại thông tin 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.

    Thiết lập màn hình OAuth

    1. Nhấp vào nút TẠO THÔNG TIN XÁC THỰC rồi chọn Mã ứng dụng OAuth.
      1. Trong phần loại ứng dụng, hãy chọn iOS.
    2. Nhập Mã nhận dạng gói bằng giá trị nhận dạng ứng dụng và Apple Developer Mã nhóm. 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 rồi ghi lại Mã ứng dụng khách đã tạo hoặc TẢI PLIST XUỐNG. Mã này sẽ được sử 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 section.

Bật API Home

Bật quyền truy cập vào API Home.

  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 kiếm HOME API rồi chọn API đó.
  4. Trên trang chi tiết Home API, hãy nhấp vào BẬT.

Tải mã nguồn xuống

Bạn có thể xem mã nguồn cho Ứng dụng mẫu 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 trong thư mục gốc của 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 bản dựng. Thông tin này bao gồm việc thêm cục bộ các tệp Khung SDK, đ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 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 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 OAuth (xem phần Thiết lập màn hình xin phép bằng OAuth), Số dự án trên đám mây tương ứng với dự án trên đám mây 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 sử dụng trong quá trình đăng ký OAuth.

  4. Thêm tính năng Chứng thực ứng dụng:

    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à 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à tính năng), hãy nhấp vào + Capability rồi tìm kiế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 tính năng này bị thiếu 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).

    Thêm 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à 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 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 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. Đây phải là giá trị nhận dạng 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à 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 (Giá trị nhận dạng gói) trong phần Signing (Ký) rồi nhập giá trị nhận dạng duy nhấ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ư xác nhận dịch vụ 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 kiếm chuỗi HOME_API_TODO_ADD_APP_GROUP và 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