Crea l'app di esempio per iOS

Questa applicazione di esempio per iOS utilizza le API Google Home. Utilizza questa guida per compilare e eseguire l'app per la prima volta.

Prerequisiti

Assicurati di soddisfare i requisiti minimi per utilizzare le API Home per iOS.

Per compilare e installare l'app di esempio, devi disporre di un computer su cui è installata la versione 15.3 o successiva di Xcode.

Scaricare Xcode

Per testare l'app, devi avere:

  1. Un Account Google registrato nel programma EAP delle API Home che funge da account di test.
  2. Un ID Apple registrato al programma Apple Developer per generare file di configurazione dei dispositivi fisici. Se non è già stata creata, la registrazione comporta un costo aggiuntivo e può richiedere fino a 48 ore.
  3. Un dispositivo iOS (non un simulatore) con iOS 16.4 o versioni successive configurato con l'account di test.
  4. Una rete Wi-Fi.
  5. Un hub Google che supporta le API Home.
  6. Un router di confine Thread se il tuo dispositivo richiede Thread e il tuo hub non supporta questa funzionalità.
  7. Almeno un tipo di dispositivo supportato.

Per lo sviluppo, devi disporre di un Mac che soddisfi i seguenti requisiti:

  • macOS Sonoma o versioni successive
  • Xcode 15.3 o versioni successive

Creare file di configurazione del deployment Apple

Innanzitutto, un'app richiede l'attivazione della funzionalità App Attest. Di conseguenza, non può essere implementato su dispositivi simulatore. Per farlo, devi creare un profilo di provisioning con il diritto App Attest.

In secondo luogo, richiede l'attivazione dei gruppi di app per la comunicazione tra l'app e MatterExtension. Per farlo, devi registrare un identificatore di gruppo di app.

Per maggiori dettagli, consulta la sezione Creare un profilo di provisioning per lo sviluppo della documentazione di Apple sui profili di provisioning.

Di seguito sono descritti i passaggi minimi necessari per eseguire il deployment di un'app:

  1. Crea un identificatore di gruppo di app per consentire alla tua app di comunicare con il MatterExtension.
    1. Accedi al portale per sviluppatori Apple.
    2. Aggiungi un identificatore gruppo di app. Ad esempio, potrebbe essere formattata come group.com.company.commissioning.
  2. Registra il dispositivo di test all'account sviluppatore.

  3. Crea un profilo per la destinazione dell'app.

    1. Scegli un identificatore del bundle di applicazioni per la tua app. L'identificatore deve essere univoco e descrittivo. Ad esempio, potrebbe essere formattata come com.company.HomeApiSample. Questo identificatore verrà utilizzato nel resto di questa sezione.
    2. Registra il tuo ID app. Quando richiesto, aggiungi le funzionalità App Attest e Gruppi di app.

    3. Modifica l'ID app appena creato e configura la funzionalità Gruppi di app per aggiungere l'identificatore del gruppo di app registrato.

    4. Crea un profilo di provisioning per lo sviluppo per lo sviluppo delle tue app. Associalo all'ID app appena creato e ai dispositivi di test selezionati. Assicurati di disporre di un certificato sviluppatore per firmare l'app.

  4. Crea un profilo per il tuo target MatterExtension.

    1. Scegli un identificatore del bundle di applicazioni per il tuo MatterExtension. L'identificatore deve essere ereditato dall'identificatore dell'app. Ad esempio, potrebbe essere formattato come com.company.HomeApiSample.MatterExtension.
    2. Registra il tuo ID app. Quando richiesto, aggiungi la funzionalità Gruppo di app.
    3. Modifica l'ID app appena creato e configura la funzionalità Gruppi di app per aggiungere l'identificatore del gruppo di app registrato creato nei passaggi precedenti.
    4. Crea un profilo di provisioning per lo sviluppo per MatterExtension.

Genera l'ID client OAuth e abilita le API Home

La tua app ha bisogno di un ID client OAuth per identificarsi nel backend di autenticazione di Google. Per iOS e le app, il tipo di applicazione ID client OAuth deve essere configurato come iOS. L'app effettuerà anche chiamate all'API Home. Per attivare questa funzionalità, l'API deve essere abilitata nel progetto Google Cloud.

Genera l'ID client OAuth

  1. Nella console Google Cloud, vai alla dashboard del selettore di progetti e seleziona il progetto che vuoi utilizzare per creare le credenziali OAuth.
  2. Vai alla pagina API e servizi facendo clic sul pulsante del menu in alto a sinistra > Visualizza tutti i prodotti > API e servizi.
  3. Nel menu di navigazione, fai clic su Credenziali.

  4. Se non hai ancora configurato la schermata del consenso per questo progetto Google Cloud, viene visualizzato il pulsante Configura schermata del consenso. In questo caso, configura la schermata del consenso utilizzando la procedura riportata di seguito. Se la schermata di consenso OAuth è già stata configurata e il relativo stato di pubblicazione è Test, assicurati che gli account di test che utilizzerai siano aggiunti al gruppo Utenti di test. In caso contrario, vai al passaggio successivo.

    1. A seconda del caso d'uso, seleziona Interno o Esterno e poi fai clic su Crea. Viene visualizzato il riquadro Schermata per il consenso OAuth.
    2. Inserisci le informazioni nella pagina Informazioni sull'app seguendo le istruzioni sullo schermo, quindi fai clic su Salva e continua. Viene visualizzato il riquadro ambiti.
    3. Non devi aggiungere ambiti, quindi fai clic su Salva e continua. Viene visualizzato il riquadro Utenti di test.
    4. Se hai scelto di creare una schermata per il consenso interna, devi aggiungere utenti per testare l'accesso alla tua app. Fai clic su Aggiungi utenti. Viene visualizzato il riquadro Aggiungi utenti. Gli utenti di test hanno il privilegio di concedere autorizzazioni nella tua app. Nel campo vuoto, aggiungi uno o più indirizzi email di Account Google, quindi fai clic su Aggiungi.
    5. Fai clic su Salva e continua. Viene visualizzato il riquadro Riepilogo.
    6. Rivedi le informazioni della schermata per il consenso OAuth, quindi fai clic su Torna alla dashboard.

  5. Nel riquadro del menu a sinistra, fai clic su Credenziali per creare il tuo ID client OAuth.

    Schermata Configura OAuth

    1. Fai clic sul pulsante CREA CREDENZIALI e seleziona ID client OAuth.
      1. In Tipo di applicazione, seleziona iOS.
    2. Inserisci l'ID pacchetto con l'identificatore dell'app e l'ID team sviluppatore Apple. Gli altri campi sono facoltativi e possono essere lasciati vuoti.
    3. Fai clic su CREA e prendi nota dell'ID client creato o su SCARICA PLIST. Verrà utilizzato in un secondo momento per attivare la funzionalità di flusso delle autorizzazioni. Per ulteriori informazioni, consulta la sezione Creare le credenziali di autorizzazione.

Abilita le API Home

Attiva l'accesso alle API Home.

  1. Nella scheda API e servizi, fai clic su API e servizi abilitati.
  2. Fai clic su ABILITA API E SERVIZI nella parte superiore della pagina.
  3. Cerca HOME API e selezionalo.
  4. Nella pagina dei dettagli dell'API Home, fai clic su ABILITA.

Scarica il codice sorgente

Il codice sorgente per l'app di esempio è disponibile su GitHub.

Vai alla posizione in cui vuoi salvare il progetto, quindi clonalo:

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

Per caricare il progetto su Xcode, fai clic su File > Apri e seleziona GoogleHomeAPISampleIOS.xcodeproj nella radice del repository clonato.

Configura l'SDK

Il progetto dell'app di esempio richiede alcune informazioni aggiuntive per la compilazione. Sono inclusi l'aggiunta locale dei file del framework SDK, la compilazione delle informazioni sull'identificatore dell'account sviluppatore e la compilazione dell'ID client OAuth.

Crea l'app

Per scaricare l'SDK iOS delle API Home, devi prima aver eseguito l'accesso a Google Home Developers.

Accedi ora.

Configura il progetto Xcode per l'app di esempio:

  1. Nel riquadro di navigazione di Xcode, seleziona il file GoogleHomeAPISampleIOS per modificare la configurazione del progetto.

    Configura l'app di esempio dell'SDK

  2. Fai clic sulla scheda Generali in alto e seleziona il target GoogleHomeAPISampleIOS a sinistra.

  3. Scorri verso il basso fino alla sezione Framework, librerie e contenuti incorporati. Dovresti vedere elencati i due framework dell'API Home.

  4. Nella colonna Incorpora, seleziona Incorpora e firma per GoogleHomeSDK.xcframework. L'altro framework, GoogleHomeTypes.xcframework, deve essere lasciato su Non incorporare.

  5. Nella parte inferiore dell'elenco, fai clic sull'icona +.

  6. Quando richiesto, cerca SafariServices.framework e fai clic su Aggiungi. Assicurati che la colonna Incorpora sia impostata su Non incorporare per questa voce.

    Incorpora e firma

  7. Fai clic su MatterAddDeviceExtension in Target per modificarne il target.

  8. Scorri verso il basso fino alla sezione Framework e librerie. Dovresti vedere GoogleHomeSDK.xcframework nell'elenco.

  9. Nella colonna Incorpora, seleziona Non incorporare.

  10. Configura gli ID client sviluppatore e OAuth:

    1. Nel riquadro di navigazione, cerca la cartella GoogleHomeAPISampleIOS e apri il file Info.plist per modificarlo.

  11. Nel file Info.plist, compila GIDClientID con il tuo ID client OAuth (vedi la sezione Configurare il consenso OAuth) e GIDTeamID con l'ID team sviluppatore Apple dell'account sviluppatore utilizzato durante la procedura di registrazione OAuth.

  12. Configura il sistema di compilazione:

    Aggiungi flag del linker

    1. Nel riquadro di navigazione di Xcode, seleziona il file del progetto GoogleHomeAPISampleIOS per modificare la configurazione del progetto.
    2. Fai clic sulla scheda Impostazioni di compilazione in alto e seleziona il target GoogleHomeAPISampleIOS a sinistra nella sezione TARGET.
    3. Cerca Altri flag del linker e aggiungi due voci:
      • -lc++
      • -ObjC

  13. Aggiungi la funzionalità di attestazione dell'app:

    1. Nel riquadro di navigazione di Xcode, seleziona il file del progetto GoogleHomeAPISampleIOS per modificare la configurazione del progetto.
    2. Fai clic sulla scheda Firma e funzionalità in alto e seleziona il target GoogleHomeAPISampleIOS a sinistra nella sezione TARGET.
    3. Sotto la scheda Firma e funzionalità, fai clic su + Funzionalità e cerca App Attest.
    4. Fai clic su App Attest per aggiungerla. Se questa funzionalità non è presente nella ricerca, il progetto potrebbe averla già aggiunta.

  14. Aggiungi la funzionalità Gruppi di app.

    Aggiungere gruppi di app

    1. Vai al progetto GoogleHomeAPISampleIOS > target GoogleHomeAPISampleIOS.
    2. Fai clic su Firma e funzionalità > + Funzionalità.
    3. Seleziona la funzionalità Gruppi di app.
    4. Fai clic sull'icona + in Gruppi di app e aggiungi l'identificatore Gruppi di app per la tua app che hai aggiunto nell'Apple Developer Portal.
    5. Ripeti questi passaggi per il target MatterAddDeviceExtension per aggiungerlo ai gruppi di app.

  15. Aggiorna l'identificatore del pacchetto

    1. Per eseguire ed eseguire il deployment dell'app di esempio sull'hardware utilizzando i certificati dello sviluppatore e i profili di provisioning, devi fornire un identificatore del bundle univoco. Deve essere lo stesso identificatore associato alle tue credenziali client OAuth (vedi sopra).
    2. Nel riquadro di navigazione di Xcode, seleziona il file del progetto GoogleHomeAPISampleIOS per modificare la configurazione del progetto.
    3. Fai clic sulla scheda Firma e funzionalità in alto e seleziona il target GoogleHomeAPISampleIOS a sinistra nella sezione TARGET.
    4. Seleziona il campo Identificatore del pacchetto nella sezione Firma e inserisci l'identificatore univoco dell'applicazione.
    5. Seleziona o installa il profilo di provisioning relativo al bundle con i diritti richiesti.
    6. Ripeti questi passaggi per il target MatterAddDeviceExtension per inserire l'identificatore del bundle per l'estensione e importare il relativo profilo di provisioning registrato.

  16. Aggiorna l'identificatore del gruppo di app registrato nel codice.

    1. L'applicazione deve configurare l'istanza dell'SDK in modo da utilizzare l'identificatore del gruppo di app per funzionalità come la messa in servizio del dispositivo. Aggiorna l'app in modo da utilizzare l'ID gruppo di app registrato nel Portale sviluppatori Apple cercando la stringa HOME_API_TODO_ADD_APP_GROUP e sostituendo ogni istanza con essa.

    Queste configurazioni vengono create nei seguenti file:

    • GoogleHomeAPISampleIOS.swift quando l'SDK viene inizializzato.
    • RequestHandler.swift
    • CommissioningManager.swift