Habilita la RA en tu app para Android

Habilita la RA para usar las funciones de realidad aumentada en tu app nueva o existente.

Configura tu app como AR Required o AR Optional

Para ahorrar espacio en los dispositivos individuales, todas las funciones de RA se almacenan en una app llamada Servicios de Google Play para RA que Play Store actualiza por separado. Las apps para Android que usan funciones de RA se comunican con los Servicios de Google Play para RA a través del SDK de ARCore. Una app que admite funciones de RA se puede configurar de dos maneras: RA obligatoria y RA opcional. Esta designación determina cómo interactúa la app con la app de Servicios de Google Play para RA.

Una app con la etiqueta AR Required no puede funcionar sin ARCore. Requiere un dispositivo compatible con ARCore que tenga instalados los Servicios de Google Play para RA.

• Google Play Store solo pondrá a disposición las apps que requieren RA en los dispositivos que admiten ARCore.
• Cuando los usuarios instalen una app que requiere RA, Google Play Store instalará automáticamente los Servicios de Google Play para RA en sus dispositivos. Sin embargo, tu app debe realizar verificaciones adicionales en el tiempo de ejecución en caso de que los Servicios de Google Play para RA estén desactualizados o se hayan desinstalado manualmente.

Una app AR Optional usa ARCore para mejorar la funcionalidad existente. Tiene funciones de RA opcionales que solo se activan en dispositivos compatibles con ARCore que tienen instalados los Servicios de Google Play para RA.

• Las apps de AR Optional se pueden instalar y ejecutar en dispositivos que no admiten ARCore.
• Cuando los usuarios instalan una app con RA opcional, Google Play Store no instalará automáticamente los Servicios de Google Play para RA en el dispositivo.

	AR Required	RA opcional
Uso de la función de RA	Tu app necesita ARCore para la funcionalidad básica.	ARCore aumenta la funcionalidad de tu app. Tu app puede ejecutarse sin compatibilidad con ARCore.
Visibilidad en Play Store	Tu app solo aparece en Play Store en dispositivos que admiten ARCore.	Tu app sigue los procedimientos normales de la ficha.
Método de instalación de los Servicios de Google Play para RA	Play Store instala los Servicios de Google Play para RA junto con tu app.	Tu app usa ArCoreApk.requestInstall() para descargar e instalar ARCore.
Requisitos de Android minSdkVersion	Android 7.0 (nivel de API 24)	Android 4.4 (nivel de API 19), aunque ejecutar cualquier funcionalidad de RA requiere al menos Android 7.0 (nivel de API 24)
Debe usar ArCoreApk.checkAvailability() o ArCoreApk.checkAvailabilityAsync() para verificar la compatibilidad con ARCore y el estado de instalación.
Debes usar ArCoreApk.requestInstall() para instalar los Servicios de Google Play para RA.

Para que tu app sea obligatoria o opcional para AR, actualiza tu AndroidManifest.xml para incluir las siguientes entradas:

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 opcional

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

Luego, modifica el build.gradle de tu app para especificar un minSdkVersion de al menos 24:

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

Cómo agregar dependencias de compilación

Para agregar ARCore a tu proyecto de Android Studio, haz lo siguiente:

1. Asegúrate de que el archivo build.gradle de tu proyecto incluya el repositorio de Maven de Google.

   allprojects {
       repositories {
           google()
           …
       }
   }
   

2. Agrega la biblioteca de ARCore más reciente como una dependencia en el archivo build.gradle de tu app.

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

Realiza verificaciones de tiempo de ejecución

Durante el tiempo de ejecución, realiza las siguientes acciones para asegurarte de que las funciones de RA de tu app se ejecuten sin problemas.

Cómo verificar si se admite ARCore

Las apps que requieren RA y las que lo ofrecen como opción deben usar ArCoreApk.checkAvailability() o ArCoreApk.checkAvailabilityAsync() para determinar si el dispositivo actual admite ARCore. En los dispositivos que no admiten ARCore, las apps deben inhabilitar la funcionalidad relacionada con la RA y ocultar los elementos de la IU asociados.

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

Aunque los Servicios de Google Play para RA se instalan junto con tu app que requiere RA, es posible que los usuarios con dispositivos no compatibles la instalen desde una fuente externa. Usar ArCoreApk.checkAvailability() o ArCoreApk.checkAvailabilityAsync() para verificar la compatibilidad con ARCore garantiza una experiencia coherente.

ArCoreApk.checkAvailability() puede necesitar consultar recursos de red para determinar si el dispositivo admite ARCore. Durante este tiempo, devolverá UNKNOWN_CHECKING. Para reducir la latencia percibida y la aparición repentina, las apps deben llamar a ArCoreApk.checkAvailability() una vez al principio de su ciclo de vida para iniciar la consulta, ignorando el valor devuelto. De esta manera, un resultado almacenado en caché estará disponible de inmediato cuando se muestre un elemento de la IU para ingresar a la RA.

Cómo verificar si los Servicios de Google Play para RA están instalados

Las apps que requieren RA y las que la ofrecen como opción deben usar ArCoreApk.requestInstall() antes de crear una sesión de ARCore para verificar si se instaló (o sigue instalada) una versión compatible de los Servicios de Google Play para RA y garantizar que se hayan descargado todos los datos de perfil del dispositivo de ARCore necesarios.

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

Solicita permiso de acceso a la cámara

Tanto las apps con RA opcional como las que requieren RA deben asegurarse de que se haya otorgado el permiso de acceso a la cámara antes de crear una sesión de RA.

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

  …
}

Tu actividad de RA también debe implementar 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();
  }
}

Cumple con los requisitos de privacidad del usuario

Para publicar tu app en Play Store, asegúrate de que cumpla con los Requisitos de Privacidad del Usuario de ARCore.

Próximos pasos

• Obtén más información para configurar una sesión de ARCore.