Включить ARCore

На этой странице описывается, как включить функциональность ARCore в ваших проектах Android NDK. Для этого вам необходимо:

  1. Добавьте AR Required или AR Optional в манифест
  2. Добавьте зависимости сборки в свой проект
  3. Выполните проверки во время выполнения , чтобы убедиться, что устройство поддерживает ARCore и что на нем установлены Google Play Services for AR .
  4. Убедитесь, что ваше приложение соответствует требованиям конфиденциальности пользователей ARCore.

Сервисы Google Play для дополненной реальности

ARCore SDK делают функции дополненной реальности доступными на устройствах с поддержкой ARCore , на которых установлены службы Google Play для дополненной реальности (ARCore).

Сервисы Google Play для AR автоматически устанавливаются и обновляются на подавляющем большинстве поддерживаемых устройств.

Перед началом сеанса дополненной реальности приложения должны:

  1. Убедитесь, что ARCore поддерживается, вызвав ArCoreApk_checkAvailability .
  2. Убедитесь, что Сервисы Google Play для AR установлены и обновлены, а необходимые данные профиля устройства ARCore загружены, вызвав ArCoreApk_requestInstall .

Добавьте AR Required или AR Optional в манифест

Приложение, поддерживающее функции дополненной реальности, можно настроить двумя способами: требуется дополненная реальность и необязательный .

Требуется дополненная реальность

Чтобы приложение, требующее дополненной реальности, можно было использовать, требуется устройство с поддержкой ARCore , на котором установлены службы Google Play для дополненной реальности.

  • Магазин Google Play делает приложения, требующие дополненной реальности, доступными только на устройствах, поддерживающих ARCore .

  • Когда пользователи устанавливают приложение, требующее дополненной реальности, магазин Google Play автоматически устанавливает Сервисы Google Play для дополненной реальности . Однако ваше приложение должно по-прежнему выполнять дополнительные проверки во время выполнения на случай, если сервисы Google Play для дополненной реальности должны быть обновлены или удалены вручную.

Дополнительные сведения см. в разделе Публикация приложений дополненной реальности в магазине Google Play .

Чтобы объявить ваше приложение обязательным для дополненной реальности, измените файл AndroidManifest.xml , включив в него следующие записи:

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

Затем измените build.gradle вашего приложения, чтобы указать minSdkVersion не менее 24:

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

Дополненная реальность Необязательно

Дополнительное приложение дополненной реальности имеет дополнительные функции дополненной реальности, которые активируются только на устройствах с поддержкой ARCore , на которых установлены службы Google Play для дополненной реальности.

  • Дополнительные приложения AR можно устанавливать и запускать на устройствах, не поддерживающих ARCore.

  • Когда пользователи устанавливают дополнительное приложение AR, магазин Google Play не будет автоматически устанавливать Сервисы Google Play для AR вместе с приложением.

Чтобы объявить ваше приложение опциональным AR , измените файл AndroidManifest.xml , включив в него следующие записи:

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

Затем измените build.gradle вашего приложения, чтобы указать minSdkVersion не менее 14:

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

Добавить зависимости сборки

Чтобы добавить библиотеку ARCore в проект Android Studio, выполните следующие действия:

  1. Убедитесь, что файл build.gradle вашего проекта включает репозиторий Google Maven.

    allprojects {
    repositories {
        google()
            ...
    
  2. Извлеките нативные библиотеки из ARCore aar.

    Собственные библиотеки включены в файл ARCore aar. Чтобы использовать их как часть проекта C/C++, их необходимо извлечь из архива, чтобы на них можно было ссылаться напрямую. Для этого добавьте пользовательскую задачу в файл build.gradle вашего модуля (например, app/build.gradle ).

    Заголовочный файл для ARCore, arcore_c_api.h , включен в проект GitHub SDK:

    Определите переменную для каталога в каталоге app/build . Собственные библиотеки будут извлечены в этот каталог. Также создайте конфигурацию gradle для хранения задач и данных извлечения.

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

    Создайте задачу для копирования нативных библиотек из файла aar и добавьте их в зависимости сборки.

      // 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. Настройте собственные флаги сборки, чтобы передать местоположения внешним инструментам сборки.

    Этот пример взят из примеров в проекте 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. Добавьте зависимости как для Java, так и для собственных библиотек.

     dependencies {
          ...
          // Add java and native dependencies on the ARCore library
          implementation 'com.google.ar:core:1.32.0'
          natives 'com.google.ar:core:1.32.0'
          ...
     }
    
  5. Ссылка на собственные библиотеки в 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}
    )
    

Выполнение проверок во время выполнения

Проверьте, установлен ли ARCore

Все приложения AR должны вызывать ArCoreApk_requestInstall() перед созданием сеанса ARCore. ArCoreApk_requestInstall() проверяет, установлена ​​ли совместимая версия Google Play Services для AR (она может быть устаревшей или была удалена пользователем вручную), и предлагает пользователю установить службу, если она отсутствует.

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

Если ArCoreApk_requestInstall() возвращает AR_INSTALL_STATUS_INSTALL_REQUESTED , текущее действие приостанавливается и пользователю предлагается установить или обновить службу. onResume() активности выполняется снова, когда пользователь возвращается к активности.

Проверьте, поддерживается ли ARCore (только AR по выбору)

Дополнительные приложения AR могут использовать ArCoreApk_checkAvailability() , чтобы определить, поддерживает ли текущее устройство ARCore. На устройстве, которое не поддерживает ARCore, приложения должны отключать функции, связанные с дополненной реальностью, и скрывать связанные элементы пользовательского интерфейса.

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

Затем, когда пользователь захочет использовать функцию дополненной реальности, ваше приложение должно убедиться, что установлены сервисы Google Play для дополненной реальности . Простой способ сделать это — запустить действие, которое следует шаблону AR Required, описанному выше.

Соблюдение требований конфиденциальности пользователей

Убедитесь, что ваше приложение соответствует требованиям конфиденциальности пользователей ARCore.

Следующие шаги

Прочтите код и комментарии в примере приложения, а также в Справочнике C API .