Android アプリで AR を有効にする

AR を有効にすると、新規または既存のアプリで拡張現実機能を使用できます。

AR 必須または AR オプションにアプリを構成する

個々のデバイスの容量を節約するため、AR 機能はすべて、Google Play ストアで個別に更新される「Google Play 開発者サービス(AR)」というアプリに保存されます。AR 機能を使用する Android アプリは、ARCore SDK を使用して AR 用 Google Play 開発者サービスと通信します。AR 機能をサポートするアプリは、AR 必須AR オプションの 2 つの方法で設定できます。この指定によって、アプリと AR 用 Google Play 開発者サービスのアプリとの連携方法が決まります。

[AR 必須] アプリは、ARCore なしでは機能しません。AR 用の Google Play 開発者サービスがインストールされている ARCore 対応デバイスが必要です。

  • Google Play ストアの AR 必須アプリは、ARCore をサポートするデバイスでのみ利用可能になります。
  • ユーザーが AR 必須アプリをインストールすると、Google Play ストアの AR 向け Google Play 開発者サービスがユーザーのデバイスに自動的にインストールされます。ただし、Google Play 開発者サービス(AR)が古い場合や手動でアンインストールした場合は、アプリで追加のランタイム チェックを行う必要があります。

AR Optional アプリは、ARCore を使用して既存の機能を強化します。オプションの AR 機能があり、Google Play 開発者サービス(AR)がインストールされている ARCore 対応デバイスでのみ有効になります。

  • AR Optional アプリは、ARCore をサポートしていないデバイスにインストールして実行できます。
  • ユーザーが AR Optional アプリをインストールしても、Google Play ストアからデバイスに AR 用 Google Play 開発者サービスが自動的にインストールされることはありません
AR が必要AR(オプション)
AR 機能の使用状況 基本的な機能を使用するには ARCore が必要です。 ARCore はアプリの機能を強化します。アプリは ARCore のサポートなしで実行できます。
Google Play ストアの公開設定 アプリは ARCore をサポートするデバイスの Play ストアにのみ掲載される。 アプリは通常の掲載情報の手順に沿っている。
AR 用 Google Play 開発者サービスのインストール方法 Play ストアによって、アプリとともに AR 用 Google Play 開発者サービスがインストールされます。 このアプリでは ArCoreApk.requestInstall() を使用して ARCore をダウンロードしてインストールしています。
Android minSdkVersion の要件 Android 7.0(API レベル 24) Android 7.0(API レベル 24)
ARCore のサポートとインストール ステータスを確認するには、ArCoreApk.checkAvailability() または ArCoreApk.checkAvailabilityAsync() を使用する必要があります
AR 用 Google Play 開発者サービスをインストールするには、ArCoreApk.requestInstall() を使用する必要があります

アプリを AR 必須または AR オプションにするには、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 を変更して、24 以上の minSdkVersion を指定します。

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

ビルド依存関係を追加する

Android Studio プロジェクトに ARCore を追加する手順は次のとおりです。

  1. プロジェクトの build.gradle ファイルに Google の Maven リポジトリが含まれていることを確認します。

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  2. アプリの build.gradle ファイルに、最新の ARCore ライブラリを依存関係として追加します。

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

ランタイム チェックを実行する

アプリの AR 機能がスムーズに動作するように、実行時に次のことを行います。

ARCore がサポートされているかどうかを確認する

AR 必須アプリと AR オプションアプリの両方で、ArCoreApk.checkAvailability() または ArCoreApk.checkAvailabilityAsync() を使用して、現在のデバイスが ARCore をサポートしているかどうかを判断する必要があります。ARCore をサポートしていないデバイスでは、AR 関連の機能を無効にして、関連する UI 要素を非表示にする必要があります。

Kotlin

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);
    }
  });
}
AR 用 Google Play 開発者サービスが AR 必須アプリと一緒にインストールされていても、サポートされていないデバイスを使用しているユーザーが外部ソースからインストールする可能性があります。ArCoreApk.checkAvailability() または ArCoreApk.checkAvailabilityAsync() を使用して ARCore のサポート状況を確認すると、一貫したエクスペリエンスが保証されます。

ArCoreApk.checkAvailability() は、デバイスが ARCore をサポートしているかどうかを判断するために、ネットワーク リソースをクエリする必要がある場合があります。この間は UNKNOWN_CHECKING が返されます。認識されるレイテンシとポップインを減らすため、アプリはライフサイクルの早い段階で ArCoreApk.checkAvailability() を呼び出してクエリを開始し、戻り値を無視する必要があります。これにより、AR 入力 UI 要素が表示される可能性があるときに、キャッシュに保存された結果をすぐに利用できるようになります。

Google Play 開発者サービス(AR)がインストールされているかどうかを確認する

AR 必須アプリと AR オプションのアプリは、ARCore セッションを作成する前に ArCoreApk.requestInstall() を呼び出して、互換性のあるバージョンの Google Play 開発者サービス(AR)が(まだ)インストールされていることを確認し、必要な ARCore デバイス プロファイル データがすべてダウンロードされていることを確認する必要があります。

Kotlin

// 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 オプションアプリと AR 必須アプリは、どちらも AR セッションを作成する前にカメラへのアクセス許可が付与されていることを確認する必要があります。

Kotlin

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() も実装する必要があります。

Kotlin

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 ストアでアプリを公開するには、アプリが ARCore のユーザー プライバシー要件を遵守していることをご確認ください。

次のステップ