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.
Se você não tiver um projeto do Google Cloud, crie um.
Ativar a API ARCore
Para usar a API ARCore, ela precisa ser ativada no seu projeto.
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.
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.keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore
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.
- Na página "Assinatura de apps" do Google Play Console, role até Certificado da chave de assinatura do app.
- 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".
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
- Inclua
com.google.android.gms:play-services-auth:16+
nas dependências do app. 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' } }
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:
- No Google Cloud, abra a página "Credenciais".
Credenciais - Clique em Criar credenciais > Conta de serviço.
- Em Detalhes da conta de serviço, digite um nome para a nova conta e clique em Criar.
- 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.
- Na página Conceda aos usuários acesso a essa conta de serviço, clique em "Concluído".
- Na página Credenciais, encontre a seção "Contas de serviço" e clique no nome da conta que você acabou de criar.
- Na página Detalhes da conta de serviço, role para baixo até a seção "Chaves" e selecione Adicionar chave > Criar nova chave.
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.
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 comohttps://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
- 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.
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
- No Google Cloud, abra a página "Credenciais".
Credenciais - 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. 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.
- 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: