Usar a API ARCore no Google Cloud

Selecione a plataforma: Android Unity (AR Foundation) iOS

Os recursos do ARCore, como a API Geospatial e o Cloud Anchors, usam a API ARCore hospedada no Google Cloud. Ao usar esses recursos, o aplicativo usa credenciais para acessar o serviço da API ARCore.

Neste guia de início rápido, descrevemos como configurar o aplicativo para que ele possa se comunicar com o serviço da API ARCore hospedado no Google Cloud.

Criar um novo projeto do Google Cloud ou usar um atual

Se você já tiver um projeto, selecione-o.

Acessar o seletor de projetos

Se você não tiver um projeto do Google Cloud, crie um.

Criar um projeto

Ativar a API ARCore

Para usar a API ARCore, ela precisa ser ativada no seu projeto.

Ativar a API ARCore

Configurar um método de autorização

Um aplicativo do Unity pode se comunicar com a API ARCore com dois métodos de autorização diferentes: autorização sem chave, que é o método recomendado, e autorização por chave de API.

• No Android, a autorização sem chave usa uma combinação do nome do pacote do aplicativo e a impressão digital da chave de assinatura para autorizar o app.

  No iOS, a autorização sem chave usa um token assinado para controlar o acesso à API. Esse método exige que você tenha um servidor para assinar os tokens e controlar o acesso à API.

• Uma chave de API é uma string que identifica um projeto do Google Cloud. Em geral, as chaves de API não são consideradas seguras, já que podem ser acessadas pelos clientes. Considere usar a autorização sem chave para se comunicar com a API ARCore.

Sem chave

Para autorizar o app usando a autenticação sem chave, crie IDs do cliente OAuth 2.0.

Determinar impressões digitais da chave de assinatura

Um ID do cliente OAuth 2.0 usa a impressão digital da chave de assinatura do app para identificar o app.

Importante :é comum assinar seu aplicativo com diferentes chaves de assinatura. É necessário criar um ID do cliente para cada chave de assinatura que você planeja usar. Normalmente, são uma chave de assinatura de depuração e uma(s) chave(s) de assinatura de lançamento.

Como conseguir a impressão digital de assinatura de depuração

Ao executar ou depurar o projeto, as Ferramentas do SDK do Android assinam automaticamente o app com um certificado de depuração gerado.

Use o comando a seguir para encontrar a impressão digital do certificado de depuração.

Mac/Linux

keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore

Windows

keytool -list -v -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

O utilitário keytool solicita que você insira uma senha para o keystore. A senha padrão para o keystore de depuração é android. O utilitário keytool imprime a impressão digital no terminal. Exemplo:

   Certificate fingerprint: SHA1: <strong>DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Como conseguir uma impressão digital de assinatura de um keystore

Se você tiver um arquivo de keystore, use o utilitário keytool para determinar a impressão digital.

keytool -list -v -alias your-key-name -keystore path-to-production-keystore

O utilitário keytool imprime a impressão digital no terminal. Exemplo:

   Certificate fingerprint: SHA1: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Como conseguir a chave de assinatura do app na Assinatura de apps do Google Play

Ao usar a Assinatura de apps do Google Play, o Google gerencia a chave de assinatura do seu app e a usa para assinar seus APKs. Essa chave precisa ser usada para a impressão digital de assinatura.

1. Na página "Assinatura de apps" do Google Play Console, role até Certificado da chave de assinatura do app.
2. Use a impressão digital do certificado SHA-1.

Criar IDs do cliente OAuth 2.0

Para cada chave de assinatura aplicável das etapas anteriores, crie um ID do cliente OAuth 2.0 nas credenciais do seu projeto do Google Cloud.

• No Google Cloud, abra a página "Credenciais".

  Credenciais

• Clique em Criar credenciais e selecione ID do cliente OAuth no menu.

• Preencha os campos obrigatórios da seguinte forma:

  • Tipo de aplicativo: escolha Android.
  • Package name: use o nome do pacote declarado no AndroidManifest.xml.
  • Impressão digital do certificado SHA-1: use a impressão digital da etapa anterior.

• Pressione Criar.

Incluir bibliotecas necessárias

1. Inclua com.google.android.gms:play-services-auth:16+ nas dependências do app.

2. Se você estiver usando a minificação de código, adicione-a ao arquivo build.gradle do app:

   buildTypes {
     release {
       ...
       proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
     }
   }
   

3. Adicione o código abaixo ao arquivo proguard-rules.pro do seu app:

   -keep class com.google.android.gms.common.** { *; }
   -keep class com.google.android.gms.location.** { *; }
   -keep class com.google.android.gms.auth.** { *; }
   -keep class com.google.android.gms.tasks.** { *; }
   

Agora seu app está configurado para usar a autenticação sem chave.

Sem chave

O ARCore é compatível com a autorização de chamadas de API no iOS usando um (token JSON da Web). O token precisa ser assinado por uma conta de serviço do Google.

Para gerar tokens para iOS, você precisa ter um endpoint no seu servidor que atenda aos seguintes requisitos:

• Seu mecanismo de autorização precisa proteger o endpoint.

• O endpoint precisa gerar um novo token todas as vezes, para que:

  • Cada usuário recebe um token exclusivo.
  • Os tokens não expiram imediatamente.

Criar uma conta de serviço e uma chave de assinatura

Siga estas etapas para criar uma conta de serviço do Google e uma chave de assinatura:

1. No Google Cloud, abra a página "Credenciais".
   Credenciais
2. Clique em Criar credenciais > Conta de serviço.
3. Em Detalhes da conta de serviço, digite um nome para a nova conta e clique em Criar.
4. Na página "Permissões da conta de serviço", acesse o menu suspenso Selecionar um papel. Selecione Contas de serviço > Criador de token de conta de serviço e clique em Continuar.
5. Na página Conceda aos usuários acesso a essa conta de serviço, clique em "Concluído".
6. Na página Credenciais, encontre a seção "Contas de serviço" e clique no nome da conta que você acabou de criar.
7. Na página Detalhes da conta de serviço, role para baixo até a seção "Chaves" e selecione Adicionar chave > Criar nova chave.

8. Selecione JSON como o tipo de chave e clique em Criar.

   Isso faz o download de um arquivo JSON que contém a chave privada na sua máquina. Armazene o arquivo de chave JSON salvo em um local seguro.

   Observação: este arquivo contém uma chave privada que não pode ser exposta ao público. Não o confirme em repositórios de código-fonte como o GitHub.

Criar tokens no seu servidor

Para criar novos tokens (JWTs) no seu servidor, use as bibliotecas JWT padrão e o arquivo JSON que você salvou com segurança na sua nova conta de serviço.

Criar tokens na máquina de desenvolvimento

Para gerar JWTs na sua máquina de desenvolvimento, use o seguinte comando oauth2l:

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

É necessário especificar um local de cache vazio usando a sinalização --cache para garantir que um token diferente seja produzido a cada vez. Certifique-se de cortar a string resultante. Espaços ou caracteres de nova linha extras farão com que a API rejeite o token.

Assinar o token

É necessário usar o algoritmo RS256 e as seguintes declarações para assinar o JWT:

• iss: o endereço de e-mail da conta de serviço.
• sub: o endereço de e-mail da conta de serviço.
• iat: o horário da época Unix em que o token foi gerado, em segundos.
• exp — iat + 3600 (1 hora). É o horário de época do Unix em que o token expira, em segundos.
• aud — O público-alvo. Ele precisa ser definido como https://arcore.googleapis.com/.

Declarações não padrão não são necessárias no payload do JWT. No entanto, a declaração uid pode ser útil para identificar o usuário correspondente.

Se você usar uma abordagem diferente para gerar JWTs, como o uso de uma API do Google em um ambiente gerenciado pelo Google, assine seus JWTs com as declarações nesta seção. Acima de tudo, verifique se o público-alvo está correto.

Transmitir o token na sessão do ARCore

1. Verifique se Estratégia de autenticação do iOS está definida como AuthenticationToken. No Unity, acesse Edit > Project Settings > XR Plug-in Management > ARCore Extensions. No menu suspenso Estratégia de autenticação do iOS, selecione a opção Token de autenticação.

2. Quando você receber um token, transmita-o para sua sessão do ARCore usando ARAnchorManager.SetAuthToken():

   // Designate the token to authorize ARCore API calls
   // on the iOS platform. This should be called each time the application's token is refreshed.
   ARAnchorManager.SetAuthToken(authToken);
   

Agora seu app está configurado para usar a autenticação sem chave.

Observe o seguinte ao transmitir um token para a sessão:

• Se você usou uma chave de API para criar a sessão, o ARCore ignorará o token e registrará um erro.

  Se você não precisa mais da chave de API, exclua-a no Google Developers Console e remova-a do seu app.

• O ARCore ignora os tokens que contêm espaços ou caracteres especiais.

• Normalmente, os tokens expiram após uma hora. Se houver a possibilidade de que seu token expire durante o uso, consiga um novo token e transmita-o para a API.

Chave de API

1. No Google Cloud, abra a página "Credenciais".
   Credenciais
2. Clique em Criar credenciais e, em seguida, selecione a chave de API no menu.
   A caixa de diálogo "Chave de API" mostra a string da sua chave recém-criada.

3. No Unity, acesse Edit > Project Settings > XR Plug-in Management > ARCore Extensions. Para cada plataforma de destino (Android, iOS), no menu suspenso Authentication Strategy, selecione a opção API Key. Depois, insira-a nos campos correspondentes.

4. Consulte a documentação sobre restrições da chave de API para proteger sua chave.

Agora seu app está configurado para usar chaves de API.

A seguir

Com a autorização configurada, confira os seguintes recursos do ARCore que a usam:

• API Geospatial
• API Cloud Anchor