Usar a API ARCore no Google Cloud

Selecione a plataforma:

Recursos do ARCore, como a API Geospatial e as âncoras de nuvem, usam a API ARCore hospedada no Google Cloud. Ao usar esses recursos, seu aplicativo usa credenciais para acessar o serviço da API ARCore.

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

Crie um projeto na nuvem do Google Cloud ou use um atual.

Se você tiver um projeto, selecione-o.

Acessar o seletor de projetos

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

Criar um projeto

Ativar a API ARCore

Para usar a API ARCore, é necessário ativá-la no projeto.

Ativar a API ARCore

Configurar um método de autorização

Um aplicativo Unity pode se comunicar com a API ARCore usando dois métodos de autorização diferentes: sem chave, que é o método recomendado, e com 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 aplicativo.

    No iOS, a autorização sem chave usa um token assinado para controlar o acesso à API. Esse método exige um servidor de sua propriedade para assinar tokens e controlar o acesso à API.

  • Uma chave de API é uma string que identifica um projeto na nuvem do Google Cloud. As chaves de API geralmente não são consideradas seguras, já que normalmente são acessíveis aos clientes. Considere usar a autorização sem chave para se comunicar com a API ARCore.

Sem chave

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

Determinar as 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 seu app.

.

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

Ao executar ou depurar seu 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 do keystore de depuração é android. Em seguida, o utilitário keytool mostra 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

Em seguida, 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 obter 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 app e a usa para assinar seus APKs. Essa chave deve ser usada para a impressão digital de assinatura.

  1. Na página de assinatura de apps do Google Play Console, role a tela 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 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.
    • Nome do pacote: use o nome do pacote declarado no AndroidManifest.xml.
    • Impressão digital do certificado SHA-1: use uma impressão digital obtida nas etapas anteriores.

  • Clique em Criar.

Incluir as bibliotecas necessárias

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

  2. Se você estiver usando 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 seguinte 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.** { *; }

Seu app agora está configurado para usar a autenticação sem chave.

Sem chave

O ARCore oferece suporte à autorização de chamadas de API no iOS usando um token da Web JSON. 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 próprio mecanismo de autorização precisa proteger o endpoint.

  • O endpoint precisa gerar um novo token a cada vez, de modo 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 Conceder 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 a tela 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 com a chave privada para sua máquina. Armazene o arquivo de chave JSON baixado em um local seguro.

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ê baixou com segurança da 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 flag --cache para garantir que um token diferente seja produzido a cada vez. Não se esqueça de remover os espaços em branco da string resultante. Espaços extras ou caracteres de nova linha farão com que a API rejeite o token.

Assinar o token

Você precisa 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 tempo de época do Unix em que o token foi gerado, em segundos.
  • exp — iat + 3600 (1 hora). O tempo 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/.

As declarações não padrão não são obrigatórias no payload do JWT, mas a declaração uid pode ser útil para identificar o usuário correspondente.

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

Transmitir o token na sessão do ARCore

  1. Verifique se a 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. Ao 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);

Seu app agora 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 vai ignorar o token e registrar um erro.

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

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

  • Os tokens geralmente expiram após uma hora. Se houver a possibilidade de o token expirar durante o uso, obtenha um novo 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 criada" mostra a string da chave recém-criada.

  3. No Unity, acesse Edit > Project Settings > XR Plug-in Management > ARCore Extensions. Para cada plataforma segmentada (Android, iOS), no menu suspenso Estratégia de autenticação, selecione a opção Chave de API. Em seguida, insira sua chave de API nos campos correspondentes.

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

Seu app agora está configurado para usar chaves de API.

A seguir

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