Enable AR in your Android NDK app

Enable AR to use augmented reality features in your new or existing app.

Configure your app to be AR Required or AR Optional

To save space on individual devices, all AR features are stored in an app called Google Play Services for AR that is updated separately by the Play Store. Android apps that use AR features communicate with Google Play Services for AR using the ARCore SDK. An app that supports AR features can be configured in two ways: AR Requiredand AR Optional. This designation determines how the app interacts with the Google Play Services for AR app.

An AR Requiredapp cannot function without ARCore. It requires an ARCore supported device that has installed Google Play Services for AR.

• The Google Play Store will only make AR Required apps available on devices that support ARCore.
• When users install an AR Required app, the Google Play Store will automatically install Google Play Services for AR on their device. However, your app must still perform additional runtime checks in case Google Play Services for AR is out of date or has been manually uninstalled.

An AR Optionalapp uses ARCore to enhance existing functionality. It has optional AR features which are only activated on ARCore supported devices that have installed Google Play Services for AR.

• AR Optional apps can be installed and run on devices that don’t support ARCore.
• When users install an AR Optional app, the Google Play Store will notautomatically install Google Play Services for AR on the device.

To make your app AR Required or AR Optional, update your AndroidManifest.xml to include the following entries:

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

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

Then, modify your app's build.gradle to specify a minSdkVersion of at least 24 :

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 } 

Add build dependencies

1. Make sure your project's build.gradle file includes Google's Maven repository.

    allprojects {
       repositories {
           google()
           …
       }
   } 
   

2. Add a custom task to your module's build.gradle file to extract included native libraries from the ARCore AAR file. This way, they can be referenced directly in a C or C++ project.

3. In the app/build directory, define a variable to the directory where the native libraries will be extracted to.

4. Create a Gradle configuration to hold the data and extraction tasks.

    /*
   The  
   ARCore  
   AAR  
   library  
   contains  
   native  
   shared  
   libraries  
   that  
   are
   extracted  
   before  
   building  
   to  
   a  
   temporary  
   directory.
   */
   def  
   arcore_libpath  
   =  
   " ${ 
    buildDir 
    } 
   /arcore-native"
   
   //  
   Create  
   a  
   configuration  
   to  
   mark  
   which  
   aars  
   to  
   extract  
   .so  
   files  
   from
   configurations  
   {  
   natives  
   } 
   

5. Create a task to copy the native libraries from the AAR file, and add it to the build dependencies.

     // Extracts the shared libraries from AARs in the native configuration 
    // so that NDK builds can access these libraries. 
    task 
     
    extractNativeLibraries 
    () 
     
    { 
     
    // Extract every time. 
     
    outputs 
    . 
    upToDateWhen 
     
    { 
     
    false 
     
    } 
     
    doFirst 
     
    { 
     
    configurations 
    . 
    natives 
    . 
    files 
    . 
    each 
     
    { 
     
    f 
     
    - 
   >  
    copy 
     
    { 
     
    from 
     
    zipTree 
    ( 
    f 
    ) 
     
    into 
     
    arcore_libpath 
     
    include 
     
    "jni/**/*" 
     
    } 
     
    } 
     
    } 
    } 
    tasks 
    . 
    whenTaskAdded 
     
    { 
     
    task 
    - 
   >  
    if 
     
    ( 
    task 
    . 
    name 
    . 
    contains 
    ( 
    "external" 
    ) 
    && 
   ! task 
    . 
    name 
    . 
    contains 
    ( 
    "Clean" 
    )) 
     
    { 
     
    task 
    . 
    dependsOn 
    ( 
    extractNativeLibraries 
    ) 
     
    } 
    } 
    
   

6. Configure the native build flags to pass the locations to the external build tools.

    //  
   From  
   the  
   sample  
   app.
   externalNativeBuild  
   {  
   cmake  
   {  
   cppFlags  
   "-std=c++11",  
   "-Wall"  
   arguments  
   "-DANDROID_STL=c++_static",  
   "-DARCORE_LIBPATH= ${ 
    arcore_libpath 
    } 
   /jni",  
   "-DARCORE_INCLUDE= ${ 
    project 
    . 
    rootDir 
    } 
   /../../libraries/include"  
   }
   } 
   

7. Add the dependencies for both the Java and the native libraries.

     dependencies 
     
    { 
     
    ... 
     
    // Add Java and native dependencies to the ARCore library. 
     
    implementation 
     
    ' 
    com 
    . 
    google 
    . 
    ar 
    : 
    core 
    : 
    1.33.0 
    ' 
     
    natives 
     
    ' 
    com 
    . 
    google 
    . 
    ar 
    : 
    core 
    : 
    1.33.0 
    ' 
     
    ... 
    } 
    
   

8. Reference the native libraries in CMakeLists.txt .

    #  
   Import  
   the  
   ARCore  
   library.
   add_library(arcore  
   SHARED  
   IMPORTED)
   set_target_properties(arcore  
   PROPERTIES  
   IMPORTED_LOCATION  
    ${ 
    ARCORE_LIBPATH 
    } 
   / ${ 
    ANDROID_ABI 
    } 
   /libarcore_sdk_c.so  
   INTERFACE_INCLUDE_DIRECTORIES  
    ${ 
    ARCORE_INCLUDE 
    } 
   ) 
   

Perform runtime checks

During runtime, perform the following to ensure that AR features on your app run smoothly.

Check if ARCore is supported

An Android NDK app may use the Java ArCoreApk class to check compatibility and manage installation in the native C ARCore Session API. Depending on the structure of your app, this may be easier than using the ArCoreApk_ functions due to the large amount of error handling and user interface interaction involved.

 void maybeEnableArButton(JNIEnv env, jobject context) {
  // Likely called from Activity.onCreate() of an activity with AR buttons.
  ArAvailability availability
  ArCoreApk_checkAvailability(env, context, &availability);
  if (availability == AR_AVAILABILITY_UNKNOWN_CHECKING) {
    // Set a timer to call maybeEnableArButton() again after about 200ms.
  }
  if (availability == AR_AVAILABILITY_SUPPORTED_NOT_INSTALLED ||
      availability == AR_AVAILABILITY_SUPPORTED_APK_TOO_OLD ||
      availability == AR_AVAILABILITY_SUPPORTED_INSTALLED) {
    // Show or enable the AR button.
  } else {
    // Hide or disable the AR button.
  }
} 

ArCoreApk_checkAvailability() may need to query network resources to determine whether the device supports ARCore. During this time, it will return AR_AVAILABILITY_UNKNOWN_CHECKING . To reduce the perceived latency and pop-in, apps should call ArCoreApk_checkAvailability() once early in its life cycle to initiate the query, ignoring the returned value. This way, a cached result will be available immediately when an AR-entering UI element might be displayed.

Check if Google Play Services for AR is installed

Both AR Required and AR Optional apps must use ArCoreApk.requestInstall() before creating an ARCore session to check whether a compatible version of Google Play Services for AR is (still) installed and to ensure that all required ARCore device profile data has been downloaded.

  // 
  
 Tracks 
  
 if 
  
 an 
  
 installation 
  
 request 
  
 has 
  
 already 
  
 been 
  
 triggered 
 . 
 bool 
  
 install_requested_ 
 ; 
 void 
  
 nativeOnCreate 
 () 
  
 { 
  
 // 
  
 Do 
  
 other 
  
 setup 
  
 here 
 . 
  
 install_requested_ 
  
 = 
  
 false 
 ; 
 } 
 void 
  
 nativeOnResume 
 ( 
 JNIEnv 
  
 env 
 , 
  
 jobject 
  
 activity 
 ) 
  
 { 
  
 if 
  
 ( 
 ar_session_ 
  
 == 
  
 null 
 ) 
  
 { 
  
 bool 
  
 user_requested_install 
  
 = 
  
 ! 
 install_requested_ 
 ; 
  
 ArInstallStatus 
  
 install_status 
 ; 
  
 // 
  
 Ensure 
  
 that 
  
 Google 
  
 Play 
  
 Services 
  
 for 
  
 AR 
  
 and 
  
 ARCore 
  
 device 
  
 profile 
  
 data 
  
 are 
  
 // 
  
 installed 
  
 and 
  
 up 
  
 to 
  
 date 
 . 
  
 ArStatus 
  
 error 
  
 = 
  
 ArCoreApk_requestInstall 
 ( 
  
 env 
 , 
  
 activity 
 , 
  
 user_requested_install 
 , 
  
& install_status 
 ); 
  
 if 
  
 ( 
 error 
  
 != 
  
 AR_SUCCESS 
 ) 
  
 { 
  
 // 
  
 Inform 
  
 user 
  
 of 
  
 error 
 . 
  
 return 
 ; 
  
 } 
  
 switch 
  
 ( 
 install_status 
 ) 
  
 { 
  
 case 
  
 AR_INSTALL_STATUS_INSTALLED 
 : 
  
 break 
 ; 
  
 case 
  
 AR_INSTALL_STATUS_INSTALL_REQUESTED 
 : 
  
 // 
  
 When 
  
 this 
  
 method 
  
 returns 
  
 AR_INSTALL_STATUS_INSTALL_REQUESTED 
 : 
  
 // 
  
 1. 
  
 This 
  
 activity 
  
 will 
  
 be 
  
 paused 
 . 
  
 // 
  
 2. 
  
 The 
  
 user 
  
 is 
  
 prompted 
  
 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. 
  
 This 
  
 activity 
  
 is 
  
 resumed 
 . 
  
 The 
  
 next 
  
 invocation 
  
 of 
  
 // 
  
 ArCoreApk_requestInstall 
 () 
  
 will 
  
 either 
  
 return 
  
 // 
  
 AR_INSTALL_STATUS_INSTALLED 
  
 or 
  
 throw 
  
 an 
  
 exception 
  
 if 
  
 the 
  
 // 
  
 installation 
  
 or 
  
 update 
  
 did 
  
 not 
  
 succeed 
 . 
  
 install_requested_ 
  
 = 
  
 true 
 ; 
  
 return 
 ; 
  
 } 
  
 // 
  
 Request 
  
 camera 
  
 permissions 
 . 
  
 error 
  
 = 
  
 ArSession_create 
 ( 
 env 
 , 
  
 context 
 , 
  
& ar_session_ 
 ); 
  
 if 
  
 ( 
 error 
  
 != 
  
 AR_SUCCESS 
 ) 
  
 { 
  
 // 
  
 Inform 
  
 user 
  
 of 
  
 error 
 . 
  
 return 
 ; 
  
 } 
  
 // 
  
 Configure 
  
 the 
  
 ARCore 
  
 session 
 . 
  
 } 
  
 // 
  
 Normal 
  
 onResume 
  
 behavior 
 . 
 } 
 

Comply with User Privacy Requirements

To publish your app on the Play Store, make sure that your app complies with ARCore's User Privacy Requirements .

What’s next

• Learn how to configure an ARCore session .