Включите AR в своем приложении для Android

Включите поддержку дополненной реальности (AR) для использования функций дополненной реальности в вашем новом или существующем приложении.

Настройте ваше приложение так, чтобы оно было обязательным или необязательным для использования дополненной реальности.

Для экономии места на отдельных устройствах все функции дополненной реальности хранятся в приложении Google Play Services for AR , которое обновляется отдельно через Play Store. Приложения Android, использующие функции дополненной реальности, взаимодействуют с Google Play Services for AR с помощью SDK ARCore. Приложение, поддерживающее функции дополненной реальности, может быть настроено двумя способами: AR Required и AR Optional . Это обозначение определяет, как приложение взаимодействует с приложением Google Play Services for AR.

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

  • В магазине Google Play приложения, требующие дополненной реальности (AR Required), будут доступны только на устройствах, поддерживающих ARCore.
  • Когда пользователи устанавливают приложение, требующее поддержки дополненной реальности (AR Required), Google Play Store автоматически устанавливает на их устройство сервисы Google Play Services for AR. Однако ваше приложение всё равно должно выполнять дополнительные проверки во время работы на случай, если сервисы Google Play Services for AR устарели или были удалены вручную.

Приложение с поддержкой дополненной реальности (AR Optional) использует ARCore для расширения существующей функциональности. Оно имеет дополнительные функции дополненной реальности, которые активируются только на устройствах с поддержкой ARCore, на которых установлены сервисы Google Play для дополненной реальности.

  • Приложения с поддержкой дополненной реальности (AR Optional) можно устанавливать и запускать на устройствах, не поддерживающих ARCore.
  • Когда пользователи устанавливают приложение, поддерживающее дополненную реальность (AR Optional), Google Play Store не устанавливает автоматически сервисы Google Play для дополненной реальности на устройство.
Требуется допуск к секретной информации (AR). AR (необязательно)
Использование функций дополненной реальности Для работы базовых функций вашему приложению необходим ARCore. ARCore расширяет функциональность вашего приложения. Ваше приложение может работать и без поддержки ARCore.
видимость в Play Store Ваше приложение отображается в Play Store только на устройствах, поддерживающих ARCore. Ваше приложение соответствует стандартным процедурам размещения .
Способ установки Google Play Services для AR Play Store устанавливает сервисы Google Play для дополненной реальности вместе с вашим приложением. Ваше приложение использует ArCoreApk.requestInstall() для загрузки и установки ARCore.
Требования minSdkVersion Android Android 7.0 (уровень API 24) Android 4.4 (уровень API 19), хотя для работы любых функций дополненной реальности требуется как минимум Android 7.0 (уровень API 24).
Для проверки поддержки ARCore и статуса установки необходимо использовать ArCoreApk.checkAvailability() или ArCoreApk.checkAvailabilityAsync()
Для установки сервисов Google Play для дополненной реальности необходимо использовать ArCoreApk.requestInstall()

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

Требуется допуск к секретной информации (AR). 

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

AR (необязательно) 

<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 не менее 24 :

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

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

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

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

    allprojects {
    repositories {
        google()
        …
    }
}

  2. Добавьте последнюю версию библиотеки ARCore в качестве зависимости в файл build.gradle вашего приложения.

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

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

Во время выполнения программы выполните следующие действия, чтобы обеспечить бесперебойную работу функций дополненной реальности в вашем приложении.

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

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

Котлин 

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

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

fun maybeEnableArButton() {
  ArCoreApk.getInstance().checkAvailabilityAsync(this) { availability ->
    if (availability.isSupported) {
      mArButton.visibility = View.VISIBLE
      mArButton.isEnabled = true
    } else { // The device is unsupported or unknown.
      mArButton.visibility = View.INVISIBLE
      mArButton.isEnabled = false
    }
  }
}

Java 

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

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

void maybeEnableArButton() {
  ArCoreApk.getInstance().checkAvailabilityAsync(this, availability -> {
    if (availability.isSupported()) {
      mArButton.setVisibility(View.VISIBLE);
      mArButton.setEnabled(true);
    } else { // The device is unsupported or unknown.
      mArButton.setVisibility(View.INVISIBLE);
      mArButton.setEnabled(false);
    }
  });
}
Даже если Google Play Services for AR установлен вместе с вашим приложением, требующим поддержки AR, пользователи устройств, не поддерживающих AR, могут установить его из внешнего источника. Использование ArCoreApk.checkAvailability() или ArCoreApk.checkAvailabilityAsync() для проверки поддержки ARCore обеспечит стабильную работу.

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

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

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

Котлин 

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

Java 

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

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

Как приложения с обязательным доступом к камере (AR Optional), так и приложения с обязательным доступом к камере (AR Required) должны убедиться, что разрешение на использование камеры предоставлено до создания сеанса дополненной реальности (AR Session).

Котлин 

override fun onResume() {
  super.onResume()

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

  …
}

Java 

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

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

  …
}

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

Котлин 

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()
  }
}

Java 

@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();
  }
}

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

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

Что дальше?