Включить ARCore

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

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

Выбор между обязательным или необязательным AR

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

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

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

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

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

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

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

Требуется дополненная реальность Дополненная реальность Необязательно
Использование функций дополненной реальности Вашему приложению требуется ARCore для базовой функциональности. ARCore расширяет функциональные возможности вашего приложения. Ваше приложение может работать без поддержки ARCore.
Видимость в Play Маркете Ваше приложение отображается в Play Store только на устройствах с поддержкой ARCore. Ваше приложение следует обычным процедурам листинга .
Сервисы Google Play для метода установки AR Play Store устанавливает сервисы Google Play для дополненной реальности вместе с вашим приложением. Ваше приложение использует ArCoreApk.requestInstall() для загрузки и установки ARCore.
Требования Android minSdkVersion Android 7.0 (уровень API 24) Android 4.0 (уровень API 14)
Необходимо использовать ArCoreApk.checkAvailability() для проверки поддержки ARCore и состояния установки.
Необходимо использовать ArCoreApk.requestInstall() для установки сервисов Google Play для AR.

Дополнительные сведения см. в разделе Публикация приложений дополненной реальности в магазине 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" />

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

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

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

Затем убедитесь, что ваше приложение имеет по крайней мере требуемую minSdkVersion в файле build.gradle вашего приложения :

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

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

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

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

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

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

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

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  • Добавьте последнюю версию библиотеки ARCore в качестве зависимости в файл build.gradle вашего приложения :

    dependencies {
        …
        implementation 'com.google.ar:core:1.32.0'
    }
    

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

Проверьте, поддерживается ли ARCore

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

Джава

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  // Enable AR-related functionality on ARCore supported devices only.
  maybeEnableArButton();
  …
}

void maybeEnableArButton() {
  ArCoreApk.Availability availability = ArCoreApk.getInstance().checkAvailability(this);
  if (availability.isTransient()) {
    // Continue to query availability at 5Hz while compatibility is checked in the background.
    new Handler().postDelayed(new Runnable() {
      @Override
      public void run() {
        maybeEnableArButton();
      }
    }, 200);
  }
  if (availability.isSupported()) {
    mArButton.setVisibility(View.VISIBLE);
    mArButton.setEnabled(true);
  } else { // The device is unsupported or unknown.
    mArButton.setVisibility(View.INVISIBLE);
    mArButton.setEnabled(false);
  }
}

Котлин

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  // Enable AR-related functionality on ARCore supported devices only.
  maybeEnableArButton()
  …
}

fun maybeEnableArButton() {
  val availability = ArCoreApk.getInstance().checkAvailability(this)
  if (availability.isTransient) {
    // Continue to query availability at 5Hz while compatibility is checked in the background.
    Handler().postDelayed({
      maybeEnableArButton()
    }, 200)
  }
  if (availability.isSupported) {
    mArButton.visibility = View.VISIBLE
    mArButton.isEnabled = true
  } else { // The device is unsupported or unknown.
    mArButton.visibility = View.INVISIBLE
    mArButton.isEnabled = false
  }
}

Несмотря на то, что сервисы Google Play для дополненной реальности установлены вместе с вашим приложением, требующим дополненной реальности, пользователи неподдерживаемых устройств могут установить его из внешнего источника. Использование checkAvailability() для проверки поддержки ARCore обеспечивает единообразие работы.

checkAvailability() может потребоваться запросить сетевые ресурсы, чтобы определить, поддерживает ли устройство ARCore. В течение этого времени он вернет UNKNOWN_CHECKING . Чтобы уменьшить воспринимаемую задержку и всплывающие окна, приложения должны вызывать checkAvailability() один раз в начале своего жизненного цикла, чтобы инициировать запрос, игнорируя возвращаемое значение. Таким образом, кэшированный результат будет доступен сразу же после maybeEnableArButton() .

Запросить разрешение камеры

Приложения AR Optional и AR Required должны убедиться, что разрешение камеры было предоставлено перед созданием сеанса AR. Пример hello_ar_java включает класс CameraPermissionHelper , который можно скопировать в ваш проект и вызвать из метода onResume() вашей активности AR:

Джава

@Override
protected void onResume() {
  super.onResume();

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this);
    return;
  }

  …
}

Котлин

override fun onResume() {
  super.onResume()

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this)
    return
  }

  …
}

Ваша активность AR также должна реализовывать onRequestPermissionsResult() , как показано в HelloArActivity :

Джава

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] results) {
  super.onRequestPermissionsResult(requestCode, permissions, results);
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    Toast.makeText(this, "Camera permission is needed to run this application", Toast.LENGTH_LONG)
        .show();
    if (!CameraPermissionHelper.shouldShowRequestPermissionRationale(this)) {
      // Permission denied with checking "Do not ask again".
      CameraPermissionHelper.launchPermissionSettings(this);
    }
    finish();
  }
}

Котлин

override fun onRequestPermissionsResult(
  requestCode: Int,
  permissions: Array<String>,
  results: IntArray
) {
  super.onRequestPermissionsResult(requestCode, permissions, results)
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    Toast.makeText(this, "Camera permission is needed to run this application", Toast.LENGTH_LONG)
      .show()
    if (!CameraPermissionHelper.shouldShowRequestPermissionRationale(this)) {
      // Permission denied with checking "Do not ask again".
      CameraPermissionHelper.launchPermissionSettings(this)
    }
    finish()
  }
}

Проверьте, установлены ли сервисы Google Play для дополненной реальности.

Чтобы проверить, установлена ​​ли (все еще) совместимая версия Google Play Services для AR, и убедиться, что все необходимые данные профиля устройства ARCore были загружены, приложения AR Required и AR Additional должны вызывать ArCoreApk.requestInstall() перед созданием ARCore. сессия. Это предложит пользователю установить или обновить ARCore, если это необходимо, и обеспечит загрузку необходимых данных профиля устройства ARCore.

Джава

// requestInstall(Activity, true) will trigger installation of
// Google Play Services for AR if necessary.
private boolean mUserRequestedInstall = true;

@Override
protected void onResume() {
  super.onResume();

  // Check camera permission.
  …

  // Ensure that Google Play Services for AR and ARCore device profile data are
  // installed and up to date.
  try {
    if (mSession == null) {
      switch (ArCoreApk.getInstance().requestInstall(this, mUserRequestedInstall)) {
        case INSTALLED:
          // Success: Safe to create the AR session.
          mSession = new Session(this);
          break;
        case INSTALL_REQUESTED:
          // When this method returns `INSTALL_REQUESTED`:
          // 1. ARCore pauses this activity.
          // 2. ARCore prompts the user 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. ARCore resumes this activity. The next invocation of
          //    requestInstall() will either return `INSTALLED` or throw an
          //    exception if the installation or update did not succeed.
          mUserRequestedInstall = false;
          return;
      }
    }
  } catch (UnavailableUserDeclinedInstallationException e) {
    // Display an appropriate message to the user and return gracefully.
    Toast.makeText(this, "TODO: handle exception " + e, Toast.LENGTH_LONG)
        .show();
    return;
  } catch (…) {
    …
    return;  // mSession remains null, since session creation has failed.
  }
  …
}

Котлин

// requestInstall(Activity, true) will triggers installation of
// Google Play Services for AR if necessary.
var mUserRequestedInstall = true

override fun onResume() {
  super.onResume()

  // Check camera permission.
  …

  // Ensure that Google Play Services for AR and ARCore device profile data are
  // installed and up to date.
  try {
    if (mSession == null) {
      when (ArCoreApk.getInstance().requestInstall(this, mUserRequestedInstall)) {
        ArCoreApk.InstallStatus.INSTALLED -> {
          // Success: Safe to create the AR session.
          mSession = Session(this)
        }
        ArCoreApk.InstallStatus.INSTALL_REQUESTED -> {
          // When this method returns `INSTALL_REQUESTED`:
          // 1. ARCore pauses this activity.
          // 2. ARCore prompts the user 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. ARCore resumes this activity. The next invocation of
          //    requestInstall() will either return `INSTALLED` or throw an
          //    exception if the installation or update did not succeed.
          mUserRequestedInstall = false
          return
        }
      }
    }
  } catch (e: UnavailableUserDeclinedInstallationException) {
    // Display an appropriate message to the user and return gracefully.
    Toast.makeText(this, "TODO: handle exception " + e, Toast.LENGTH_LONG)
        .show()
    return
  } catch (…) {
    …
    return  // mSession remains null, since session creation has failed.
  }
  …
}

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

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

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