Kompilowanie przykładowej aplikacji na iOS

Ta przykładowa aplikacja na iOS korzysta z interfejsów Google Home API. Z tego przewodnika dowiesz się, jak po raz pierwszy skompilować i uruchomić aplikację.

Wymagania wstępne

Upewnij się, że spełniasz minimalne wymagania dotyczące korzystania z interfejsów Home API na iOS.

Aby skompilować i zainstalować przykładową aplikację, potrzebujesz komputera z zainstalowanym Xcode w wersji 15.3 lub nowszej.

Pobieranie Xcode

Aby przetestować aplikację, musisz mieć:

  1. Konto Google.
  2. Identyfikator Apple ID zarejestrowany w programie Apple Developer do generowania plików konfiguracyjnych urządzeń fizycznych. Jeśli nie masz jeszcze konta, rejestracja wiąże się z dodatkowymi kosztami i może potrwać do 48 godzin.
  3. Urządzenie z iOS (nie symulator) z systemem iOS 16.4 lub nowszym skonfigurowane za pomocą konta testowego.
  4. sieć Wi-Fi,
  5. Hub Google, który obsługuje interfejsy Home API.
  6. router graniczny Thread, jeśli urządzenie wymaga Thread, a hub nie ma tej funkcji;
  7. Co najmniej 1 obsługiwany typ urządzenia.

Do tworzenia aplikacji potrzebujesz komputera Mac spełniającego te wymagania:

  • macOS Sonoma lub nowszy
  • Xcode 15.3 lub nowszy

Tworzenie plików konfiguracji wdrożenia Apple

Po pierwsze, aplikacja musi mieć włączoną funkcję App Attest. W związku z tym nie można go wdrożyć na urządzeniach symulacyjnych. Wymaga to utworzenia profilu obsługi administracyjnej z uprawnieniem App Attest.

Po drugie, wymaga to włączenia grup aplikacji w celu komunikacji między aplikacją a MatterExtension. Wymaga to zarejestrowania identyfikatora grupy aplikacji.

Więcej informacji o profilach administracyjnych znajdziesz w artykule Apple Tworzenie profilu administracyjnego na potrzeby programowania.

Poniżej znajdziesz minimalne kroki wymagane do wdrożenia aplikacji:

  1. Utwórz identyfikator grupy aplikacji, aby aplikacja mogła komunikować się z MatterExtension.
    1. Zaloguj się w portalu Apple Developer.
    2. Dodaj identyfikator grupy aplikacji. Może być na przykład sformatowany jako group.com.company.commissioning.
  2. Zarejestruj urządzenie testowe na koncie dewelopera.

  3. Utwórz profil dla miejsca docelowego aplikacji.

    1. Wybierz identyfikator pakietu aplikacji. Powinien być unikalny i opisowy. Może być na przykład sformatowany jako com.company.HomeApiSample. Ten identyfikator będzie używany w pozostałej części tej sekcji.
    2. Zarejestruj identyfikator aplikacji. Gdy pojawi się odpowiedni komunikat, dodaj funkcje App Attest i App Groups.

    3. Edytuj nowo utworzony identyfikator aplikacji i skonfiguruj funkcję App Groups (Grupy aplikacji), aby dodać zarejestrowany identyfikator grupy aplikacji.

    4. Utwórz profil udostępniania na potrzeby programowania aplikacji. Powiąż go z nowo utworzonym identyfikatorem aplikacji i wybranymi urządzeniami testowymi. Upewnij się, że masz certyfikat dewelopera, aby podpisać aplikację.

  4. Utwórz profil dla swojego MatterExtension.

    1. Wybierz identyfikator pakietu aplikacji dla MatterExtension. Identyfikator powinien być dziedziczony z identyfikatora aplikacji. Może być na przykład sformatowany jako com.company.HomeApiSample.MatterExtension.
    2. Zarejestruj identyfikator aplikacji. Gdy pojawi się odpowiedni komunikat, dodaj funkcję Grupa aplikacji.
    3. Edytuj nowo utworzony identyfikator aplikacji i skonfiguruj funkcję Grupy aplikacji, aby dodać zarejestrowany identyfikator grupy aplikacji utworzony w poprzednich krokach.
    4. Utwórz profil obsługi administracyjnej dewelopera dla MatterExtension.

Generowanie identyfikatora klienta OAuth i włączanie interfejsów Home API

Aplikacja potrzebuje identyfikatora klienta OAuth, aby identyfikować się w backendzie uwierzytelniania Google. W przypadku aplikacji na iOS typ aplikacji identyfikatora klienta OAuth musi być skonfigurowany jako iOS. Aplikacja będzie też wysyłać wywołania do interfejsu Home API. Aby włączyć tę funkcję, musisz włączyć interfejs API w projekcie Google Cloud.

Generowanie identyfikatora klienta OAuth

  1. W konsoli Google Cloud otwórz panel wyboru projektu i wybierz projekt, w którym chcesz utworzyć dane uwierzytelniające OAuth.
  2. Otwórz stronę Interfejsy API i usługi. W tym celu kliknij przycisk menu w lewym górnym rogu > Wyświetl wszystkie produkty > Interfejsy API i usługi.
  3. W menu nawigacyjnym kliknij Dane logowania.

  4. Jeśli nie masz jeszcze skonfigurowanego ekranu zgody w tym projekcie Google Cloud, pojawi się przycisk Skonfiguruj ekran zgody. W takim przypadku skonfiguruj ekran zgody, wykonując te czynności. Jeśli ekran akceptacji OAuth został już skonfigurowany, a jego stan publikowania to Testowanie, upewnij się, że konta testowe, których będziesz używać, zostały dodane do grupy Użytkownicy testowi. W przeciwnym razie przejdź do następnego kroku.

    1. W zależności od przypadku użycia wybierz Wewnętrzny lub Zewnętrzny, a następnie kliknij Utwórz. Wyświetli się panel Ekran zgody OAuth.
    2. Wpisz informacje na stronie z informacjami o aplikacji zgodnie z instrukcjami wyświetlanymi na ekranie, a potem kliknij Zapisz i kontynuuj. Wyświetli się panel Zakresy.
    3. Nie musisz dodawać żadnych zakresów, więc kliknij Zapisz i kontynuuj. Wyświetli się panel Użytkownicy testowi.
    4. Jeśli zdecydujesz się utworzyć wewnętrzny ekran zgody, musisz dodać użytkowników, którzy będą testować dostęp do Twojej aplikacji. Kliknij Dodaj użytkowników. Wyświetli się panel Dodaj użytkowników. Testerzy mają uprawnienia do przyznawania uprawnień w Twojej aplikacji. W pustym polu dodaj co najmniej 1 adres e-mail konta Google, a potem kliknij Dodaj.
    5. Kliknij Zapisz i kontynuuj. Wyświetli się panel Podsumowanie.
    6. Sprawdź informacje na ekranie zgody OAuth, a potem kliknij Wróć do panelu.

  5. W panelu menu po lewej stronie kliknij Dane logowania, aby utworzyć identyfikator klienta OAuth.

    Konfigurowanie ekranu OAuth

    1. Kliknij przycisk UTWÓRZ DANE LOGOWANIA i wybierz Identyfikator klienta OAuth.
      1. W sekcji Typ aplikacji wybierz iOS.
    2. Wpisz identyfikator pakietu z identyfikatorem aplikacji i identyfikator zespołu programistów Apple. Pozostałe pola są opcjonalne i można je pozostawić puste.
    3. Kliknij UTWÓRZ i zanotuj utworzony identyfikator klienta lub kliknij POBIERZ PLIK PLIST. Będzie on później używany do włączania funkcji przepływu uprawnień. Więcej informacji znajdziesz w sekcji Tworzenie danych uwierzytelniających.

Włączanie interfejsów Home API

Włącz dostęp do interfejsów Home API.

  1. Na karcie Interfejsy API i usługi kliknij Włączone interfejsy API i usługi.
  2. U góry strony kliknij WŁĄCZ INTERFEJSY API I USŁUGI.
  3. Wyszukaj HOME API i wybierz go.
  4. Na stronie szczegółów Home API kliknij WŁĄCZ.

Pobieranie kodu źródłowego

Kod źródłowy przykładowej aplikacji jest dostępny na GitHubie.

Przejdź do miejsca, w którym chcesz zapisać projekt, a następnie go sklonuj:

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

Aby wczytać projekt w Xcode, kliknij File (Plik) > Open (Otwórz) i wybierz GoogleHomeAPISampleIOS.xcodeproj w katalogu głównym sklonowanego repozytorium.

Konfigurowanie pakietu SDK

Aby skompilować projekt aplikacji przykładowej, musisz podać dodatkowe informacje. Obejmuje to lokalne dodanie plików struktury pakietu SDK, wypełnienie informacji o identyfikatorze konta dewelopera i wypełnienie identyfikatora klienta OAuth.

Tworzenie aplikacji

Aby pobrać pakiet Home APIs iOS SDK, musisz najpierw zalogować się w Google Home Developers.

Zaloguj się

Skonfiguruj projekt Xcode na potrzeby aplikacji przykładowej:

  1. W panelu nawigacji Xcode wybierz plik GoogleHomeAPISampleIOS, aby edytować konfigurację projektu.

    Konfigurowanie przykładowej aplikacji pakietu SDK

  2. U góry kliknij kartę Ogólne i po lewej stronie wybierz cel GoogleHomeAPISampleIOS.

  3. Przewiń w dół do sekcji Frameworki, biblioteki i treści osadzone. Powinny być widoczne 2 platformy interfejsu API Home.

  4. W kolumnie Osadź wybierz Osadź i podpisz dla GoogleHomeSDK.xcframework. Drugi framework, GoogleHomeTypes.xcframework, powinien mieć ustawienie Nie umieszczaj.

  5. U dołu listy kliknij ikonę +.

  6. Gdy pojawi się prośba, wyszukaj SafariServices.framework i kliknij Dodaj. Upewnij się, że w przypadku tego wpisu w kolumnie Osadź jest ustawiona wartość Nie osadzaj.

    Umieść i podpisz

  7. Kliknij MatterAddDeviceExtension w sekcji Cel, aby edytować cel.

  8. Przewiń w dół do sekcji Frameworki i biblioteki. Powinna się wyświetlić wartość GoogleHomeSDK.xcframework.

  9. W kolumnie Umieść wybierz Nie umieszczaj.

  10. Skonfiguruj identyfikatory dewelopera i klienta OAuth:

    1. W panelu nawigacyjnym znajdź folder GoogleHomeAPISampleIOS i otwórz plik Info.plist do edycji.

  11. W pliku Info.plist wypełnij pole GIDClientID identyfikatorem klienta OAuth (patrz sekcja Konfigurowanie zgody OAuth), pole Cloud Project Number numerem projektu w chmurze, a pole GIDTeamID identyfikatorem zespołu deweloperów Apple konta dewelopera użytego podczas procesu rejestracji OAuth.

  12. Dodaj funkcję potwierdzania aplikacji:

    1. W panelu nawigacyjnym Xcode wybierz GoogleHomeAPISampleIOSplik projektu, aby edytować konfigurację projektu.
    2. U góry kliknij kartę Podpisywanie i możliwości, a następnie po lewej stronie w sekcji CELE wybierz docelowy GoogleHomeAPISampleIOS.
    3. Tuż pod kartą Podpisywanie i możliwości kliknij + Możliwość i wyszukaj App Attest.
    4. Aby dodać usługę, kliknij App Attest. Jeśli ta funkcja nie jest dostępna w wyszukiwarce, być może została już dodana do projektu.

  13. Dodaj funkcję Grupy aplikacji.

    Dodawanie grup aplikacji

    1. Otwórz projekt GoogleHomeAPISampleIOS > GoogleHomeAPISampleIOS.
    2. Kliknij Podpisywanie i możliwości > + Możliwości.
    3. Wybierz funkcję Grupy aplikacji.
    4. Kliknij ikonę + w sekcji Grupy aplikacji i dodaj identyfikator grup aplikacji dla aplikacji, którą dodano w portalu Apple Developer.
    5. Powtórz te czynności w przypadku elementu docelowego MatterAddDeviceExtension, aby dodać go do grup aplikacji.

  14. Aktualizowanie identyfikatora pakietu

    1. Aby uruchomić i wdrożyć aplikację przykładową na sprzęcie za pomocą certyfikatów deweloperskich i profili administracyjnych, musisz podać unikalny identyfikator pakietu. Musi to być ten sam identyfikator, który jest powiązany z Twoimi danymi logowania klienta OAuth (patrz wyżej).
    2. W panelu nawigacyjnym Xcode wybierz GoogleHomeAPISampleIOSplik projektu, aby edytować konfigurację projektu.
    3. U góry kliknij kartę Podpisywanie i możliwości, a następnie po lewej stronie w sekcji CELE wybierz docelowy GoogleHomeAPISampleIOS.
    4. W sekcji Podpisywanie wybierz pole Identyfikator pakietu i wpisz unikalny identyfikator aplikacji.
    5. Wybierz lub zainstaluj profil administracyjny powiązany z tym pakietem, który zawiera wymagane uprawnienia.
    6. Powtórz te czynności w przypadku MatterAddDeviceExtension, aby wpisać identyfikator pakietu rozszerzenia i zaimportować zarejestrowany profil administracyjny.

  15. Zaktualizuj w kodzie zarejestrowany identyfikator grupy aplikacji.

    1. Aplikacja musi skonfigurować instancję pakietu SDK, aby korzystać z identyfikatora grupy aplikacji w przypadku funkcji takich jak wdrażanie urządzenia. Zaktualizuj aplikację, aby korzystała z identyfikatora grupy aplikacji zarejestrowanego w Apple Developer Portal. Wyszukaj ciąg znaków HOME_API_TODO_ADD_APP_GROUP i zastąp nim każdą instancję.

    Te konfiguracje są wprowadzane w tych plikach:

    • GoogleHomeAPISampleIOS.swift podczas inicjowania pakietu SDK.
    • RequestHandler.swift
    • CommissioningManager.swift