ARCore चालू करें

इस पेज पर, आपके Android NDK प्रोजेक्ट में ARCore फ़ंक्शन को चालू करने का तरीका बताया गया है. ऐसा करने के लिए, ये गतिविधियां ज़रूरी हैं:

  1. मेनिफ़ेस्ट में एआर (ऑगमेंटेड रिएलिटी) या एआर (ऑगमेंटेड रिएलिटी) वाला विकल्प जोड़ना
  2. अपने प्रोजेक्ट में बिल्ड डिपेंडेंसी जोड़ना
  3. रनटाइम की जांच-पड़ताल करके पक्का करें कि डिवाइस ARCore की सुविधा के साथ काम करता है और डिवाइस पर Google Play Services for AR इंस्टॉल है
  4. पक्का करें कि आपका ऐप्लिकेशन ARCore'उपयोगकर्ता की निजता से जुड़ी ज़रूरी शर्तों का पालन करता हो

Google Play Services for AR

ARCore SDK टूल, ARCore की सुविधा वाले डिवाइसों पर उपलब्ध कराता है. इन डिवाइसों में AR के लिए Google Play सेवाएं (ARCore) इंस्टॉल किया गया है.

Google Play Services for AR, उन ज़्यादातर डिवाइसों पर अपने-आप इंस्टॉल और अप-टू-डेट हो जाता है जिन पर यह सुविधा काम करती है.

एआर (ऑगमेंटेड रिएलिटी) सेशन शुरू करने से पहले, ऐप्लिकेशन को:

  1. ArCoreApk_checkAvailability को कॉल करके देखें कि ARCore काम करता है या नहीं.
  2. जांचें कि AR के लिए Google Play सेवाएं इंस्टॉल और अप टू डेट हैं या नहीं और यह कि ArCoreApk_requestInstallको कॉल करके ज़रूरी ARCore डिवाइस प्रोफ़ाइल डेटा डाउनलोड किया गया है या नहीं.

मेनिफ़ेस्ट में एआर (ऑगमेंटेड रिएलिटी) या एआर (ऑगमेंटेड रिएलिटी) का विकल्प जोड़ना ज़रूरी नहीं है

एआर (ऑगमेंटेड रिएलिटी) सुविधाओं के साथ काम करने वाले ऐप्लिकेशन को दो तरीकों से कॉन्फ़िगर किया जा सकता है: एआर (ऑगमेंटेड रिएलिटी) और एआर (ऑगमेंटेड रिएलिटी) ज़रूरी नहीं.

एआर (ऑगमेंटेड रिएलिटी) ज़रूरी है

इस्तेमाल करने के लिए, AR ज़रूरी है ऐप्लिकेशन का इस्तेमाल करने के लिए, ARCore की सुविधा वाला डिवाइस होना ज़रूरी है. इस डिवाइस पर Google Play Services for AR इंस्टॉल हो.

  • Google Play Store, AR ज़रूरी ऐप्लिकेशन को सिर्फ़ ARCore की सुविधा वाले डिवाइसों पर उपलब्ध कराता है.

  • जब उपयोगकर्ता AR की ज़रूरत वाला ऐप्लिकेशन इंस्टॉल करते हैं, तो Google Play स्टोर AR के लिए Google Play सेवाएं अपने-आप इंस्टॉल कर देता है. हालांकि, अगर आपके ऐप्लिकेशन को मैन्युअल तौर पर अनइंस्टॉल किया गया है या उसे मैन्युअल तौर पर अनइंस्टॉल किया गया है, तो ऐसी स्थिति में आपके ऐप्लिकेशन को रनटाइम की जांच करने की ज़रूरत पड़ सकती है.

ज़्यादा जानकारी के लिए, Google Play Store में AR ऐप्लिकेशन प्रकाशित करना देखें.

अपने ऐप्लिकेशन को AR ज़रूरी है के तौर पर एलान करने के लिए, अपने AndroidManifest.xml में बदलाव करें और नीचे दी गई एंट्री शामिल करें:

<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" android:required="true"/>

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

इसके बाद, कम से कम 24 का minSdkVersion बताने के लिए अपने ऐप्लिकेशन के build.gradle में बदलाव करें:

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

एआर (ऑगमेंटेड रिएलिटी) ज़रूरी नहीं है

एआर (ऑगमेंटेड रिएलिटी) ऐप्लिकेशन में वैकल्पिक एआर (ऑगमेंटेड रिएलिटी) की सुविधाएं हैं, जो सिर्फ़ उन ARCore की सुविधा वाले डिवाइसों पर चालू हैं जिन पर एआर (ऑगमेंटेड रिएलिटी) के लिए Google Play सेवाएं इंस्टॉल की गई हैं.

  • AR वैकल्पिक ऐप्लिकेशन इंस्टॉल किए जा सकते हैं और ऐसे डिवाइस पर चलाए जा सकते हैं जिन पर ARCore काम नहीं करता.

  • जब उपयोगकर्ता किसी एआर (ऑगमेंटेड रिएलिटी) ऐप्लिकेशन को इंस्टॉल करते हैं, तो Google Play स्टोर, उस ऐप्लिकेशन से Google Play Services for AR को अपने-आप इंस्टॉल नहीं करता.

अपने ऐप्लिकेशन को AR वैकल्पिक बताने के लिए, अपने AndroidManifest.xml में बदलाव करें और नीचे दी गई एंट्री शामिल करें:

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

इसके बाद, कम से कम 14 का minSdkVersion बताने के लिए अपने ऐप्लिकेशन के build.gradle में बदलाव करें:

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

बिल्ड डिपेंडेंसी जोड़ना

अपने Android Studio प्रोजेक्ट में ARCore लाइब्रेरी जोड़ने के लिए, यह तरीका अपनाएं:

  1. पक्का करें कि आपके Project's build.gradle फ़ाइल में Google's Maven डेटा संग्रह स्थान शामिल है.

    allprojects {
    repositories {
        google()
            ...
    
  2. ARCore Aar से नेटिव लाइब्रेरी निकालें.

    ARCore को AAR फ़ाइल में शामिल किया गया है. किसी C/C++ प्रोजेक्ट के हिस्से के रूप में उन्हें इस्तेमाल करने के लिए, उन्हें संग्रह से निकाला जाना चाहिए, ताकि उनकी जानकारी सीधे दी जा सके. ऐसा करने के लिए, अपने मॉड्यूल कीbuild.gradle कस्टम फ़ाइल में कस्टम टास्क जोड़ें. उदाहरण के लिए, app/build.gradle.

    ARCore की हेडर फ़ाइल, arcore_c_api.h GitHub SDK प्रोजेक्ट में शामिल है:

    app/build डायरेक्ट्री में किसी डायरेक्ट्री के लिए वैरिएबल तय करें. नेटिव लाइब्रेरी इस डायरेक्ट्री में निकाली जाएंगी. साथ ही, एक्सट्रैक्शन के काम और डेटा को बनाए रखने के लिए ग्रेडल कॉन्फ़िगरेशन बनाएं.

    /*
    The ARCore aar library contains the native shared libraries. These 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 }
    
    

    एआर फ़ाइल से नेटिव लाइब्रेरी को कॉपी करने के लिए कोई टास्क बनाएं और उसे बिल्ड डिपेंडेंसी में जोड़ें

      // Extracts the shared libraries from aars in the natives configuration.
      // This is done 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)
          }
      }
    
  3. जगहों को बाहरी बिल्ड टूल में पास करने के लिए, नेटिव बिल्ड फ़्लैग को कॉन्फ़िगर करें.

    यह उदाहरण, GitHub प्रोजेक्ट के सैंपल से है.

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

  4. Java और नेटिव लाइब्रेरी, दोनों के लिए डिपेंडेंसी जोड़ें.

     dependencies {
          ...
          // Add java and native dependencies on the ARCore library
          implementation 'com.google.ar:core:1.32.0'
          natives 'com.google.ar:core:1.32.0'
          ...
     }
    
  5. 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}
    )
    

रनटाइम के दौरान जांच करें

देखें कि ARCore इंस्टॉल है या नहीं

सभी AR ऐप्लिकेशन को ARCore सेशन बनाने से पहले ArCoreApk_requestInstall() को कॉल करना होगा. ArCoreApk_requestInstall() जांच करता है कि 'Google Play सेवाएं' का एआर (ऑगमेंटेड रिएलिटी) वर्शन काम करता है या नहीं. साथ ही, हो सकता है कि यह ऐप्लिकेशन का पुराना वर्शन हो या उपयोगकर्ता ने इसे मैन्युअल तरीके से हटा दिया हो.

// Tracks if we have already triggered an installation request.
bool install_requested_;

void nativeOnCreate() {
  // other setup

  install_requested_ = false;
}

void nativeOnResume(JNIEnv env, jobject activity) {
  if (ar_session_ == null) {
    bool user_requested_install = !install_requested_;

    ArInstallStatus install_status;
    // Ensure 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 session
  }

  // Normal onResume behavior
}

अगर ArCoreApk_requestInstall() AR_INSTALL_STATUS_INSTALL_REQUESTED लौटाता है, तो मौजूदा गतिविधि रुक जाती है और उपयोगकर्ता को सेवा इंस्टॉल करने या अपडेट करने के लिए कहा जाता है जब उपयोगकर्ता गतिविधि पर वापस आता है, तो onResume() की गतिविधि फिर से शुरू हो जाती है.

देखें कि ARCore काम करता है या नहीं (सिर्फ़ एआर वैकल्पिक)

एआर (ऑगमेंटेड रिएलिटी) ऐप्लिकेशन ArCoreApk_checkAvailability() का इस्तेमाल करके यह पता लगा सकता है कि मौजूदा डिवाइस, ARCore पर काम करता है या नहीं. ऐसे डिवाइस पर जो ARCore की सुविधा नहीं देता, ऐप्लिकेशन को एआर (ऑगमेंटेड रिएलिटी) से जुड़ी सुविधा को बंद करना चाहिए और यूआई से जुड़े एलिमेंट को छिपाना चाहिए.

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/enable AR button.
  } else {
    // Hide/disable AR button.
  }
}

इसके बाद, जब उपयोगकर्ता किसी एआर (ऑगमेंटेड रिएलिटी) सुविधा का इस्तेमाल करना चाहता है, तो आपके ऐप्लिकेशन को पक्का करना चाहिए कि एआर (ऑगमेंटेड रिएलिटी) के लिए Google Play सेवाएं इंस्टॉल की गई है. ऐसा करने का एक आसान तरीका यह है कि ऊपर बताई गई, एआर (ऑगमेंटेड रिएलिटी) की ज़रूरी शर्त के मुताबिक गतिविधि शुरू करें.

उपयोगकर्ता की निजता से जुड़ी ज़रूरी शर्तों का पालन करना

पक्का करें कि आपका ऐप्लिकेशन ARCore' उपयोगकर्ता की निजता से जुड़ी ज़रूरी शर्तों का पालन करता हो.

अगले चरण

सैंपल ऐप्लिकेशन में कोड और टिप्पणियों के साथ-साथ C API रेफ़रंस भी पढ़ें.