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 tem experiência com o Cloud Anchors, entenda como funcionam as âncoras e os âncoros do Cloud.
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 os recursos do Cloud Anchors no seu app, ative os recursos do Cloud Anchors na configuração da sessão de RA do app para que ele possa se comunicar com a API ARCore:
Hospedar uma âncora do Cloud
A hospedagem começa com uma chamada para ARAnchorManager.HostCloudAnchorAsync(). O ARCore fará o upload de dados visuais, poses do dispositivo e posições de âncora para a API do ARCore. Em seguida, a API processa essas informações para criar um mapa de recursos 3D, retornando um ID exclusivo do Cloud Anchor para a âncora do dispositivo.
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:
- Chame
ARAnchorManager.HostCloudAnchorAsync(). - Inicie uma corrotina para aguardar até que a promessa gere um resultado. Consulte Corrotinas no Unity (link em inglês) para ver mais informações.
- 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.
- Compartilhe o ID do Cloud Anchor do resultado com outros clientes e use-o para resolver o Cloud Anchor com
ARAnchorManagerExtensions.ResolveCloudAnchorAsync().
Verificar a qualidade do mapeamento de pontos de destaque
ARCoreExtensions.FeatureMapQuality indica a qualidade dos pontos de recursos vistos pelo ARCore nos segundos anteriores a partir de uma determinada pose da câmera. As âncoras do Cloud Anchor hospedadas com recursos de maior qualidade geralmente são resolvidas com mais precisão. Use ARAnchorManagerExtensions.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 visualizada 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 ARAnchorManagerExtensions.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 posição do Cloud Anchor hospedado.
É possível iniciar resoluções para vários Cloud Anchors 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
O ARCloudAnchor.OnDestroy() é chamado automaticamente quando o componente ARCloudAnchor é removido do objeto do jogo que o contém. Isso vai remover e liberar o objeto nativo do Cloud Anchor.
Verificar o estado do resultado de uma operação de âncora do Cloud
Use o CloudAnchorState para verificar o status do resultado da operação de hospedagem ou resolução, incluindo erros.
| Valor | Descrição |
|---|---|
ErrorResolvingCloudIdNotFound |
A resolução falhou porque a API ARCore não encontrou o ID do Cloud Anchor fornecido. |
ErrorHostingDatasetProcessingFailed |
A hospedagem falhou porque o servidor não conseguiu processar o conjunto de dados da âncora especificada. Tente novamente depois que o dispositivo coletar mais dados do ambiente. |
ErrorHostingServiceUnavailable |
A API ARCore não pode ser alcançada. 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 ativa. O tempo limite da solicitação enviada ao servidor pode ter sido atingido sem resposta. Uma conexão de rede ruim, indisponibilidade de DNS, problemas de firewall ou qualquer outra coisa que possa afetar a capacidade de conexão do dispositivo com a API ARCore. |
ErrorInternal |
Uma tarefa de hospedagem ou resolução para esta âncora foi concluída com um erro interno. O app não pode tentar se recuperar desse erro. |
ErrorNotAuthorized |
O app não consegue se comunicar com a API ARCore devido a uma autorização inválida. Verifique Project Settings > XR > ARCore Extensions para conferir uma estratégia de autorização válida. |
ErrorResolvingPackageTooNew |
Não foi possível resolver o Cloud Anchor porque o pacote de extensões do ARCore usado para resolver o Cloud Anchor é mais recente e incompatível com a versão usada para hospedá-lo. |
ErrorResolvingPackageTooOld |
Não foi possível resolver o Cloud Anchor porque o pacote de extensões do ARCore usado para resolver o Cloud Anchor é mais antigo e incompatível com a versão usada para hospedá-lo. |
ErrorResourceExhausted |
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 resolução e de host
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 |
| Fixar solicitações de resolução | 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á ao acompanhamento algum tempo para se estabilizar.
- Ao selecionar um local para hospedar a âncora, tente encontrar uma área com elementos visuais que sejam facilmente distinguíveis um do outro. Para melhores resultados, evite superfícies reflexivas ou que não tenham recursos visuais, como paredes brancas.
Mantenha a câmera focada no centro de interesse e mova o dispositivo ao redor do centro de interesse para mapear o ambiente de diferentes ângulos, mantendo aproximadamente a mesma distância física. Isso vai ajudar a capturar mais dados visuais e tornar a resolução mais robusta.
Confira se há iluminação suficiente no ambiente real enquanto hospeda e resolve âncoras do Cloud.
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.
A seguir
- Confira a documentação de referência das extensões do ARCore para a AR Foundation para saber mais maneiras de usar o ARCore no seu app.