Crea l'app di esempio per iOS

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

Prerequisiti

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

Per creare e installare l'app di esempio, devi avere un computer con Xcode versione 15.3 o successive.

Scarica Xcode

Per testare l'app, ti servono:

  1. Un Account Google.
  2. Un ID Apple registrato all'Apple Developer Program per generare file di configurazione del dispositivo fisico. Se non è già stato creato, la registrazione comporta un costo aggiuntivo e il completamento 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 dispositivo richiede Thread e l'hub non ha questa funzionalità.
  7. Almeno un tipo di dispositivo supportato.

Per lo sviluppo, devi avere 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 che la funzionalità App Attest sia abilitata. Di conseguenza, non può essere sottoposta a deployment sui dispositivi simulatore. Per questo, devi creare un profilo di provisioning con l'autorizzazione App Attest.

In secondo luogo, è necessario che i gruppi di app siano abilitati per la comunicazione tra l'app e MatterExtension. Per questo, devi registrare un identificatore del gruppo di app.

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

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

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

  3. Crea un profilo per il target dell'app.

    1. Decidi un identificatore pacchetto dell'applicazione per la tua app. L'identificatore deve essere univoco e descrittivo. Ad esempio, potrebbe essere formattato come com.company.HomeApiSample. Questo identificatore verrà utilizzato nel resto di questa sezione.
    2. Registra l'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 di sviluppo per lo sviluppo dell'app. Associalo all'ID app appena creato e ai dispositivi di test selezionati. Assicurati di avere un certificato sviluppatore per firmare l'app.

  4. Crea un profilo per il target MatterExtension.

    1. Scegli un identificatore pacchetto dell'applicazione per MatterExtension. L'identificatore deve essere ereditato dall'identificatore dell'app. Ad esempio, potrebbe essere formattato come com.company.HomeApiSample.MatterExtension.
    2. Registra l'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 di sviluppo per MatterExtension.

Generare l'ID client OAuth e abilitare 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 dell'ID client OAuth deve essere configurato come iOS. L'app effettuerà anche chiamate all'API Home. Per abilitare questa funzionalità, l'API deve essere abilitata nel progetto Google Cloud.

Generare 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 per il consenso per questo progetto Google Cloud, viene visualizzato il pulsante Configura schermata per il consenso. In questo caso, configura la schermata per il consenso utilizzando la seguente procedura. Se la schermata per il 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 tuo caso d'uso, seleziona Interno o Esterno, e quindi 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 alcun ambito, 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 dell'Account Google, quindi fai clic su Aggiungi.
    5. Fai clic su Salva e continua. Viene visualizzato il riquadro Riepilogo.
    6. Esamina 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 l'ID client OAuth.

    Configura la schermata 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 dello 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 SCARICA PLIST. Verrà utilizzato in un secondo momento per abilitare la funzionalità del flusso di autorizzazioni. Per saperne di più, consulta la sezione Creare credenziali di autorizzazione.

Abilitare le API Home

Abilita 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 selezionala.
  4. Nella pagina dei dettagli di API Home, fai clic su ABILITA.

Scaricare il codice sorgente

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

Scegli dove 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 directory root del repository clonato.

Aggiungere l'SDK al progetto

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

Creare l'app

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

Accedi ora.

Configura il progetto Xcode per l'app di esempio:

  1. Decomprimi l'SDK scaricato nella directory ThirdParty/GoogleHomeSDK relativa alla directory root del progetto.
  2. Configura gli ID client sviluppatore e OAuth:
    1. Nel riquadro di navigazione, cerca la cartella GoogleHomeAPISampleIOS e apri il file Info.plist per modificarlo.

  3. Nel file Info.plist, completa il campo GIDClientID con l'ID client OAuth (vedi la sezione Configurare il consenso OAuth), il numero del progetto cloud corrispondente al tuo progetto cloud e il campo GIDTeamID con l'ID team dello sviluppatore Apple dell'account sviluppatore utilizzato durante la procedura di registrazione OAuth.

  4. Aggiungi la funzionalità App Attest:

    1. Nel riquadro di navigazione di Xcode, seleziona il file di 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 TARGETS.
    3. Appena sotto la scheda Firma e funzionalità, fai clic su + Funzionalità e cerca App Attest.
    4. Fai clic su App Attest per aggiungere. Se questa funzionalità non è presente nella ricerca, è possibile che sia già stata aggiunta al progetto.

  5. 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 dei gruppi di app per la tua app che hai aggiunto nel portale per sviluppatori Apple.
    5. Ripeti questi passaggi per il target MatterAddDeviceExtension per aggiungerlo a Gruppi di app.

  6. Aggiorna l'identificatore pacchetto

    1. Per eseguire e sottoporre a deployment correttamente l'app di esempio sull'hardware utilizzando i certificati sviluppatore e i profili di provisioning, devi fornire un identificatore pacchetto univoco. Questo deve essere lo stesso identificatore associato alle credenziali client OAuth (vedi sopra).
    2. Nel riquadro di navigazione di Xcode, seleziona il file di 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 TARGETS.
    4. Seleziona il campo Identificatore bundle nella sezione Firma e inserisci l'identificatore univoco dell'applicazione.
    5. Seleziona o installa il profilo di provisioning correlato a questo bundle con le autorizzazioni richieste.
    6. Ripeti questi passaggi per il target MatterAddDeviceExtension per inserire l'identificatore pacchetto dell'estensione e importare il profilo di provisioning registrato.

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

    1. L'applicazione è necessaria per configurare l'istanza dell'SDK in modo da utilizzare l'identificatore del gruppo di app per funzionalità come il provisioning dei dispositivi. Aggiorna l'app in modo che utilizzi l'ID gruppo di app registrato nel portale per sviluppatori Apple cercando la stringa HOME_API_TODO_ADD_APP_GROUP e sostituendo ogni istanza con l'ID.

    Queste configurazioni vengono eseguite nei seguenti file:

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