Ative a RA para usar os recursos de realidade aumentada no seu app novo ou existente.
Configure seu app para que ele seja compatível com RA ou opcional
Para economizar espaço em dispositivos individuais, todos os recursos de RA são armazenados em um app chamado Google Play Services para RA, que é atualizado separadamente pela Play Store. Os apps Android que usam recursos de RA se comunicam com o Google Play Services para RA usando o SDK do ARCore. Um app compatível com recursos de RA pode ser configurado de duas maneiras: RA necessária e RA opcional. Essa designação determina como o app interage com o app Google Play Services para RA.
Um app AR required não funciona sem o ARCore. É necessário um dispositivo compatível com o ARCore que tenha instalado o Google Play Services para RA.
- A Google Play Store só vai disponibilizar os apps necessários para RA em dispositivos compatíveis com o ARCore.
- Quando os usuários instalam um app de RA obrigatório, a Google Play Store instala automaticamente o Google Play Services para RA no dispositivo. No entanto, o app ainda vai precisar fazer mais verificações no tempo de execução caso o Google Play Services para RA esteja desatualizado ou tenha sido desinstalado manualmente.
Um app opcional de RA usa o ARCore para melhorar a funcionalidade existente. Ela tem recursos opcionais de RA que são ativados apenas em dispositivos com suporte ao ARCore e que tenham instalado o Google Play Services para RA.
- Os apps opcionais de RA podem ser instalados e executados em dispositivos sem suporte ao ARCore.
- Quando os usuários instalam um app opcional de RA, a Google Play Store não instala automaticamente o Google Play Services para RA no dispositivo.
RA obrigatória | RA opcional | |
---|---|---|
Uso de recursos de RA | Seu app precisa do ARCore para a funcionalidade básica. | O ARCore aumenta a funcionalidade do seu app. Seu app pode ser executado sem suporte ao ARCore. |
Visibilidade na Play Store | Seu app só está disponível na Play Store em dispositivos compatíveis com ARCore. | Seu app segue os procedimentos normais de informações do produto. |
Método de instalação do Google Play Services para RA | A Play Store instala o Google Play Services para RA junto com seu app. | O app usa o ArCoreApk.requestInstall() para fazer o download e instalar o ARCore. |
Requisitos do Android minSdkVersion |
Android 7.0 (API de nível 24) | Android 7.0 (API de nível 24) |
É preciso usar ArCoreApk.checkAvailability() ou ArCoreApk.checkAvailabilityAsync() para verificar o suporte e o status da instalação do ARCore |
||
Precisa usar o ArCoreApk.requestInstall() ao instalar o Google Play Services para RA |
Para tornar o app obrigatória ou opcional, atualize o AndroidManifest.xml
para incluir as seguintes entradas:
RA obrigatória
<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>
Em seguida, modifique a build.gradle
do app para especificar um minSdkVersion
de pelo menos 24
:
android {
defaultConfig {
…
minSdkVersion 24
}
}
Adicionar dependências do build
Para adicionar o ARCore ao seu projeto do Android Studio, faça o seguinte:
Verifique se o arquivo
build.gradle
do projeto inclui o repositório Maven do Google.allprojects { repositories { google() … } }
Adicione a biblioteca ARCore mais recente como uma dependência no arquivo
build.gradle
do seu app.dependencies { … implementation 'com.google.ar:core:1.33.0' }
Realizar verificações no ambiente de execução
Durante o tempo de execução, faça o seguinte para garantir que os recursos de RA do seu app funcionem sem problemas.
Verificar se há suporte para o ARCore
Tanto os apps de RA necessária quanto os opcionais de RA precisam usarArCoreApk.checkAvailability()
ou ArCoreApk.checkAvailabilityAsync()
para determinar se o dispositivo atual é compatível com o ARCore. Em dispositivos que não oferecem suporte a ARCore, os apps precisam desativar as funcionalidades relacionadas à RA e ocultar os elementos de IU associados.
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);
}
});
}
ArCoreApk.checkAvailability()
ou ArCoreApk.checkAvailabilityAsync()
para verificar a compatibilidade com o ARCore garante uma experiência consistente.
O ArCoreApk.checkAvailability()
pode precisar consultar recursos de rede para determinar se o dispositivo é compatível com ARCore. Durante esse período, ele vai retornar UNKNOWN_CHECKING
. Para reduzir a latência percebida e o pop-in, os apps precisam chamar ArCoreApk.checkAvailability()
no início do ciclo de vida para iniciar a consulta, ignorando o valor retornado. Dessa forma, um resultado armazenado em cache vai ficar disponível imediatamente quando um elemento da interface de entrada em RA for exibido.
Conferir se o Google Play Services para RA está instalado
Os apps de RA necessária e opcionais de RA precisam chamar ArCoreApk.requestInstall()
antes de criar uma sessão do ARCore para conferir se uma versão compatível do Google Play Services para RA está (ainda) instalada e se todos os dados necessários do perfil do ARCore no dispositivo foram transferidos por download.
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.
}
…
}
Solicitar permissão para usar a câmera
Os apps opcionais e obrigatórios de RA precisam garantir que a permissão da câmera tenha sido concedida antes de criar uma sessão 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;
}
…
}
Sua atividade de RA também precisa 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();
}
}
Cumpra os requisitos de privacidade do usuário
Para publicar seu app na Play Store, verifique se ele obedece aos requisitos de privacidade do usuário do ARCore.
O que vem em seguida?
- Saiba como configurar uma sessão do ARCore.