Tworzenie 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 utworzyć i uruchomić aplikację.

Wymagania wstępne

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

Aby utworzyć i zainstalować przykładową aplikację, musisz mieć komputer z zainstalowanym Xcode w wersji 15.3 lub nowszej.

Pobierz Xcode

Aby przetestować aplikację, musisz mieć:

  1. Konto Google.
  2. Apple ID zarejestrowany w programie Apple Developer Program aby generować pliki konfiguracyjne urządzeń fizycznych. Jeśli nie masz jeszcze takiego 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 w wersji 16.4 lub nowszej skonfigurowane za pomocą konta testowego.
  4. Sieć Wi-Fi.
  5. Hub Google, który obsługuje interfejsy Home API.
  6. Thread Border Router (TBR) jeśli Twoje urządzenie wymaga Thread, a Twój hub nie ma tej funkcji.
  7. Co najmniej 1 obsługiwany typ urządzenia.

Do programowania potrzebujesz komputera Mac, który spełnia te wymagania:

  • macOS Sonoma lub nowszy
  • Xcode 15.3 lub nowszy

Tworzenie plików konfiguracyjnych wdrożenia Apple

Po pierwsze, aplikacja wymaga włączenia funkcji App Attest. W związku z tym nie można jej wdrożyć na urządzeniach symulatora. Wymaga to utworzenia profilu aprowizacji z uprawnieniem App Attest.

Po drugie, do komunikacji między aplikacją a MatterExtension wymagane jest włączenie grup aplikacji. Wymaga to zarejestrowania identyfikatora grupy aplikacji.

Więcej informacji znajdziesz w dokumentacji Apple na temat tworzenia profilu aprowizacji dewelopera na temat profili aprowizacji.

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 on mieć na przykład format group.com.company.commissioning.
  2. Zarejestruj urządzenie testowe na koncie dewelopera account.

  3. Utwórz profil dla docelowej aplikacji.

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

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

    4. Utwórz profil aprowizacji dewelopera na potrzeby tworzenia aplikacji. Powiąż go z nowo utworzonym identyfikatorem aplikacji i wybranymi urządzeniami testowymi. Upewnij się, że masz certyfikat dewelopera, za pomocą którego możesz podpisać aplikację.

  4. Utwórz profil dla docelowej MatterExtension.

    1. Wybierz identyfikator pakietu aplikacji dla MatterExtension. Identyfikator powinien być dziedziczony z identyfikatora aplikacji. Może on mieć na przykład format com.company.HomeApiSample.MatterExtension.
    2. Zarejestruj identyfikator aplikacji. Gdy pojawi się prośba, dodaj funkcję App Group.
    3. Edytuj nowo utworzony identyfikator aplikacji i skonfiguruj funkcję App Groups , aby dodać zarejestrowany identyfikator grupy aplikacji utworzony w poprzednich krokach.
    4. Utwórz profil aprowizacji dewelopera dla MatterExtension.

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

Twoja aplikacja potrzebuje identyfikatora klienta OAuth, aby identyfikować się w backendzie uwierzytelniania Google. W przypadku aplikacji na iOS typ aplikacji z identyfikatorem klienta OAuth musi być skonfigurowany jako iOS. Aplikacja będzie też wywoływać interfejs 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, którego chcesz użyć do utworzenia danych logowania OAuth.
  2. Otwórz stronę Interfejsy API i usługi, klikając przycisk menu w lewym górnym rogu > Wyświetl wszystkie usługi > 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 zgody OAuth został już skonfigurowany, a jego stan publikacji to Testowanie, upewnij się, że konta testowe, których będziesz używać, są 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ę okienko Ekran zgody OAuth.
    2. Na stronie Informacje o aplikacji wpisz informacje zgodnie z instrukcjami wyświetlanymi na ekranie, a następnie kliknij Zapisz i kontynuuj. Wyświetli się okienko Zakresy.
    3. Nie musisz dodawać żadnych zakresów, więc kliknij Zapisz i kontynuuj. Wyświetli się okienko Użytkownicy testowi.
    4. Jeśli utworzysz wewnętrzny ekran zgody, musisz dodać użytkowników, aby przetestować dostęp do aplikacji. Kliknij Dodaj użytkowników. Wyświetli się okienko Dodaj użytkowników. Użytkownicy testowi mają uprawnienia do przyznawania uprawnień w Twojej aplikacji. W pustym polu dodaj co najmniej 1 adres e-mail konta Google, a następnie kliknij Dodaj.
    5. Kliknij Zapisz i kontynuuj. Wyświetli się okienko Podsumowanie.
    6. Sprawdź informacje na ekranie zgody OAuth, a następnie 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 dewelopera Apple. Pozostałe pola są opcjonalne i można je pozostawić puste.
    3. Kliknij UTWÓRZ i zanotuj utworzony identyfikator klienta lub 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 logowania autoryzacji sekcja.

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 z informacjami Home API kliknij WŁĄCZ.

Pobieranie kodu źródłowego

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

Otwórz miejsce, 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 Plik > Otwórz i wybierz GoogleHomeAPISampleIOS.xcodeproj w katalogu głównym sklonowanego repozytorium.

Dodawanie pakietu SDK do projektu

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

Tworzenie aplikacji

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

Zaloguj się teraz

Skonfiguruj projekt Xcode na potrzeby przykładowej aplikacji:

  1. Rozpakuj pobrany pakiet SDK do katalogu ThirdParty/GoogleHomeSDK względem katalogu głównego projektu.
  2. Skonfiguruj identyfikatory dewelopera i klienta OAuth:
    1. W panelu nawigacyjnym znajdź folder GoogleHomeAPISampleIOS i otwórz plik Info.plist do edycji.

  3. 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 dewelopera Apple Apple Developer Team ID konta dewelopera używanego podczas procesu rejestracji OAuth.

  4. Dodaj funkcję App Attest:

    1. W panelu nawigacyjnym Xcode wybierz plik projektu GoogleHomeAPISampleIOS, aby edytować konfigurację projektu.
    2. U góry kliknij kartę Podpisywanie i funkcje i po lewej stronie w sekcji CELE wybierz cel GoogleHomeAPISampleIOS.
    3. Tuż pod kartą Podpisywanie i funkcje kliknij + Funkcja i wyszukaj App Attest.
    4. Kliknij App Attest , aby dodać tę funkcję. Jeśli tej funkcji nie ma w wynikach wyszukiwania, być może została już dodana do projektu.

  5. Dodaj funkcję App Groups.

    Dodawanie grup aplikacji

    1. Otwórz projekt GoogleHomeAPISampleIOS > cel GoogleHomeAPISampleIOS.
    2. Kliknij Podpisywanie i funkcje > + Funkcja.
    3. Wybierz funkcję App Groups.
    4. Kliknij ikonę + w sekcji App Groups i dodaj identyfikator grupy aplikacji, który został dodany w portalu dla programistów Apple.
    5. Powtórz te czynności w przypadku celu MatterAddDeviceExtension , aby dodać go do App Groups.

  6. Zaktualizuj identyfikator pakietu.

    1. Aby pomyślnie uruchomić i wdrożyć przykładową aplikację na sprzęcie za pomocą certyfikatów dewelopera i profili aprowizacji, musisz podać unikalny identyfikator pakietu. Powinien to być ten sam identyfikator, który jest powiązany z danymi logowania klienta OAuth (patrz wyżej).
    2. W panelu nawigacyjnym Xcode wybierz plik projektu GoogleHomeAPISampleIOS, aby edytować konfigurację projektu.
    3. U góry kliknij kartę Podpisywanie i funkcje i po lewej stronie w sekcji CELE wybierz cel GoogleHomeAPISampleIOS.
    4. W sekcji Podpisywanie wybierz pole Identyfikator pakietu i wpisz unikalny identyfikator aplikacji.
    5. Wybierz lub zainstaluj profil aprowizacji powiązany z tym pakietem z wymaganymi uprawnieniami.
    6. Powtórz te czynności w przypadku celu MatterAddDeviceExtension, aby wpisać identyfikator pakietu rozszerzenia i zaimportować jego zarejestrowany profil aprowizacji.

  7. Zaktualizuj zarejestrowany identyfikator grupy aplikacji w kodzie.

    1. Aplikacja musi skonfigurować instancję pakietu SDK, aby korzystać z identyfikatora grupy aplikacji w przypadku funkcji takich jak wdrażanie urządzeń. Zaktualizuj aplikację, aby korzystała z identyfikatora grupy aplikacji zarejestrowanego w portalu Apple Developer. W tym celu 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

  8. Skonfiguruj zakres OAuth w GoogleHomeAPISampleIOS.swift. Domyślnie kod źródłowy przykładowej aplikacji używa zakresu https://www.googleapis.com/auth/home.platform.v2. Wiele funkcji w przykładowej aplikacji jest ograniczonych zakresem home.platform.v2 i wymaga zatwierdzenia przez partnera. Aby uruchomić przykładową aplikację ze standardowym zakresem https://www.googleapis.com/auth/home.platform.selected.devices, otwórz GoogleHomeAPISampleIOS.swift i zmień homePlatformOAuthScope w Home.configure na HomePlatformOAuthScope.v1:

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