Ativar RA no seu app Android NDK

Ative a RA para usar os recursos de realidade aumentada no seu app novo ou atual.

Configurar o app para ser obrigatório ou opcional para RA

Para economizar espaço em dispositivos individuais, todos os recursos de RA são armazenados em um app chamado Google Play Services para RA, que é atualizado separadamente pela Play Store. Os apps Android que usam recursos de RA se comunicam com o Google Play Services para RA usando o SDK do ARCore. Um app compatível com recursos de RA pode ser configurado de duas maneiras: RA necessária e RA opcional. Essa designação determina como o app interage com o Google Play Services para apps de RA.

Um app AR Required não pode funcionar sem o ARCore. É necessário um dispositivo com suporte ao ARCore que tenha o Google Play Services para RA instalado.

  • A Google Play Store só vai disponibilizar apps com a exigência de RA em dispositivos compatíveis com o ARCore.
  • Quando os usuários instalam um app que exige RA, a Google Play Store instala automaticamente o Google Play Services para RA no dispositivo. No entanto, o app ainda precisará realizar mais verificações no tempo de execução caso o Google Play Services para RA esteja desatualizado ou tenha sido desinstalado manualmente.

Um app opcional de RA usa o ARCore para aprimorar a funcionalidade atual. Ele tem recursos de RA opcionais que são ativados apenas em dispositivos compatíveis com o 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 têm suporte ao ARCore.
  • Quando os usuários instalam um app opcional de RA, a Google Play Store não instala automaticamente o Google Play Services para RA no dispositivo.
RA necessáriaRA opcional
Uso de recursos de RA Seu app precisa do ARCore para a funcionalidade básica. O ARCore aumenta a funcionalidade do seu app. O app pode ser executado sem suporte ao ARCore.
Visibilidade na Play Store O app só está listado na Play Store em dispositivos compatíveis com o ARCore. O app segue os procedimentos normais de inclusão.
Método de instalação do Google Play Services para RA A Play Store instala o Google Play Services para RA junto com o app. Seu app usa ArCoreApk.requestInstall() para fazer o download e instalar o ARCore.
Requisitos do minSdkVersion do Android Android 7.0 (nível 24 da API) Android 4.4 (nível 19 da API), embora executar qualquer funcionalidade de RA exija pelo menos o Android 7.0 (nível 24 da API).
É necessário usar ArCoreApk_checkAvailability() ou ArCoreApk_checkAvailabilityAsync() para verificar o suporte ao ARCore e o status da instalação.
É necessário usar o ArCoreApk.requestInstall() para instalar o Google Play Services para RA.

Para tornar o app obrigatório ou opcional para RA, atualize o AndroidManifest.xml para incluir as seguintes entradas:

RA necessária

<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" />

<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>

RA (opcional)

<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 a build.gradle do app para especificar um minSdkVersion de pelo menos 24:

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

Adicionar dependências de compilação

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

    allprojects {
    repositories {
        google()
        …
    }
}

  2. Adicione uma tarefa personalizada ao arquivo build.gradle do módulo para extrair as bibliotecas nativas incluídas do arquivo AAR do ARCore. Dessa forma, eles podem ser referenciados diretamente em um projeto C ou C++.

  3. No diretório app/build, defina uma variável para o diretório de onde as bibliotecas nativas serão extraídas.

  4. Crie uma configuração do Gradle para armazenar os dados e as tarefas de extração.

    /*
The ARCore AAR library contains native shared libraries that 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 }

  5. Crie uma tarefa para copiar as bibliotecas nativas do arquivo AAR e adicione-as às dependências do build.

    // Extracts the shared libraries from AARs in the native configuration
// 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)
    }
}

  6. Configure as flags de build nativas para passar os locais às ferramentas de build externas.

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

  7. Adicione as dependências das bibliotecas nativas e do Java.

    dependencies {
     ...
     // Add Java and native dependencies to the ARCore library.
     implementation 'com.google.ar:core:1.33.0'
     natives 'com.google.ar:core:1.33.0'
     ...
}

  8. 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}
)

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

Durante o tempo de execução, faça o seguinte para garantir que os recursos de RA do app funcionem sem problemas.

Verificar se o ARCore é compatível

Os apps com e sem RA obrigatórios precisam usar ArCoreApk_checkAvailability() ou ArCoreApk_checkAvailabilityAsync() para determinar se o dispositivo atual oferece suporte ao ARCore. Em dispositivos que não são compatíveis com o ARCore, os apps precisam desativar as funcionalidades relacionadas à RA e ocultar os elementos de interface associados.

Um app do Android NDK pode usar a classe ArCoreApk do Java para verificar a compatibilidade e gerenciar a instalação na API de sessão nativa do ARCore. Dependendo da estrutura do app, isso pode ser mais fácil do que usar as funções ArCoreApk_ devido à grande quantidade de processamento de erros e interação da interface do usuário envolvidos.

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 or enable the AR button.
  } else {
    // Hide or disable the AR button.
  }
}
Mesmo que o Google Play Services para RA esteja instalado com seu app obrigatório para RA, os usuários com dispositivos sem suporte podem instalá-lo de uma fonte externa. Usar ArCoreApk_checkAvailability() ou ArCoreApk_checkAvailabilityAsync() para verificar o suporte ao ARCore garante uma experiência consistente.

O ArCoreApk_checkAvailability() pode precisar consultar os recursos da rede para determinar se o dispositivo é compatível com o ARCore. Durante esse período, ele retornará AR_AVAILABILITY_UNKNOWN_CHECKING. Para reduzir a latência percebida e o pop-in, os apps precisam chamar ArCoreApk_checkAvailability() uma vez no início do ciclo de vida para iniciar a consulta, ignorando o valor retornado. Dessa forma, um resultado armazenado em cache estará disponível imediatamente quando um elemento da interface de entrada em RA for exibido.

Verificar se o Google Play Services para RA está instalado

Os apps obrigatórios e opcionais de RA precisam usar ArCoreApk.requestInstall() antes de criar uma sessão do ARCore para verificar se uma versão compatível do Google Play Services para RA está (ainda) instalada e garantir que todos os dados necessários do perfil do dispositivo do ARCore foram transferidos por download.

// Tracks if an installation request has already been triggered.
bool install_requested_;

void nativeOnCreate() {
  // Do other setup here.

  install_requested_ = false;
}

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

    ArInstallStatus install_status;
    // Ensure that 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 the ARCore session.
  }

  // Normal onResume behavior.
}

Obedeça aos requisitos de privacidade do usuário

Para publicar seu app na Play Store, verifique se ele está em conformidade com as Requisitos de privacidade do usuário.

O que vem em seguida?