Criar o app de exemplo para iOS

Este aplicativo iOS de exemplo usa as APIs do Google Home. Use este guia para criar e executar o app pela primeira vez.

Pré-requisitos

Verifique se você atende aos requisitos mínimos para usar as APIs Home para iOS.

Para criar e instalar o app de exemplo, você precisa de um computador com a versão 15.3 ou mais recente do Xcode instalada.

Fazer o download do Xcode

Para testar o app, você vai precisar de:

  1. Uma Conta do Google registrada no EAP das APIs Home que serve como uma conta de teste.
  2. Um ID da Apple inscrito no Programa para desenvolvedores da Apple para gerar arquivos de configuração de dispositivos físicos. Se ainda não tiver sido criada, a inscrição vai gerar um custo extra e pode levar até 48 horas para ser concluída.
  3. Um dispositivo iOS (não um simulador) com iOS 16.4 ou versões mais recentes configurado com a conta de teste.
  4. Uma rede Wi-Fi.
  5. Um hub do Google compatível com as APIs do Google Home.
  6. Um roteador de borda do Thread, se o dispositivo exigir o Thread e a central não tiver essa capacidade.
  7. Pelo menos um tipo de dispositivo compatível.

Para desenvolvimento, você precisa de um Mac que atenda aos seguintes requisitos:

  • macOS Sonoma ou mais recente
  • Xcode 15.3 ou mais recente

Criar arquivos de configuração de implantação da Apple

Primeiro, o app exige que o recurso App Attest esteja ativado. Como resultado, ele não pode ser implantado em dispositivos de simulador. Para isso, você precisa criar um perfil de provisionamento com o direito App Attest.

Em segundo lugar, é necessário que os grupos de apps estejam ativados para a comunicação entre o app e o MatterExtension. Para isso, você precisa registrar um identificador de grupo de apps.

Para mais detalhes, consulte Criar um perfil de provisionamento de desenvolvimento na documentação da Apple sobre perfis de provisionamento.

Confira a seguir as etapas mínimas necessárias para implantar um app:

  1. Crie um identificador de grupo de apps para que seu app se comunique com o MatterExtension.
    1. Faça login no Portal para desenvolvedores da Apple.
    2. Adicione um identificador de grupo de apps. Por exemplo, ele pode ser formatado como group.com.company.commissioning.
  2. Registre seu dispositivo de teste na conta de desenvolvedor.

  3. Crie um perfil para o destino do app.

    1. Escolha um identificador de pacote de aplicativo para seu app. O identificador precisa ser exclusivo e descritivo. Por exemplo, ele pode ser formatado como com.company.HomeApiSample. Esse identificador será usado ao longo desta seção.
    2. Registre o ID do app. Quando solicitado, adicione o recurso App Attest e App Groups.

    3. Edite o ID do app recém-criado e configure o recurso Grupos de apps para adicionar o identificador de grupo de apps registrado.

    4. Crie um perfil de provisionamento de desenvolvimento para o desenvolvimento do app. Associe-o ao ID do app recém-criado e aos dispositivos de teste selecionados. Verifique se você tem um certificado de desenvolvedor para assinar o app.

  4. Crie um perfil para o público-alvo MatterExtension.

    1. Escolha um identificador de pacote de aplicativo para o MatterExtension. O identificador precisa ser herdado do identificador do app. Por exemplo, ele pode ser formatado como com.company.HomeApiSample.MatterExtension.
    2. Registre o ID do app. Quando solicitado, adicione o recurso Grupo de apps.
    3. Edite o ID do app recém-criado e configure o recurso Grupos de apps para adicionar o identificador de grupo de apps registrado criado nas etapas anteriores.
    4. Crie um perfil de provisionamento de desenvolvimento para MatterExtension.

Gerar o ID do cliente OAuth e ativar as APIs do Google Home

O app precisa de um ID do cliente OAuth para se identificar no back-end de autenticação do Google. Para iOS e apps, o tipo de aplicativo do ID do cliente do OAuth precisa ser configurado como iOS. O app também fará chamadas para a API Home. Para ativar essa funcionalidade, a API precisa estar ativada no projeto Google Cloud.

Gerar o ID do cliente OAuth

  1. No console do Google Cloud, acesse o painel do seletor de projetos e selecione o projeto que você quer usar para criar credenciais do OAuth.
  2. Acesse a página "APIs e serviços" clicando no botão de menu no canto superior esquerdo > Ver todos os produtos > APIs e serviços.
  3. No menu de navegação, clique em Credenciais.

  4. Se você ainda não tiver configurado a tela de consentimento para este projeto do Google Cloud, o botão Configurar tela de consentimento vai aparecer. Nesse caso, configure a tela de consentimento usando o procedimento a seguir. Se a tela de consentimento do OAuth já tiver sido configurada e o status de publicação for Teste, verifique se as contas de teste que você vai usar foram adicionadas ao grupo Usuários de teste. Caso contrário, avance para a próxima etapa.

    1. Dependendo do seu caso de uso, selecione Interno ou Externo e clique em Criar. O painel Tela de consentimento do OAuth é exibido.
    2. Insira informações na página de informações do app de acordo com as instruções na tela e clique em Salvar e continuar. O painel "Scopes" é exibido.
    3. Não é necessário adicionar escopos. Clique em Salvar e continuar. O painel Test users é exibido.
    4. Se você optou por criar uma tela de consentimento interna, adicione usuários para testar o acesso ao app. Clique em Adicionar usuários. O painel Adicionar usuários é exibido. Os usuários de teste têm o privilégio de conceder permissões no app. No campo vazio, adicione um ou mais endereços de e-mail da Conta do Google e clique em Adicionar.
    5. Clique em Salvar e continuar. O painel Summary é exibido.
    6. Revise as informações da tela de consentimento OAuth e clique em Voltar ao painel.

  5. No painel do menu à esquerda, clique em Credenciais para criar o ID do cliente OAuth.

    Configurar a tela OAuth

    1. Clique no botão CREATE CREDENTIALS e selecione ID do cliente do OAuth.
      1. Em Tipo de aplicativo, selecione iOS.
    2. Insira o ID do pacote com o identificador do app e o ID da equipe do desenvolvedor da Apple. Os outros campos são opcionais e podem ser deixados em branco.
    3. Clique em CRIAR e anote o ID do cliente ou o DOWNLOAD PLIST criado. Ele será usado mais tarde para ativar a funcionalidade do fluxo de permissões. Para mais informações, consulte a seção Criar credenciais de autorização.

Ativar as APIs Home

Ative o acesso às APIs do Google Home.

  1. Na guia APIs e serviços, clique em APIs e serviços ativados.
  2. Clique em ATIVAR APIS E SERVIÇOS na parte de cima da página.
  3. Procure e selecione o HOME API.
  4. Na página de detalhes da API Home, clique em ATIVAR.

Faça o download do código-fonte

O código-fonte do app de exemplo está disponível no GitHub.

Navegue até o local em que você quer salvar o projeto e clone-o:

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

Para carregar o projeto no Xcode, clique em File > Open e selecione GoogleHomeAPISampleIOS.xcodeproj na raiz do repositório clonado.

configurar o SDK

O projeto de app de exemplo exige algumas informações adicionais para ser criado. Isso inclui adicionar localmente os arquivos do SDK Framework, preencher as informações do identificador da sua conta de desenvolvedor e preencher o ID do cliente OAuth.

Criar o app

Para fazer o download do SDK das APIs Home para iOS, primeiro você precisa fazer login no Google Home Developers.

Faça login agora!

Configure o projeto do Xcode para o app de exemplo:

  1. No painel de navegação do Xcode, selecione o arquivo GoogleHomeAPISampleIOS para editar a configuração do projeto.

    Configurar o app de exemplo do SDK

  2. Clique na guia Geral na parte de cima e selecione o alvo GoogleHomeAPISampleIOS no lado esquerdo.

  3. Role para baixo até a seção Frameworks, bibliotecas e conteúdo incorporado. Os dois frameworks da API Home vão aparecer listados.

  4. Na coluna Inserir, selecione Inserir e assinar para GoogleHomeSDK.xcframework. O outro framework, GoogleHomeTypes.xcframework, precisa ser deixado como Não incorporar.

  5. Na parte de baixo da lista, clique no ícone +.

  6. Quando solicitado, pesquise SafariServices.framework e clique em adicionar. Verifique se a coluna Inserir está definida como Não inserir para essa entrada.

    Incorporar e assinar

  7. Clique em MatterAddDeviceExtension em Destino para editar o destino.

  8. Role para baixo até a seção Frameworks e bibliotecas. Você vai encontrar GoogleHomeSDK.xcframework listado.

  9. Na coluna Incorporar, selecione Não incorporar.

  10. Configure os IDs de cliente do desenvolvedor e do OAuth:

    1. No painel de navegação, procure a pasta GoogleHomeAPISampleIOS e abra o arquivo Info.plist para edição.

  11. No arquivo Info.plist, preencha o GIDClientID com seu ID de cliente OAuth (consulte a seção Configurar o consentimento do OAuth) e o GIDTeamID com o ID da equipe de desenvolvedores da Apple da conta de desenvolvedor usada durante o processo de registro do OAuth.

  12. Configure o sistema de build:

    Adicionar flags de vinculador

    1. No painel de navegação do Xcode, selecione o arquivo de projeto GoogleHomeAPISampleIOS para editar a configuração do projeto.
    2. Clique na guia Build Settings na parte de cima e selecione o destino GoogleHomeAPISampleIOS no lado esquerdo, na seção TARGETS.
    3. Pesquise Outras flags do vinculador e adicione duas entradas:
      • -lc++
      • -ObjC

  13. Adicionar o recurso App Attest:

    1. No painel de navegação do Xcode, selecione o arquivo de projeto GoogleHomeAPISampleIOS para editar a configuração do projeto.
    2. Clique na guia Assinatura e recursos na parte de cima e selecione o alvo GoogleHomeAPISampleIOS no lado esquerdo, na seção TARGETS.
    3. Logo abaixo da guia "Assinatura e recursos", clique em + Recurso e pesquise App Attest.
    4. Clique em App Attest para adicionar. Se esse recurso não estiver na pesquisa, é possível que o projeto já o tenha adicionado.

  14. Adicione o capability Grupos de apps.

    Adicionar grupos de apps

    1. Acesse o projeto GoogleHomeAPISampleIOS > destino GoogleHomeAPISampleIOS.
    2. Clique em Assinatura e recursos > + Recurso.
    3. Selecione o capability Grupos de apps.
    4. Clique no ícone + em App Groups e adicione o identificador de grupos de apps que você adicionou no portal do desenvolvedor da Apple.
    5. Repita essas etapas para o destino MatterAddDeviceExtension para adicioná-lo aos Grupos de apps.

  15. Atualizar o identificador do pacote

    1. Para executar e implantar o app de exemplo em hardware usando seus certificados de desenvolvedor e perfis de provisionamento, você precisa fornecer um identificador de pacote exclusivo. Esse é o mesmo identificador associado às suas credenciais de cliente OAuth (consulte acima).
    2. No painel de navegação do Xcode, selecione o arquivo de projeto GoogleHomeAPISampleIOS para editar a configuração do projeto.
    3. Clique na guia Assinatura e recursos na parte de cima e selecione o alvo GoogleHomeAPISampleIOS no lado esquerdo, na seção TARGETS.
    4. Selecione o campo "Bundle Identifier" na seção Signing e insira o identificador exclusivo do aplicativo.
    5. Selecione ou instale o perfil de provisionamento relacionado a esse pacote com os direitos necessários.
    6. Repita essas etapas para o destino MatterAddDeviceExtension para inserir o identificador do pacote da extensão e importar o perfil de provisionamento registrado.

  16. Atualize o identificador do grupo de apps registrado no código.

    1. O aplicativo precisa configurar a instância do SDK para usar o identificador do grupo de apps em recursos como a ativação do dispositivo. Atualize o app para usar o ID do grupo de apps registrado no Portal para desenvolvedores da Apple pesquisando a string HOME_API_TODO_ADD_APP_GROUP e substituindo cada instância por ela.

    Essas configurações são feitas nos seguintes arquivos:

    • GoogleHomeAPISampleIOS.swift quando o SDK é inicializado.
    • RequestHandler.swift
    • CommissioningManager.swift