Activer la RA dans votre application Android

Activez la RA pour utiliser les fonctionnalités de réalité augmentée dans votre application nouvelle ou existante.

Configurer votre application pour qu'elle soit "RA requise" ou "RA facultative"

Pour économiser de l'espace sur les appareils individuels, toutes les fonctionnalités de RA sont stockées dans une application appelée Services Google Play pour la RA, qui est mise à jour séparément par le Play Store. Les applications Android qui utilisent des fonctionnalités de RA communiquent avec les Services Google Play pour la RA à l'aide du SDK ARCore. Une application compatible avec les fonctionnalités de RA peut être configurée de deux manières : RA requise et RA facultative. Cette désignation détermine la façon dont l'application interagit avec l'application Services Google Play pour la RA.

Une application AR Required ne peut pas fonctionner sans ARCore. Il nécessite un appareil compatible avec ARCore sur lequel les Services Google Play pour la RA sont installés.

• Le Google Play Store ne proposera les applications "RA requise" que sur les appareils compatibles avec ARCore.
• Lorsque les utilisateurs installent une application nécessitant la RA, le Google Play Store installe automatiquement les Services Google Play pour la RA sur leur appareil. Toutefois, votre application doit toujours effectuer des vérifications d'exécution supplémentaires au cas où les services Google Play pour la RA seraient obsolètes ou auraient été désinstallés manuellement.

Une application RA facultative utilise ARCore pour améliorer les fonctionnalités existantes. Elle propose des fonctionnalités de RA facultatives qui ne sont activées que sur les appareils compatibles ARCore sur lesquels les services Google Play pour la RA sont installés.

• Les applications AR Optional peuvent être installées et exécutées sur des appareils qui ne sont pas compatibles avec ARCore.
• Lorsque les utilisateurs installent une application AR Optional, le Google Play Store n'installe pas automatiquement les services Google Play pour la RA sur l'appareil.

	AR Required	RA facultative
Utilisation des fonctionnalités de RA	Votre application a besoin d'ARCore pour les fonctionnalités de base.	ARCore augmente les fonctionnalités de votre application. Votre application peut s'exécuter sans la prise en charge d'ARCore.
Visibilité sur le Play Store	Votre application n'est listée sur le Play Store que sur les appareils compatibles avec ARCore.	Votre application suit les procédures de fiche habituelles.
Méthode d'installation des Services Google Play pour la RA	Le Play Store installe les Services Google Play pour la RA en même temps que votre application.	Votre application utilise ArCoreApk.requestInstall() pour télécharger et installer ARCore.
Exigences concernant Android minSdkVersion	Android 7.0 (niveau d'API 24)	Android 4.4 (niveau d'API 19), mais l'exécution de toute fonctionnalité de RA nécessite au moins Android 7.0 (niveau d'API 24)
Vous devez utiliser ArCoreApk.checkAvailability() ou ArCoreApk.checkAvailabilityAsync() pour vérifier la compatibilité avec ARCore et l'état de l'installation.
Vous devez utiliser ArCoreApk.requestInstall() pour installer les Services Google Play pour la RA.

Pour que votre application soit requise ou facultative pour la RA, mettez à jour votre fichier AndroidManifest.xml afin d'inclure les entrées suivantes :

AR Required

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

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

Modifiez ensuite le build.gradle de votre application pour spécifier un minSdkVersion d'au moins 24 :

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

Ajouter des dépendances de build

Pour ajouter ARCore à votre projet Android Studio, procédez comme suit :

1. Assurez-vous que le fichier build.gradle de votre projet inclut le dépôt Maven de Google.

   allprojects {
       repositories {
           google()
           …
       }
   }
   

2. Ajoutez la dernière bibliothèque ARCore en tant que dépendance dans le fichier build.gradle de votre application.

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

Effectuer des vérifications à l'exécution

Pendant l'exécution, effectuez les opérations suivantes pour vous assurer que les fonctionnalités de RA de votre application fonctionnent correctement.

Vérifier si ARCore est pris en charge

Les applications AR requises et AR facultatives doivent utiliser ArCoreApk.checkAvailability() ou ArCoreApk.checkAvailabilityAsync() pour déterminer si l'appareil actuel est compatible avec ARCore. Sur les appareils qui ne sont pas compatibles avec ARCore, les applications doivent désactiver les fonctionnalités liées à la RA et masquer les éléments d'interface utilisateur associés.

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

Même si les Services Google Play pour la RA sont installés en même temps que votre application requise pour la RA, les utilisateurs dont l'appareil n'est pas compatible peuvent l'installer à partir d'une source externe. L'utilisation de ArCoreApk.checkAvailability() ou ArCoreApk.checkAvailabilityAsync() pour vérifier la compatibilité avec ARCore garantit une expérience cohérente.

ArCoreApk.checkAvailability() peut avoir besoin d'interroger les ressources réseau pour déterminer si l'appareil est compatible avec ARCore. Pendant ce temps, il renverra UNKNOWN_CHECKING. Pour réduire la latence perçue et le pop-in, les applications doivent appeler ArCoreApk.checkAvailability() une fois au début de leur cycle de vie pour lancer la requête, en ignorant la valeur renvoyée. Ainsi, un résultat mis en cache sera disponible immédiatement lorsqu'un élément d'interface utilisateur d'entrée en RA peut être affiché.

Vérifier si les Services Google Play pour la RA sont installés

Les applications "RA requise" et "RA facultative" doivent utiliser ArCoreApk.requestInstall() avant de créer une session ARCore pour vérifier si une version compatible des Services Google Play pour la RA est (toujours) installée et pour s'assurer que toutes les données de profil d'appareil ARCore requises ont été téléchargées.

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

Demander l'autorisation d'accès à l'appareil photo

Les applications AR facultatives et AR requises doivent s'assurer que l'autorisation d'accès à l'appareil photo a été accordée avant de créer une session 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;
  }

  …
}

Votre activité de RA doit également implémenter 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();
  }
}

Respecter les exigences concernant la confidentialité des utilisateurs

Pour publier votre application sur le Play Store, assurez-vous qu'elle respecte les exigences d'ARCore concernant la confidentialité des utilisateurs.

Étapes suivantes

• Découvrez comment configurer une session ARCore.