Créer l'application exemple iOS

Cet exemple d'application iOS utilise les API Google Home. Utilisez ce guide pour créer et exécuter l'application pour la première fois.

Prérequis

Assurez-vous de disposer des conditions minimales requises pour utiliser les API Home pour iOS.

Pour compiler et installer l'application exemple, vous avez besoin d'un ordinateur sur lequel la version 15.3 ou ultérieure de Xcode est installée.

Télécharger Xcode

Pour tester l'application, vous avez besoin des éléments suivants:

  1. Un compte Google enregistré dans le programme EAP des API Home servant de compte de test.
  2. Un ID Apple enregistré dans le programme de développement Apple pour générer des fichiers de configuration d'appareils physiques. Si ce n'est pas déjà fait, l'inscription entraîne des frais supplémentaires et peut prendre jusqu'à 48 heures.
  3. Un appareil iOS (pas un simulateur) équipé d'iOS 16.4 ou version ultérieure configuré avec le compte de test.
  4. Un réseau Wi-Fi
  5. Un hub Google compatible avec les API Home.
  6. Un routeur de bordure Thread si votre appareil nécessite Thread et que votre hub ne dispose pas de cette fonctionnalité.
  7. Au moins un type d'appareil compatible

Pour le développement, vous avez besoin d'un Mac qui répond aux exigences suivantes:

  • macOS Sonoma ou version ultérieure
  • Xcode 15.3 ou version ultérieure

Créer des fichiers de configuration de déploiement Apple

Tout d'abord, une application doit avoir activé la fonctionnalité App Attest (Attestation d'application). Par conséquent, il ne peut pas être déployé sur des appareils de simulation. Pour ce faire, vous devez créer un profil de provisionnement avec le droit d'accès App Attest.

Deuxièmement, les groupes d'applications doivent être activés pour la communication entre l'application et le MatterExtension. Pour ce faire, vous devez enregistrer un identifiant de groupe d'applications.

Pour en savoir plus, consultez la section Créer un profil de provisionnement de développement d'Apple sur les profils de provisionnement.

Vous trouverez ci-dessous les étapes minimales requises pour déployer une application:

  1. Créez un identifiant de groupe d'applications pour que votre application puisse communiquer avec MatterExtension.
    1. Connectez-vous au portail des développeurs Apple.
    2. Ajoutez un identifiant de groupe d'applications. Par exemple, il peut être au format group.com.company.commissioning.
  2. Enregistrez votre appareil de test dans le compte du développeur.

  3. Créez un profil pour la cible de votre application.

    1. Choisissez un identifiant de bundle d'application pour votre application. Cet identifiant doit être unique et descriptif. Par exemple, il peut être au format com.company.HomeApiSample. Cet identifiant sera utilisé tout au long de cette section.
    2. Enregistrez votre ID d'application. Lorsque vous y êtes invité, ajoutez les fonctionnalités App Attest (Attestation d'application) et App Groups (Groupes d'applications).

    3. Modifiez l'ID d'application nouvellement créé et configurez la fonctionnalité Groupes d'applications pour ajouter l'identifiant de groupe d'applications enregistré.

    4. Créez un profil de configuration de développement pour le développement de votre application. Associez-le à votre ID d'application nouvellement créé et aux appareils de test sélectionnés. Assurez-vous de disposer d'un certificat de développeur pour signer l'application.

  4. Créez un profil pour votre cible MatterExtension.

    1. Choisissez un identifiant de bundle d'application pour votre MatterExtension. L'identifiant doit être hérité de l'identifiant de l'application. Par exemple, il peut être au format com.company.HomeApiSample.MatterExtension.
    2. Enregistrez votre ID d'application. Lorsque vous y êtes invité, ajoutez la fonctionnalité Groupe d'applications.
    3. Modifiez l'ID d'application nouvellement créé et configurez la fonctionnalité Groupes d'applications pour ajouter l'identifiant de groupe d'applications enregistré créé aux étapes précédentes.
    4. Créez un profil de provisionnement de développement pour MatterExtension.

Générer l'ID client OAuth et activer les API Home

Votre application a besoin d'un ID client OAuth pour s'identifier auprès du backend d'authentification de Google. Pour iOS et les applications, le type d'application de l'ID client OAuth doit être configuré sur iOS. L'application appelle également l'API Home. Pour activer cette fonctionnalité, l'API doit être activée dans le projet Google Cloud.

Générer l'ID client OAuth

  1. Dans la console Google Cloud, accédez au tableau de bord du sélecteur de projet, puis sélectionnez le projet que vous souhaitez utiliser pour créer des identifiants OAuth.
  2. Accédez à la page "API et services" en cliquant sur le bouton de menu en haut à gauche > Afficher tous les produits > API et services.
  3. Dans le menu de navigation, cliquez sur Identifiants.

  4. Si vous n'avez pas encore configuré votre écran de consentement pour ce projet Google Cloud, le bouton Configurer l'écran de consentement s'affiche. Dans ce cas, configurez votre écran de consentement en suivant la procédure ci-dessous. Si votre écran de consentement OAuth a déjà été configuré et que son état de publication est Test, assurez-vous que les comptes de test que vous utiliserez sont ajoutés au groupe Utilisateurs tests. Sinon, passez à l'étape suivante.

    1. Selon votre cas d'utilisation, sélectionnez Interne ou Externe, puis cliquez sur Créer. Le volet Écran de consentement OAuth s'affiche.
    2. Saisissez les informations sur la page Informations sur l'application en suivant les instructions à l'écran, puis cliquez sur Enregistrer et continuer. Le volet "Champs d'application" s'affiche.
    3. Vous n'avez pas besoin d'ajouter de champs d'application. Cliquez donc sur Enregistrer et continuer. Le volet Utilisateurs de test s'affiche.
    4. Si vous avez choisi de créer un écran d'autorisation interne, vous devez ajouter des utilisateurs pour tester l'accès à votre application. Cliquez sur Ajouter des utilisateurs. Le volet Ajouter des utilisateurs s'affiche. Les utilisateurs tests ont le droit d'accorder des autorisations dans votre application. Dans le champ vide, ajoutez une ou plusieurs adresses e-mail de compte Google, puis cliquez sur Ajouter.
    5. Cliquez sur Enregistrer et continuer. Le volet Summary (Récapitulatif) s'affiche.
    6. Vérifiez les informations de votre écran de consentement OAuth, puis cliquez sur Retour au tableau de bord.

  5. Dans le panneau de menu de gauche, cliquez sur Identifiants pour créer votre ID client OAuth.

    Écran de configuration OAuth

    1. Cliquez sur le bouton CREATE CREDENTIALS (CRÉER DES IDENTIFIANTS), puis sélectionnez OAuth client ID (ID client OAuth).
      1. Sous Type d'application, sélectionnez iOS.
    2. Saisissez l'ID du bundle avec l'identifiant de votre application et l'ID d'équipe du développeur Apple. Les autres champs sont facultatifs et peuvent être laissés vides.
    3. Cliquez sur CREATE (CRÉER), puis notez l'ID client ou le DOWNLOAD PLIST (TÉLÉCHARGER LA PLIST) créé. Il sera utilisé plus tard pour activer la fonctionnalité de flux d'autorisations. Pour en savoir plus, consultez la section Créer des identifiants d'autorisation.

Activer les API Home

Activez l'accès aux API Home.

  1. Dans l'onglet API et services, cliquez sur API et services activés.
  2. Cliquez sur ACTIVER DES API ET DES SERVICES en haut de la page.
  3. Recherchez HOME API, puis sélectionnez-le.
  4. Sur la page d'informations de l'API Home, cliquez sur ACTIVER.

Télécharger le code source

Le code source de l'application exemple est disponible sur GitHub.

Accédez à l'emplacement où vous souhaitez enregistrer le projet, puis clonez-le:

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

Pour charger le projet dans Xcode, cliquez sur File > Open (Fichier > Ouvrir), puis sélectionnez GoogleHomeAPISampleIOS.xcodeproj à la racine du dépôt cloné.

Configurez le SDK

Pour compiler l'exemple d'application, vous devez fournir des informations supplémentaires. Cela inclut l'ajout local des fichiers du framework du SDK, le remplissage des informations d'identification de votre compte de développeur et le remplissage de votre ID client OAuth.

Développer l'application

Pour télécharger le SDK iOS des API Home, vous devez d'abord être connecté à Google Home Developers.

Se connecter

Configurez votre projet Xcode pour l'application exemple:

  1. Dans le volet de navigation Xcode, sélectionnez le fichier GoogleHomeAPISampleIOS pour modifier la configuration du projet.

    Configurer l'exemple d'application du SDK

  2. Cliquez sur l'onglet Général en haut de la page, puis sélectionnez la cible GoogleHomeAPISampleIOS à gauche.

  3. Faites défiler la page vers le bas jusqu'à la section Frameworks, bibliothèques et contenu intégré. Les deux frameworks d'API Home devraient s'afficher.

  4. Dans la colonne Intégration, sélectionnez Intégrer et signer pour GoogleHomeSDK.xcframework. L'autre framework, GoogleHomeTypes.xcframework, doit rester défini sur Ne pas intégrer.

  5. En bas de la liste, cliquez sur l'icône +.

  6. Lorsque vous y êtes invité, recherchez SafariServices.framework, puis cliquez sur Ajouter. Assurez-vous que la colonne Intégration est définie sur Ne pas intégrer pour cette entrée.

    Intégrer et signer

  7. Cliquez sur MatterAddDeviceExtension sous Cible pour modifier sa cible.

  8. Faites défiler la page vers le bas jusqu'à la section Frameworks et bibliothèques. GoogleHomeSDK.xcframework doit s'afficher.

  9. Dans la colonne Intégrer, sélectionnez Ne pas intégrer.

  10. Configurez les ID client du développeur et OAuth:

    1. Dans le volet de navigation, recherchez le dossier GoogleHomeAPISampleIOS et ouvrez le fichier Info.plist pour le modifier.

  11. Dans le fichier Info.plist, renseignez GIDClientID avec votre ID client OAuth (voir la section Configurer le consentement OAuth) et GIDTeamID avec l'ID d'équipe de développeur Apple du compte de développeur utilisé lors du processus d'enregistrement OAuth.

  12. Configurez le système de compilation:

    Ajouter des indicateurs de l'éditeur de liens

    1. Dans le volet de navigation Xcode, sélectionnez le fichier de projet GoogleHomeAPISampleIOS pour modifier la configuration du projet.
    2. Cliquez sur l'onglet Build Settings (Paramètres de compilation) en haut de la page, puis sélectionnez la cible GoogleHomeAPISampleIOS sur la gauche, sous la section "TARGETS" (CIBLES).
    3. Recherchez Other Linker Flags (Autres indicateurs de l'éditeur de liens) et ajoutez deux entrées :
      • -lc++
      • -ObjC

  13. Ajoutez la capacité d'attestation d'application:

    1. Dans le volet de navigation Xcode, sélectionnez le fichier de projet GoogleHomeAPISampleIOS pour modifier la configuration du projet.
    2. Cliquez sur l'onglet Signature et fonctionnalités en haut de la page, puis sélectionnez la cible GoogleHomeAPISampleIOS sur la gauche, sous la section "CIBLES".
    3. Juste sous l'onglet "Signature et fonctionnalités", cliquez sur + Fonctionnalité, puis recherchez App Attest.
    4. Cliquez sur App Attest (Attestation d'application) pour l'ajouter. Si cette fonctionnalité est manquante dans la recherche, il est possible que le projet l'ait déjà ajoutée.

  14. Ajoutez la fonctionnalité Groupes d'applications.

    Ajouter des groupes d'applications

    1. Accédez au projet GoogleHomeAPISampleIOS > cible GoogleHomeAPISampleIOS.
    2. Cliquez sur Signature et fonctionnalités > + Fonctionnalité.
    3. Sélectionnez la fonctionnalité Groupes d'applications.
    4. Cliquez sur l'icône + sous App Groups (Groupes d'applications) et ajoutez l'identifiant de groupe d'applications de votre application que vous avez ajouté sur le portail pour les développeurs Apple.
    5. Répétez ces étapes pour la cible MatterAddDeviceExtension afin de l'ajouter aux groupes d'applications.

  15. Mettre à jour l'identifiant du bundle

    1. Pour exécuter et déployer correctement l'application exemple sur du matériel à l'aide de vos certificats de développeur et de vos profils de provisionnement, vous devez fournir un identifiant de bundle unique. Il doit s'agir du même identifiant associé à vos identifiants client OAuth (voir ci-dessus).
    2. Dans le volet de navigation Xcode, sélectionnez le fichier de projet GoogleHomeAPISampleIOS pour modifier la configuration du projet.
    3. Cliquez sur l'onglet Signature et fonctionnalités en haut de la page, puis sélectionnez la cible GoogleHomeAPISampleIOS sur la gauche, sous la section "CIBLES".
    4. Sélectionnez le champ "Bundle Identifier" (Identifiant de groupe) dans la section Signing (Signature) et saisissez l'identifiant unique de l'application.
    5. Sélectionnez ou installez le profil de provisionnement associé à ce lot avec les droits d'accès requis.
    6. Répétez ces étapes pour la cible MatterAddDeviceExtension afin de saisir l'identifiant du bundle pour l'extension et d'importer son profil de provisionnement enregistré.

  16. Mettez à jour l'identifiant du groupe d'applications enregistré dans le code.

    1. L'application doit configurer l'instance du SDK pour qu'elle utilise l'identifiant du groupe d'applications pour des fonctionnalités telles que la mise en service de l'appareil. Mettez à jour l'application pour qu'elle utilise l'ID de groupe d'applications enregistré dans le portail pour les développeurs Apple. Pour ce faire, recherchez la chaîne HOME_API_TODO_ADD_APP_GROUP et remplacez-la par celle-ci.

    Ces configurations sont effectuées dans les fichiers suivants:

    • GoogleHomeAPISampleIOS.swift lorsque le SDK est initialisé.
    • RequestHandler.swift
    • CommissioningManager.swift