הפעלת ARCore

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

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

בחירה בין הרשאת חובה ל-AR או ל-AR אופציונלי

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

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

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

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

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

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

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

נדרש ARAR אופציונלי
שימוש בתכונות AR האפליקציה שלך צריכה את ARCore לפונקציונליות בסיסית. ARCore מרחיבה את הפונקציונליות של האפליקציה. האפליקציה יכולה לפעול ללא תמיכה ב-ARCore.
הרשאות גישה לחנות Play האפליקציה רשומה רק בחנות Play במכשירים עם תמיכה ב-ARCore. האפליקציה פועלת בהתאם להליכי רישום רגילים.
שיטת ההתקנה של Google Play Services ל-AR בחנות Play מותקנים שירותי Google Play ל-AR לצד האפליקציה. האפליקציה שלך משתמשת ב-ArCoreApk.requestInstall() כדי להוריד ולהתקין את ARCore.
דרישות השימוש ב-Android עבור minSdkVersion Android 7.0 (API ברמה 24) Android 4.0 (API ברמה 14)
יש להשתמש ב-ArCoreApk.checkAvailability() כדי לבדוק את תמיכת ARCore וסטטוס ההתקנה
יש להשתמש ב-ArCoreApk.requestInstall() כדי להתקין את שירותי Google Play ל-AR

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

הוספת ערכים למניפסט של האפליקציה שלך

יש לשנות את 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>

לאחר מכן, צריך לוודא שהאפליקציה כוללת לפחות את המאפיין minSdkVersion באפליקציה's build.gradle:

נדרש AR

android {
    defaultConfig {
        …
        minSdkVersion 24
    }
}

AR אופציונלי

android {
    defaultConfig {
        …
        minSdkVersion 14
    }
}

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

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

  • יש לוודא שקובץ ה-Project's של build.gradle כולל את מאגר ה-Maven של Google

    allprojects {
        repositories {
            google()
            …
        }
    }
    
  • מוסיפים את ספריית ARCore העדכנית ביותר בהתאם לקובץ app's build.gradle:

    dependencies {
        …
        implementation 'com.google.ar:core:1.32.0'
    }
    

בדיקות ריצה

איך בודקים אם מערכת ARCore נתמכת?

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

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  // Enable AR-related functionality on ARCore supported devices only.
  maybeEnableArButton();
  …
}

void maybeEnableArButton() {
  ArCoreApk.Availability availability = ArCoreApk.getInstance().checkAvailability(this);
  if (availability.isTransient()) {
    // Continue to query availability at 5Hz while compatibility is checked in the background.
    new Handler().postDelayed(new Runnable() {
      @Override
      public void run() {
        maybeEnableArButton();
      }
    }, 200);
  }
  if (availability.isSupported()) {
    mArButton.setVisibility(View.VISIBLE);
    mArButton.setEnabled(true);
  } else { // The device is unsupported or unknown.
    mArButton.setVisibility(View.INVISIBLE);
    mArButton.setEnabled(false);
  }
}

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  // Enable AR-related functionality on ARCore supported devices only.
  maybeEnableArButton()
  …
}

fun maybeEnableArButton() {
  val availability = ArCoreApk.getInstance().checkAvailability(this)
  if (availability.isTransient) {
    // Continue to query availability at 5Hz while compatibility is checked in the background.
    Handler().postDelayed({
      maybeEnableArButton()
    }, 200)
  }
  if (availability.isSupported) {
    mArButton.visibility = View.VISIBLE
    mArButton.isEnabled = true
  } else { // The device is unsupported or unknown.
    mArButton.visibility = View.INVISIBLE
    mArButton.isEnabled = false
  }
}

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

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

צריך לבקש גישה למצלמה

אפליקציות אופציונליות של AR וגם אפליקציות AR נדרשות כדי לוודא שהרשאת המצלמה הוענקה לפני יצירת סשן AR. הדוגמה hello_ar_JavaScript כוללת כיתה CameraPermissionHelper שניתן להעתיק לפרויקט שלך ולקרוא אליה משיטת onResume() ב-AR.

Java

@Override
protected void onResume() {
  super.onResume();

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this);
    return;
  }

  …
}

Kotlin

override fun onResume() {
  super.onResume()

  // ARCore requires camera permission to operate.
  if (!CameraPermissionHelper.hasCameraPermission(this)) {
    CameraPermissionHelper.requestCameraPermission(this)
    return
  }

  …
}

כמו כן, הפעילות ב-AR חייבת להתבצע ב-onRequestPermissionsResult(), כפי שמוצג ב-HelloArActivity:

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();
  }
}

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

בדיקה אם שירותי Google Play ל-AR מותקנים

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

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

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

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

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

השלבים הבאים