Criar o app de exemplo para iOS

Este aplicativo de exemplo para iOS usa as APIs 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 o Xcode versão 15.3 ou mais recente instalado.

Baixar o Xcode

Para testar o app, você precisa de:

  1. Uma Conta do Google.
  2. Um ID Apple inscrito no Programa para desenvolvedores da Apple para gerar arquivos de configuração de dispositivos físicos. Se ainda não tiver sido criado, a inscrição terá um custo adicional e poderá levar até 48 horas para ser concluída.
  3. Um dispositivo iOS (não um simulador) com o iOS 16.4 ou mais recente configurado com a conta de teste.
  4. Uma rede Wi-Fi.
  5. Um hub do Google que ofereça suporte às APIs Home.
  6. Um roteador de borda do Thread, caso o dispositivo exija o Thread e o hub não tenha essa capacidade.
  7. Pelo menos um tipo de dispositivo compatível.

Para o 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, um app exige que o recurso App Attest esteja ativado. Como resultado, ele não pode ser implantado em dispositivos simuladores. Isso exige que você crie 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 a MatterExtension. Isso exige que você registre um identificador de grupo de apps.

Para mais detalhes, consulte Criar um perfil de provisionamento de desenvolvimento em perfis de provisionamento da Apple.

A seguir, descrevemos as etapas mínimas necessárias para implantar um app:

  1. Crie um identificador de grupo de apps para que ele se comunique com a 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. Decida um identificador do pacote de aplicativos para seu app. O identificador precisa ser exclusivo e descritivo. Por exemplo, ele pode ser formatado como com.company.HomeApiSample. Esse identificador será usado no restante desta seção.
    2. Registre o ID do app. Quando solicitado, adicione os recursos App Attest e App Groups.

    3. Edite o ID do app recém-criado e configure o recurso App Groups 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 destino da MatterExtension.

    1. Decida um identificador do pacote de aplicativos para sua 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 App Group.
    3. Edite o ID do app recém-criado e configure o recurso App Groups 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 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 de ID do cliente OAuth precisa ser configurado como iOS. O app também fará chamadas para a API Home. Para ativar essa funcionalidade, a API precisa ser 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 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 configurou a tela de permissão para esse projeto do Google Cloud, o botão Configurar tela de permissão vai aparecer. Nesse caso, configure a tela de permissão usando o procedimento a seguir. Se a tela de permissão 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 permissão 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 "Escopos" é exibido.
    3. Não é necessário adicionar escopos. Clique em Salvar e continuar. O painel Usuários de teste é exibido.
    4. Se você optou por criar uma tela de permissão 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 seu 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 Resumo é exibido.
    6. Revise as informações da tela de permissão 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 do OAuth

    1. Clique no botão CRIAR CREDENCIAIS e selecione ID do cliente 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 criado ou BAIXAR PLIST. Ele será usado mais tarde para ativar a funcionalidade de 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 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. Pesquise a HOME API e selecione-a.
  4. Na página de detalhes da API Home, clique em ATIVAR.

Fazer o download do código-fonte

O código -fonte do app de exemplo está disponível no GitHub (link em inglês).

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 Arquivo > Abrir e selecione GoogleHomeAPISampleIOS.xcodeproj na raiz do repositório clonado.

Adicionar o SDK ao projeto

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

Criar o app

Para baixar o SDK das APIs Home para iOS, primeiro você precisa fazer login nos desenvolvedores do Google Home.

Fazer login agora

Configure seu projeto do Xcode para o app de exemplo:

  1. Descompacte o SDK baixado no diretório ThirdParty/GoogleHomeSDK em relação ao diretório raiz do projeto.
  2. Configure os IDs do cliente de desenvolvedor e OAuth:
    1. No painel de navegação, procure a pasta GoogleHomeAPISampleIOS e abra o arquivo Info.plist para edição.

  3. No arquivo Info.plist, preencha o GIDClientID com o ID do cliente OAuth (consulte a seção Configurar o consentimento do OAuth), o Número do projeto na nuvem correspondente ao projeto na nuvem e o GIDTeamID com o ID da equipe de desenvolvedores da Apple da conta de desenvolvedor usada durante o processo de registro do OAuth.

  4. 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 destino GoogleHomeAPISampleIOS no lado esquerdo, na seção "DESTINOS".
    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 estiver ausente na pesquisa, é possível que o projeto já o tenha adicionado.

  5. Adicione o recurso App Groups.

    Adicionar grupos de apps

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

  6. Atualizar o identificador do pacote

    1. Para executar e implantar o app de exemplo no hardware usando seus certificados de desenvolvedor e perfis de provisionamento, você precisa fornecer um identificador de pacote exclusivo. Ele precisa ser o mesmo identificador associado às credenciais do 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 destino GoogleHomeAPISampleIOS no lado esquerdo, na seção "DESTINOS".
    4. Selecione o campo "Identificador do pacote" na seção Assinatura 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.

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

    1. O aplicativo é necessário para configurar a instância do SDK para usar o identificador do grupo de apps para recursos como o provisionamento de dispositivos. 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