The Home APIs Developer Challenge is ON! Show us your skills for a chance to win exciting prizes.

Esta página foi traduzida pela API Cloud Translation.

Criar o app de exemplo para iOS

Este aplicativo de exemplo para iOS 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 no 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 do seguinte:

Uma Conta do Google
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, o registro vai gerar um custo adicional e pode levar até 48 horas para ser concluído.
Um dispositivo iOS (não um simulador) com iOS 16.4 ou mais recente configurado com a conta de teste.
Uma rede Wi-Fi.
Um hub do Google compatível com as APIs Home.
Um roteador de borda do Thread se o dispositivo exigir o Thread e o hub não tiver essa capacidade.
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 versões mais recentes

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

Primeiro, um app precisa ter o recurso App Attest ativado. Por isso, 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 ativar os grupos de apps para a comunicação entre o app e o MatterExtension. Para isso, registre um identificador de grupo de apps.

Para mais detalhes, consulte o artigo da Apple Criar um perfil de provisionamento de desenvolvimento sobre perfis de provisionamento.

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

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.
Registre seu dispositivo de teste na conta de desenvolvedor.
Crie um perfil para o destino do app.
1. Decida 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 em todo o restante desta seção.
2. Registre seu 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 Grupos de apps para adicionar o identificador do grupo de apps registrado.
4. Crie um perfil de provisionamento de desenvolvimento para o desenvolvimento do seu 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.
  - Se você ainda não criou um, consulte Criar certificados de ID de desenvolvedor para instruções.
Crie um perfil para seu destino MatterExtension.
1. Decida um identificador de pacote de aplicativo para seu MatterExtension. O identificador precisa ser herdado do identificador do app. Por exemplo, ele pode ser formatado como com.company.HomeApiSample.MatterExtension.
2. Registre seu 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 do 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

Seu 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 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

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.
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.
No menu de navegação, clique em Credenciais.
Se você ainda não configurou 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 permissão do OAuth já estiver 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 as 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 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 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.
No painel do menu à esquerda, clique em Credenciais para criar seu ID do cliente 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 FAZER O DOWNLOAD DA PLIST. Isso 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.

Na guia APIs e serviços, clique em APIs e serviços ativados.
Clique em ATIVAR APIS E SERVIÇOS na parte de cima da página.
Pesquise e selecione HOME API.
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 onde 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 precisa de mais informações 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 fazer o download do SDK do iOS das APIs Home, primeiro faça login no Google Home Developers.

Faça login agora!

Configure o projeto do Xcode para o app de exemplo:

No painel de navegação do Xcode, selecione o arquivo GoogleHomeAPISampleIOS para editar a configuração do projeto.
Clique na guia Geral na parte de cima e selecione o destino GoogleHomeAPISampleIOS à esquerda.
Role a tela para baixo até a seção Frameworks, bibliotecas e conteúdo incorporado. Os dois frameworks da API Home vão aparecer listados.
Na coluna Incorporar, selecione Incorporar e assinar para GoogleHomeSDK.xcframework. O outro framework, GoogleHomeTypes.xcframework, precisa ser deixado como Não incorporar.
Na parte de baixo da lista, clique no ícone +.
Quando solicitado, pesquise SafariServices.framework e clique em Adicionar. Verifique se a coluna Incorporar está definida como Não incorporar para esta entrada.
Clique no MatterAddDeviceExtension em Segmentação para editar a segmentação.
Role a tela para baixo até a seção Frameworks e bibliotecas. Você vai ver GoogleHomeSDK.xcframework listado.
Na coluna Incorporar, selecione Não incorporar.
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.
No arquivo Info.plist, preencha GIDClientID com o ID do cliente OAuth (consulte a seção Configurar o consentimento do OAuth), o Número do projeto do Cloud correspondente ao seu projeto do Cloud e o GIDTeamID com o ID da equipe de desenvolvedores da Apple da conta de desenvolvedor usada durante o processo de registro do OAuth.
Adicione 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 essa funcionalidade não aparecer na pesquisa, talvez o projeto já a tenha adicionado.
Adicione o recurso Grupos de apps.
1. Acesse o projeto GoogleHomeAPISampleIOS > destino GoogleHomeAPISampleIOS.
2. Clique em Assinatura e recursos > + Recurso.
3. Selecione o recurso Grupos de apps.
4. Clique no ícone + em Grupos de apps e adicione o identificador de grupos de apps do app que você adicionou no portal para desenvolvedores da Apple.
5. Repita essas etapas para o destino MatterAddDeviceExtension e adicione-o aos Grupos de apps.
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. Precisa ser o mesmo identificador associado às credenciais do cliente OAuth (veja 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 "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 e insira o identificador do pacote da extensão e importe o perfil de provisionamento registrado.
Importante: são necessários dois perfis de provisionamento. Um para GoogleHomeAPISampleIOS e outro para MatterAddDeviceExtension.
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 o provisionamento de dispositivos. Atualize o app para usar o ID do grupo de apps registrado no Apple Developer Portal. Para isso, pesquise a string HOME_API_TODO_ADD_APP_GROUP e substitua cada instância por ela.
Essas configurações são feitas nos seguintes arquivos:
- GoogleHomeAPISampleIOS.swift quando o SDK é inicializado.
- RequestHandler.swift
- CommissioningManager.swift