Ativar o ARCore

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Esta página descreve como ativar a funcionalidade do ARCore nos projetos do Android NDK. Para fazer isso, você precisa:

  1. Adicionar RA obrigatória ou RA opcional ao manifesto
  2. Adicionar dependências de build ao seu projeto
  3. Realize verificações de tempo de execução para garantir que o dispositivo seja compatível com o ARCore e que o Google Play Services para RA seja instalado nele.
  4. Verificar se o app está em conformidade com os Requisitos de privacidade do usuário do ARCore'

Google Play Services para RA

Os SDKs do ARCore disponibilizam recursos de RA em dispositivos compatíveis com o ARCore que têm o Google Play Services para RA (ARCore) instalado.

O Google Play Services para RA é instalado e atualizado automaticamente na grande maioria dos dispositivos compatíveis.

Antes de iniciar uma sessão de RA, os apps precisam:

  1. Verifique se há suporte para o ARCore chamando ArCoreApk_checkAvailability.
  2. Verifique se o Google Play Services para RA está instalado e atualizado e se os dados de perfil do dispositivo do ARCore necessários foram salvos, chamando ArCoreApk_requestInstall.

Adicionar RA obrigatória ou RA opcional ao manifesto

Um app compatível com recursos de RA pode ser configurado de duas maneiras: RA necessária e RA opcional.

RA obrigatória

Para ser utilizável, um app RA obrigatório requer um Dispositivo compatível com ARCore que tenha o Google Play Services para RA instalado.

Para ver mais informações, consulte Como publicar apps de RA na Google Play Store.

Para declarar o app como RA obrigatório, modifique a AndroidManifest.xml para incluir as seguintes entradas:

<uses-permission android:name="android.permission.CAMERA"/>

<!-- Limits app visibility in the Google Play Store to ARCore supported devices
     (https://developers.google.com/ar/devices). -->
<uses-feature android:name="android.hardware.camera.ar" android:required="true"/>

<application …>
    …

  <!-- "AR Required" app, requires "Google Play Services for AR" (ARCore)
       to be installed, as the app does not include any non-AR features. -->
  <meta-data android:name="com.google.ar.core" android:value="required" />

</application>

Em seguida, modifique a build.gradle do app para especificar um minSdkVersion de pelo menos 24:

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

RA (opcional)

Um app Opcional em RA tem recursos de RA opcionais que são ativados apenas em dispositivos compatíveis com ARCore que têm o Google Play Services para RA instalado.

  • Os apps opcionais de RA podem ser instalados e executados em dispositivos que não são compatíveis com o ARCore.

  • Quando os usuários instalarem um app opcional de RA, a Google Play Store não instalará automaticamente o Google Play Services para RA com o app.

Para declarar o app como RA (opcional), modifique o AndroidManifest.xml para incluir as seguintes entradas:

<uses-permission android:name="android.permission.CAMERA" />

<!-- If your app was previously AR Required, don't forget to remove the
 `<uses-feature android:name="android.hardware.camera.ar" />` entry, as
 this would limit app visibility in the Google Play Store to only
 ARCore supported devices. -->

<application …>
    …

    <!-- "AR Optional" app, contains non-AR features that can be used when
         "Google Play Services for AR" (ARCore) is not available. -->
    <meta-data android:name="com.google.ar.core" android:value="optional" />
</application>

Em seguida, modifique o build.gradle do app para especificar um minSdkVersion de pelo menos 19:

android {
    defaultConfig {
        …
        minSdkVersion 19
    }
}

Adicionar dependências de compilação

Para adicionar a biblioteca do ARCore ao seu projeto do Android Studio, siga estas etapas:

  1. Verifique se o arquivo build.gradle do seu projeto inclui o repositório Maven do Google.

    allprojects {
    repositories {
        google()
            ...
    
  2. Extrair bibliotecas nativas do ARCore aar.

    As bibliotecas nativas estão incluídas no arquivo aar do ARCore. Para usá-los como parte de um projeto C/C++, eles precisam ser extraídos do arquivo para que possam ser referenciados diretamente. Para fazer isso, adicione uma tarefa personalizada ao arquivo build.gradle do seu módulo (por exemplo, app/build.gradle).

    O arquivo principal do ARCore, arcore_c_api.h, está incluído no projeto do SDK do GitHub:

    Defina uma variável para um diretório no diretório app/build. As bibliotecas nativas serão extraídas para esse diretório. Crie também uma configuração do Gradle para armazenar as tarefas e os dados de extração.

    /*
    The ARCore aar library contains the native shared libraries. These are
    extracted before building to a temporary directory.
    */
    def arcore_libpath = "${buildDir}/arcore-native"
    
    // Create a configuration to mark which aars to extract .so files from
    configurations { natives }
    
    

    Crie uma tarefa para copiar as bibliotecas nativas do arquivo aar e adicioná-la às dependências de build

      // Extracts the shared libraries from aars in the natives configuration.
      // This is done so that NDK builds can access these libraries.
      task extractNativeLibraries() {
         // Extract every time.
         outputs.upToDateWhen { false }
    
         doFirst {
              configurations.natives.files.each { f ->
                  copy {
                      from zipTree(f)
                      into arcore_libpath
                      include "jni/**/*"
                  }
              }
          }
      }
    
      tasks.whenTaskAdded {
          task-> if (task.name.contains("external") && !task.name.contains("Clean")) {
              task.dependsOn(extractNativeLibraries)
          }
      }
    
  3. Configurar as sinalizações de build nativas para transmitir os locais às ferramentas de build externas.

    Este exemplo é de amostra do projeto do GitHub.

          externalNativeBuild {
              cmake {
                  cppFlags "-std=c++11", "-Wall"
                  arguments "-DANDROID_STL=c++_static",
                          "-DARCORE_LIBPATH=${arcore_libpath}/jni",
                          "-DARCORE_INCLUDE=${project.rootDir}/../../libraries/include"
              }
          }
    

  4. Adicione as dependências para as bibliotecas do Java e nativas.

     dependencies {
          ...
          // Add java and native dependencies on the ARCore library
          implementation 'com.google.ar:core:1.33.0'
          natives 'com.google.ar:core:1.33.0'
          ...
     }
    
  5. Consulte as bibliotecas nativas em CMakeLists.txt

    # Import the ARCore library.
    add_library(arcore SHARED IMPORTED)
    set_target_properties(arcore PROPERTIES IMPORTED_LOCATION
                  ${ARCORE_LIBPATH}/${ANDROID_ABI}/libarcore_sdk_c.so
                  INTERFACE_INCLUDE_DIRECTORIES ${ARCORE_INCLUDE}
    )
    

Executar verificações de tempo de execução

Verificar se o ARCore está instalado

Todos os apps de RA precisam chamar ArCoreApk_requestInstall() antes de criar uma sessão do ARCore. ArCoreApk_requestInstall() verifica se uma versão compatível do Google Play Services para RA está instalada (pode estar desatualizada ou foi removida manualmente pelo usuário) e solicita que o usuário instale o serviço, se ele não estiver presente.

// Tracks if we have already triggered an installation request.
bool install_requested_;

void nativeOnCreate() {
  // other setup

  install_requested_ = false;
}

void nativeOnResume(JNIEnv env, jobject activity) {
  if (ar_session_ == null) {
    bool user_requested_install = !install_requested_;

    ArInstallStatus install_status;
    // Ensure Google Play Services for AR and ARCore device profile data are
    // installed and up to date.
    ArStatus error = ArCoreApk_requestInstall(
        env, activity, user_requested_install, &install_status);
    if (error != AR_SUCCESS) {
      // Inform user of error.
      return;
    }

    switch (install_status) {
      case AR_INSTALL_STATUS_INSTALLED:
        break;
      case AR_INSTALL_STATUS_INSTALL_REQUESTED:
        // When this method returns `AR_INSTALL_STATUS_INSTALL_REQUESTED`:
        // 1. This activity will be paused.
        // 2. The user is prompted to install or update Google Play
        //    Services for AR (market://details?id=com.google.ar.core).
        // 3. ARCore downloads the latest device profile data.
        // 4. This activity is resumed. The next invocation of
        //    ArCoreApk_requestInstall will either return
        //    `AR_INSTALL_STATUS_INSTALLED` or throw an exception if the
        //    installation or update did not succeed.
        install_requested_ = true;
        return;
    }

    // Request camera permissions.

    error = ArSession_create(env, context, &ar_session_);
    if (error != AR_SUCCESS) {
      // Inform user of error.
      return;
    }

    // Configure session
  }

  // Normal onResume behavior
}

Se ArCoreApk_requestInstall() retornar AR_INSTALL_STATUS_INSTALL_REQUESTED, a atividade atual será pausada e o usuário receberá uma solicitação para instalar ou atualizar o serviço. O onResume() da atividade é executado novamente quando o usuário retorna à atividade.

Conferir se há suporte para o ARCore (apenas AR opcional)

Os apps opcionais de RA podem usar o ArCoreApk_checkAvailability() para determinar se o dispositivo atual é compatível com o ARCore. Em um dispositivo incompatível com o ARCore, os apps precisam desativar a funcionalidade relacionada à RA e ocultar elementos de IU associados.

void maybeEnableArButton(JNIEnv env, jobject context) {
  // Likely called from Activity.onCreate() of an activity with AR buttons.
  ArAvailability availability
  ArCoreApk_checkAvailability(env, context, &availability);
  if (availability == AR_AVAILABILITY_UNKNOWN_CHECKING) {
    // Set a timer to call maybeEnableArButton() again after about 200ms.
  }
  if (availability == AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED ||
      availability == AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD ||
      availability == AR_AVAILABILITY_SUPPORTED_INSTALLED) {
    // Show/enable AR button.
  } else {
    // Hide/disable AR button.
  }
}

Quando o usuário quiser usar um recurso de RA, o app precisará garantir que o Google Play Services para RA esteja instalado. Uma maneira fácil de fazer isso é iniciar uma atividade que siga o padrão de RA obrigatório descrito acima.

Conformidade com requisitos de privacidade do usuário

Verifique se o app está em conformidade com os Requisitos de privacidade do usuário do ARCore.

Próximas etapas

Leia o código e os comentários no app de exemplo e a Referência da API C.