הפעלת ARCore

הדף הזה מתאר כיצד להפעיל פונקציונליות ARCore בפרויקטים של Android NDK. לשם כך:

  1. הוספת AR נדרש או AR אופציונלי למניפסט
  2. מוסיפים יחסי תלות של ה-build בפרויקט
  3. ביצוע בדיקות בזמן ריצה כדי לוודא שהמכשיר נתמך על ידי ARCore וששירותי Google Play ל-AR מותקנים בו.
  4. יש לוודא שהאפליקציה תואמת ל-ARCore's דרישות הפרטיות של המשתמשים

שירותי Google Play ל-AR

ערכות ARCore SDK מאפשרות גישה לתכונות ה-AR הזמינות במכשירים הנתמכים ב-ARCore שמותקנות Google Play Services ל-AR (ARCore) מותקנות.

Google Play Services למציאות רבודה מותקנים באופן אוטומטי ומתעדכנים ברוב המכשירים הנתמכים.

לפני התחלת סשן AR, האפליקציות חייבות:

  1. מוודאים ש-ARCore נתמך. לשם כך, מתקשרים ArCoreApk_checkAvailability.
  2. מוודאים שאפליקציית Google Play Services למציאות רבודה מותקנת ומעודכנת, וש הורדת נתוני פרופיל המכשיר של ARCore באמצעות שיחה ArCoreApk_requestInstall.

יש להוסיף AR נדרש או AR אופציונלי למניפסט

יש שתי דרכים להגדיר אפליקציה שתומכת בתכונות AR : AR נדרש ואופציונלי ב-AR.

נדרש AR

כדי להשתמש בהם, לאפליקציה AR הנדרשת נדרש מכשיר הנתמך על ידי ARCore שבו מותקנת שירותי Google Play ל-AR.

  • בחנות Google Play, אפליקציות שצריכות AR זמינות רק במכשירים שתומכים ב-ARCore.

  • כשמשתמשים מתקינים אפליקציית AR נדרשת, חנות Google Play מתקין באופן אוטומטי את שירותי Google Play ל-AR. עם זאת, האפליקציה שלך עדיין תצטרך לבצע בדיקות זמן ריצה נוספות אם צריך לעדכן את שירותי Google Play ל-AR או להסיר את ההתקנה שלו באופן ידני.

למידע נוסף, כדאי לעיין בפרסום של אפליקציות AR בחנות Google Play.

כדי להצהיר על כך שהאפליקציה נדרשת 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>

לאחר מכן, משנים את ה-build.gradle של האפליקציה כך שיכלול minSdkVersion של 24 לפחות:

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR אופציונלי

לאפליקציה אופציונלית של AR יש תכונות אופציונליות של AR, המופעלות רק במכשירים עם תמיכה ב-ARCore שהותקנו בהם Google Play Services למציאות רבודה.

  • ניתן להתקין אפליקציות AR אופציונליות ולהפעיל אותן במכשירים שלא תומכים ב-ARCore.

  • כשמשתמשים מתקינים אפליקציה אופציונלית ב-AR, חנות Google Play לא תתקין אוטומטית את שירותי Google Play ל-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>

אחרי שמשנים את ה-build.gradle של האפליקציה, צריך לציין minSdkVersion של לפחות 14:

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

הוספת תלויות build

כדי להוסיף את ספריית ARCore לפרויקט Android Studio, מבצעים את השלבים הבאים:

  1. חשוב לוודא שקובץ ה-Project's של build.gradle כולל את מאגר הידע של Google 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 }
    
    

    יוצרים משימה כדי להעתיק את הספריות המקוריות מקובץ ה-Aar, ומוסיפים אותה לתלות ב-build

      // 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. צריך להגדיר את התראות ה-build המקוריות כדי להעביר את המיקומים לכלים החיצוניים של ה-build.

    הדוגמה הזו מבוססת על דגימות הפרויקט ב-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.31.0'
          natives 'com.google.ar:core:1.31.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 חייבות להתקשר אל ArCoreApk_requestInstall() לפני יצירת סשן של ARCore. ArCoreApk_requestInstall() בודק אם מותקנת גרסה תואמת של שירותי Google Play ל-AR (יכול להיות שהיא לא עדכנית או שהיא הוסרה באופן ידני על ידי המשתמש). אם היא לא קיימת, היא תציג למשתמש בקשה להתקין את השירות.

// 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 נתמכת (AR אופציונלי בלבד)

אפליקציות אופציונליות ל-AR יכולות להשתמש ב-ArCoreApk_checkAvailability() כדי לקבוע אם המכשיר הנוכחי תומך ב-ARCore. במכשיר שלא תומך ב-ARCore, אפליקציות צריך להשבית את הפונקציונליות הקשורה ל-AR ולהסתיר את רכיבי ממשק המשתמש המשויכים.

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

לאחר מכן, כשהמשתמש רוצה להשתמש בתכונת AR, האפליקציה שלך צריכה לוודא ששירותי Google Play ל-AR מותקנים. דרך קלה לעשות זאת היא להפעיל פעילות שתואמת לדפוס החובה AR שמתואר למעלה.

ציות לדרישות הפרטיות של משתמשים

מוודאים שהאפליקציה עומדת בדרישות של ARCore&#39.לדרישות הפרטיות.

השלבים הבאים

קראו את הקוד והתגובות באפליקציה לדוגמה, וכן את ההפניה ל-C API.