Ativar RA no seu app Android NDK

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

Configurar o app como "RA obrigatória" ou "RA opcional"

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 que oferece suporte a recursos de RA pode ser configurado de duas maneiras: RA obrigatória e RA opcional. Essa designação determina como o app de RA interage com o Google Play Services para RA.

Um app de RA obrigatória não funciona sem o ARCore. Ele exige um dispositivo compatível com o ARCore que tenha o Google Play Services para RA instalado.

  • A Google Play Store só disponibiliza apps de RA obrigatória em dispositivos que oferecem suporte ao ARCore.
  • Quando os usuários instalam um app de RA obrigatória, a Google Play Store instala automaticamente o Google Play Services para RA no dispositivo. No entanto, o app ainda precisa realizar outras verificações de tempo de execução caso o Google Play Services para RA esteja desatualizado ou tenha sido desinstalado manualmente.

Um app de RA opcional usa o ARCore para melhorar a funcionalidade atual. Ele tem recursos de RA opcionais que só são ativados em dispositivos compatíveis com o ARCore que tenham o Google Play Services para RA instalado.

  • Os apps de RA opcional podem ser instalados e executados em dispositivos que não oferecem suporte ao ARCore.
  • Quando os usuários instalam um app de RA opcional, a Google Play Store não instala automaticamente o Google Play Services para RA no dispositivo.
RA obrigatóriaRA opcional
Uso do recurso de RA O app precisa do ARCore para a funcionalidade básica. O ARCore aumenta a funcionalidade do app. O app pode ser executado sem suporte ao ARCore.
Visibilidade da Google Play Store O app só aparece na Google Play Store em dispositivos que oferecem suporte ao ARCore. O app segue os procedimentos normais de listagem.
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. O app usa ArCoreApk.requestInstall() para fazer o download e instalar o ARCore.
Requisitos de 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 do ARCore e o status da instalação
É necessário usar ArCoreApk.requestInstall() para instalar o Google Play Services para RA

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

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

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

Adicionar dependências de build

  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 bibliotecas nativas incluídas do arquivo AAR do ARCore. Dessa forma, elas podem ser referenciadas diretamente em um projeto C ou C++.

  3. No diretório app/build, defina uma variável para o diretório em que 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-a às dependências de 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 nativo para transmitir 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 Java e nativas.

    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 no app sejam executados sem problemas.

Verificar se o ARCore é compatível

Os apps de RA obrigatória e RA opcional precisam usar ArCoreApk_checkAvailability() ou ArCoreApk_checkAvailabilityAsync() para determinar se o dispositivo atual oferece suporte ao ARCore. Em dispositivos que não oferecem suporte ao ARCore, os apps precisam desativar a funcionalidade relacionada à RA e ocultar os elementos da interface associados.

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

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 seja instalado junto com o app de RA obrigatória, os usuários com dispositivos não compatíveis podem instalá-lo de uma fonte externa. Usar ArCoreApk_checkAvailability() ou ArCoreApk_checkAvailabilityAsync() para verificar o suporte do ARCore garante uma experiência consistente.

ArCoreApk_checkAvailability() pode precisar consultar recursos de rede para determinar se o dispositivo oferece suporte ao ARCore. Durante esse período, ele vai 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 de RA puder ser exibido.

Verificar se o Google Play Services para RA está instalado

Os apps de RA obrigatória e RA opcional 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 para garantir que todos os dados de perfil do dispositivo ARCore necessários tenham sido baixados.

// 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.
}

Cumprir os requisitos de privacidade do usuário

Para publicar seu app na Google Play Store, verifique se ele está em conformidade com os requisitos de privacidade do usuário do ARCore .

Próximas etapas