Guia do desenvolvedor do Cloud Anchors para Android (Kotlin/Java)

Aprenda a usar as âncoras do Cloud nos seus apps.

Pré-requisitos

Entenda os conceitos básicos de RA e como configurar uma sessão do ARCore antes de continuar.

Se você não conhece os Cloud Anchors:

Ativar a API ARCore

Antes de usar o Cloud Anchors no app, é necessário ativar a API ARCore.

Ativar os recursos do Cloud Anchor na configuração da sessão

Depois de ativar a funcionalidade do Cloud Anchors no app, ative os recursos do Cloud Anchors na configuração da sessão de RA para que ele possa se comunicar com a API ARCore:

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

Hospedar uma âncora do Cloud

O Hosting começa com uma chamada para hostCloudAnchorAsync(). O ARCore vai fazer upload de dados visuais, poses do dispositivo e a pose da âncora para a API ARCore. A API processa essas informações para criar um mapa de recursos 3D e, por fim, retorna ao dispositivo um ID exclusivo do Cloud Anchor para a âncora.

Também é possível estender a duração de uma âncora hospedada usando a API ARCore Cloud Anchor Management.

O app precisa seguir estas etapas para concluir a hospedagem de uma âncora do Cloud:

  1. Chame hostCloudAnchorAsync().
  2. Aguarde o callback ou verifique continuamente o estado Future até que ele seja concluído.
  3. Verifique o estado do resultado para determinar se a operação foi bem-sucedida ou interprete o código de erro em caso de falha.
  4. Compartilhe o ID do Cloud Anchor do resultado com outros clientes e use-o para resolver o Cloud Anchor com resolveCloudAnchorAsync().

Verificar a qualidade do mapeamento dos pontos de elemento

Session.FeatureMapQuality indica a qualidade dos pontos de recurso vistos pelo ARCore nos segundos anteriores de uma determinada pose da câmera. Âncoras do Cloud hospedadas usando recursos de maior qualidade costumam ser resolvidas com mais precisão. Use Session.estimateFeatureMapQualityForHosting() para estimar a qualidade do mapa de recursos de uma determinada pose da câmera.

Valor Descrição
INSUFFICIENT A qualidade dos pontos de características identificados na pose nos segundos anteriores é baixa. Esse estado indica que o ARCore provavelmente terá mais dificuldade para resolver a âncora do Cloud. Incentive o usuário a mover o dispositivo para que a posição desejada do Cloud Anchor que ele quer hospedar possa ser vista de diferentes ângulos.
SUFFICIENT A qualidade dos pontos de características identificados na pose nos segundos anteriores provavelmente é suficiente para que o ARCore resolva uma âncora do Cloud, embora a precisão da pose resolvida provavelmente seja reduzida. Incentive o usuário a mover o dispositivo para que a posição desejada do Cloud Anchor que ele quer hospedar possa ser vista de diferentes ângulos.
GOOD A qualidade dos pontos de características identificados na pose nos segundos anteriores provavelmente é suficiente para que o ARCore resolva uma âncora do Cloud com um alto grau de precisão.

Resolver uma âncora hospedada anteriormente

Chame resolveCloudAnchorAsync() para resolver uma âncora do Cloud hospedada. A API ARCore compara periodicamente os recursos visuais da cena com o mapa de recursos 3D da âncora para identificar a posição e a orientação do usuário em relação à âncora. Quando encontra uma correspondência, a API retorna a pose da âncora do Cloud hospedada.

É possível iniciar resoluções para várias âncoras do Cloud em sequência. Até 40 operações simultâneas do Cloud Anchor podem existir por vez.

Cancelar uma operação ou remover uma âncora do Cloud

Chame cancel() para cancelar uma operação pendente da âncora do Cloud. Chame detach() para remover uma âncora do Cloud já resolvida do app.

Verificar o estado do resultado de uma operação de âncora do Cloud

Use Anchor.CloudAnchorState para verificar o status do resultado da operação de hospedagem ou resolução, incluindo erros.

Valor Descrição
ERROR_CLOUD_ID_NOT_FOUND A resolução falhou porque a API ARCore não encontrou o ID do Cloud Anchor fornecido.
ERROR_HOSTING_DATASET_PROCESSING_FAILED A hospedagem falhou porque o servidor não conseguiu processar o conjunto de dados da âncora especificada. Tente de novo depois que o dispositivo coletar mais dados do ambiente.
ERROR_HOSTING_SERVICE_UNAVAILABLE Não foi possível acessar a API ARCore. Isso pode acontecer por uma série de motivos. O dispositivo pode estar no modo avião ou não ter uma conexão de Internet. A solicitação enviada ao servidor pode ter atingido o tempo limite sem resposta. Pode haver uma conexão de rede ruim, indisponibilidade de DNS, problemas de firewall ou qualquer outra coisa que possa afetar a capacidade do dispositivo de se conectar à API ARCore.
ERROR_INTERNAL Uma tarefa de hospedagem ou resolução para esta âncora foi concluída com um erro interno. O app não deve tentar se recuperar desse erro.
ERROR_NOT_AUTHORIZED A autorização fornecida pelo aplicativo não é válida. Consulte Solução de problemas com autorização da API ARCore.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW Não foi possível resolver o Cloud Anchor porque a versão do SDK usada para resolver a âncora é mais recente e incompatível com a versão usada para hospedar.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD O Cloud Anchor não pode ser resolvido porque a versão do SDK usada para resolver a âncora é mais antiga e incompatível com a versão usada para hospedá-la.
ERROR_RESOURCE_EXHAUSTED O aplicativo esgotou a cota de solicitações atribuída ao projeto do Google Cloud. Solicite uma cota adicional para a API ARCore do seu projeto no Google Developers Console.
SUCCESS Uma tarefa de hospedagem ou resolução para esta âncora foi concluída.

Cotas de API para solicitações de host e resolução

A API ARCore tem as seguintes cotas para largura de banda de solicitação:

Tipo da cota Máximo Duração Aplicável a
Número de âncoras ilimitado N/A projeto
Solicitações de host de âncora 30 minuto Endereço IP e projeto
Ancorar solicitações resolve 300 minuto Endereço IP e projeto

Práticas recomendadas para uma boa experiência do usuário

Instrua os usuários a fazer o seguinte para garantir uma boa experiência no app:

  • Aguarde alguns segundos após o início da sessão antes de tentar hospedar uma âncora (colocando um objeto etc.). Isso dá tempo para que o rastreamento se estabilize.
  • Ao selecionar um local para hospedar a âncora, tente encontrar uma área com recursos visuais facilmente distinguíveis entre si. Para melhores resultados, evite superfícies reflexivas ou que não tenham recursos visuais, como paredes brancas.

  • Mantenha a câmera treinada no centro de interesse e mova o dispositivo pelo centro de interesse para mapear o ambiente de diferentes ângulos, mantendo aproximadamente a mesma distância física que você faz isso. Isso ajudará a capturar mais dados visuais e a tornar a resolução mais robusta.

  • Verifique se há iluminação suficiente no ambiente real ao hospedar e resolver as ancoragens na nuvem.

Política de descontinuação

  • Os apps criados com o SDK do ARCore 1.12.0 ou mais recente estão incluídos na política de descontinuação da API Cloud Anchor.
  • Os apps criados com o SDK 1.11.0 ou versões anteriores do ARCore não podem hospedar ou resolver âncoras do Cloud devido ao uso de uma API ARCore mais antiga e descontinuada pelo SDK.

O que vem em seguida?