דף זה תורגם על ידי Cloud Translation API.

הפעלת AR באפליקציית NDK של Android

יש להפעיל AR כדי להשתמש בתכונות של מציאות רבודה באפליקציה החדשה או הקיימת.

הגדרת האפליקציה כחובה ב-AR או כ-AR אופציונלי

כדי לחסוך במקום במכשירים מסוימים, כל תכונות ה-AR מאוחסנות באפליקציה שנקראת Google Play Services ל-AR. היא מתעדכנת בנפרד בחנות Play. אפליקציות ל-Android שמשתמשות בתכונות AR מתקשרות עם שירותי Google Play למציאות רבודה באמצעות ה-ARCore SDK. אפשר להגדיר אפליקציה שתומכת בתכונות AR בשתי דרכים: חובה ב-AR ואופציונלי ב-AR. הסיווג הזה קובע את האינטראקציה של האפליקציה עם שירותי Google Play לאפליקציית AR.

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

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

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

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

	נדרש AR	אופציונלי ב-AR
שימוש בתכונות ב-AR	האפליקציה שלך זקוקה ל-ARCore כדי ליהנות מפונקציונליות בסיסית.	ARCore מרחיבה את הפונקציונליות של האפליקציה. האפליקציה יכולה לפעול בלי תמיכה ב-ARCore.
גלוי בחנות Play	האפליקציה שלך רשומה רק בחנות Play במכשירים שתומכים ב-ARCore.	האפליקציה פועלת לפי נוהלי רישום רגילים.
שיטת ההתקנה של Google Play Services למציאות רבודה	בחנות Play מותקנים שירותי Google Play למציאות רבודה לצד האפליקציה.	האפליקציה שלך משתמשת ב-`ArCoreApk_requestInstall()` כדי להוריד ולהתקין את ARCore.
דרישות לגבי `minSdkVersion` של Android	Android 7.0 (רמת API 24)	Android 7.0 (רמת API 24)
יש להשתמש ב-`ArCoreApk_checkAvailability()` או ב-`ArCoreApk_checkAvailabilityAsync()` כדי לבדוק את התמיכה ב-ARCore ואת סטטוס ההתקנה
יש להשתמש ב-`ArCoreApk_requestInstall()` כדי להתקין את Google Play Services למציאות רבודה

כדי שהאפליקציה תהיה נדרשת לשימוש ב-AR או שהיא אופציונלית, יש לעדכן את AndroidManifest.xml כך שיכלול את הרשומות הבאות:

נדרש AR

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

אופציונלי ב-AR

<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 של 24 לפחות:

 android {
     defaultConfig {
         …
         minSdkVersion 24
     }
 }

הוספת יחסי תלות של גרסאות build

יש לוודא שקובץ ה-build.gradle של הפרויקט כולל את מאגר Maven ב-Google.
```
allprojects {
    repositories {
        google()
        …
    }
}
```
אפשר להוסיף משימה מותאמת אישית לקובץ build.gradle של המודול כדי לחלץ ספריות מקוריות כלולות מקובץ AAR של ARCore. באופן כזה ניתן להפנות אליהם ישירות בפרויקט C או C++.
בספרייה app/build, מגדירים משתנה לספרייה שאליה יועברו הספריות המקוריות.

יצירה של הגדרת Gradle להחזקת נתונים ומשימות חילוץ.

/*
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 }

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

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

צריך להגדיר את הדגלים של גרסת ה-build המקורית כדי להעביר את המיקומים לכלי ה-build החיצוניים.

// 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"
    }
}

מוסיפים את יחסי התלות בין ה-Java והספריות המקוריות.

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

אפשר להפנות לספריות המקוריות ב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}
)

ביצוע בדיקות בזמן ריצה

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

בדיקה אם אפליקציית ARCore נתמכת

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

אפליקציות ל-Android NDK עשויות להשתמש בסיווג Java ArCoreApk כדי לבדוק את התאימות ולנהל את ההתקנה ב-CARC ARCore Session API המקורי. בהתאם למבנה של האפליקציה, יכול להיות שיהיה לך קל יותר להשתמש בפונקציות ArCoreApk_ עקב הכמות הגדולה של טיפול בשגיאות והאינטראקציה של ממשק המשתמש.

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

למרות ששירותי Google Play למציאות רבודה מותקנים לצד האפליקציה הנדרשת ל-AR, משתמשים עם מכשירים שאינם נתמכים יכולים להתקין אותה ממקור חיצוני. שימוש ב-ArCoreApk_checkAvailability() או ב-ArCoreApk_checkAvailabilityAsync() לבדיקת התמיכה ב-ARCore מבטיח חוויה עקבית.

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

בדיקה אם Google Play Services למציאות רבודה מותקן

גם אפליקציות נדרשות ב-AR וגם אפליקציות אופציונליות ב-AR חייבות לקרוא ArCoreApk_requestInstall() לפני יצירת סשן של ARCore כדי לבדוק אם מותקנת גרסה תואמת של Google Play Services ל-AR (ועדיין) ולוודא שכל נתוני הפרופיל הנדרשים של מכשיר ARCore הורדו.

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

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

כדי לפרסם את האפליקציה בחנות Play, צריך לוודא שהיא עומדת בדרישות של ARCore בנושא פרטיות המשתמשים.

מה השלב הבא?

איך מגדירים סשן של ARCore