Table of Contents

Come utilizzare le funzionalità EasyAR su Apple Vision Pro

Questa guida ti accompagna nella configurazione del progetto Unity e Xcode per sbloccare tutte le funzionalità core di EasyAR, inclusa la localizzazione cloud Mega, per le applicazioni Apple Vision Pro.

Prima di iniziare

  • Impara come utilizzare gli esempi per headset
  • Assicurati che l'ambiente di sviluppo soddisfi i seguenti requisiti:
    • visionOS 2.0 o superiore
    • Xcode 16.0 o superiore corrispondente alla versione di visionOS, con visionOS simulator installato
    • Versione consigliata di Unity: LTS 6000.0.23 o superiore

Richiedere una licenza API enterprise a Apple Inc.

Poiché l'acquisizione del flusso fotocamera e dei parametri su Apple Vision Pro richiede un entitlement tramite API enterprise, è necessario richiedere a Apple Inc. un file license contenente tale entitlement. Per la richiesta e l'utilizzo di questa licenza, consultare Building spatial experiences for business apps with enterprise APIs for visionOS.

Importante

Il Bundle ID specificato nell'entitlement ottenuto da Apple deve corrispondere esattamente a quello inserito durante la creazione della EasyAR Sense License Key.

Come scegliere la modalità App visionOS

Le App in esecuzione su visionOS possono accedere ai dati ARKit solo in Immersive Space. L'app generata dall'editor Unity in Immersive Space, in base al flusso di rendering e alle API, richiede la scelta tra la modalità RealityKit with PolySpatial o Metal Rendering with Compositor Services.

Per la definizione di Immersive Space, consultare la documentazione ufficiale Apple.

Per una panoramica dettagliata delle modalità App di Unity, fare riferimento a visionOS Platform Overview nella documentazione PolySpatial di Unity.

Consiglio

Suggerimenti per la scelta della modalità App

  • Scelta consigliata: RealityKit with PolySpatial

    Se è il tuo primo approccio a visionOS, si consiglia di scegliere prioritariamente questa modalità. Offre un'integrazione profonda con le funzionalità di rendering di sistema di visionOS, garantendo elevata stabilità e qualità del rendering. Questa modalità non supporta shader di codice personalizzati (HLSL/ShaderLab); è obbligatorio utilizzare Shader Graph e sono supportate solo le funzionalità verificate per la compatibilità PolySpatial (convertite in MaterialX).

    Gli shader integrati di Unity Standard (Built-in) e Lit (URP) sono pre-adattati ufficialmente e possono essere utilizzati direttamente.

  • Avanzata/necessità specifiche: Metal Rendering with Compositor Services

    Adatta per progetti complessi con esigenze di migrazione massiva di asset 3D esistenti o che richiedono shader personalizzati. In questa modalità, Unity gestisce completamente la logica di rendering, bypassando la pipeline RealityKit del sistema. Ciò può comportare una qualità di rendering generalmente inferiore rispetto a RealityKit e potenziali problemi imprevisti.

Suggerimenti per l'integrazione EasyAR:

Durante l'integrazione di EasyAR, inizia sempre utilizzando la modalità RealityKit with PolySpatial per stabilire un flusso di base. Questo approccio aiuta a isolare le variabili, evitando che problemi di basso livello legati a Metal si intreccino con questioni AR, complicando l'individuazione delle cause dei malfunzionamenti.

Configurazione nel progetto Unity

Nel progetto Unity è necessario effettuare le seguenti configurazioni:

Importare i Package necessari nel progetto Unity

Unity 6 (consigliato):

  • com.unity.xr.visionos (2.0.4+)
  • com.unity.polyspatial (2.0.4+)
  • com.unity.polyspatial.visionos (2.0.4+)
Importante

Tutti i numeri di versione dei Package devono corrispondere esattamente.

Si consiglia di utilizzare prioritariamente Unity 6, poiché alcune versioni precedenti di Unity 2023.x non supportano ancora visionOS.

Unity 2022.3:

  • com.unity.xr.visionos (1.2.3)
  • com.unity.polyspatial (1.2.3)
  • com.unity.polyspatial.visionos (1.2.3)
Importante

Tutti i numeri di versione dei Package devono corrispondere esattamente.

Le versioni 1.3.x non sono supportate; assicurati di utilizzare 1.2.3.

Selezionare la piattaforma di build

Clicca su File > Build Profiles nella barra dei menu e imposta Platform su visionOS.

Cambiare piattaforma di build

Configurare il sistema di input

Assicurati di utilizzare la nuova versione di Input System Package:

Clicca su Edit > Project Settings > Player, e imposta Active Input Handling su Input System Package(New).

Unity potrebbe richiedere il riavvio del progetto; clicca Apply per rendere effettive le modifiche.

Modifica sistema di input applicata

Configurare XR Plug-in Management

Clicca su Edit > Project Settings > XR Plug-in Management, nella scheda visionOS sotto Plug-in Providers seleziona Apple visionOS.

Selezionare il plugin visionOS

Configurare il plugin Apple visionOS

Clicca su Edit > Project Settings > XR Plug-in Management > Apple visionOS.

In base alla descrizione precedente seleziona la modalità App Mode appropriata.

Selezionare la modalità App

Nota

La modalità Windowed, poiché non è eseguita in Immersive Space, non può utilizzare le funzionalità AR.

La modalità Hybrid richiede il passaggio manuale tra le modalità Metal e RealityKit. Essendo complessa, non è consigliata; consulta la documentazione ufficiale Unity.

Nella stessa pagina, effettua le seguenti modifiche:

  • In World Sensing Usage Description aggiungi una descrizione.
  • Imposta Metal Immersion Style su Mixed.
  • Imposta Reality Kit Immersion Style su Mixed.
  • Seleziona IL2CPP Large Exe Workaround.

Modificare la configurazione del plugin visionOS

[Solo modalità RealityKit] Importare TextMesh Pro Essentials

Clicca su Edit > Project Settings > TextMesh Pro > clicca su Import TMP Essentials

Importare TMP Essentials

Nota

Attualmente la modalità RealityKit with PolySpatial supporta solo testo TextMesh Pro. Senza l'importazione, il testo non verrà renderizzato.

[Solo modalità RealityKit] Impostazioni PolySpatial

Clicca su Edit > Project Settings > PolySpatial, e modifica quanto segue:

  • Imposta Default Volume Camera Window Config su Default Unbounded Configuration.
  • Seleziona Auto-Create Volume Camera

Configurare PolySpatial

Se è necessario specificare un Default Volume Camera Window Config diverso, assicurati che il suo Mode sia Unbounded.

Confermare che Mode è Unbounded

Elimina eventuali Volume Camera presenti nella scena.

Eliminare Volume Camera dalla scena

Avvertenza
  • Non è supportato un Volume Camera con World Transform diverso da identity.
  • Se per motivi specifici è necessario aggiungere un Volume Camera personalizzato unico nella scena, assicurati di:
    • Impostare il suo World Transform su identity.
    • Verificare che il Volume Camera Window Configuration abbia Mode impostato su Unbounded.
    • Utilizzarlo solo dopo aver compreso appieno il significato e l'utilizzo come descritto nella documentazione ufficiale Unity.

[Quando si utilizza Mega] Aggiungere Location Usage Description

Attenzione

Se in EasyAR è abilitata l'autorizzazione Location (necessaria per Mega), è obbligatorio aggiungere una descrizione dell'utilizzo, altrimenti la build fallirà.

Poiché attualmente in Project Settings > Player > visionOS non è presente il campo Location Usage Description, configurare come segue:

  1. Cambiare scheda piattaforma: Passare temporaneamente alla scheda iOS.
  2. Inserire descrizione: In Location Usage Description inserisci la descrizione necessaria.
  3. Ritornare a visionOS: Torna alla scheda visionOS; la configurazione inserita verrà mantenuta e applicata automaticamente.

Descrizione Location

Configurazione nel progetto Xcode

Nel progetto Xcode generato da Unity, effettuare le seguenti configurazioni:

Configurare l'entitlement per i dati fotocamera

  • Copia il file Enterprise.license ottenuto nella cartella del progetto Xcode.

    Copiare nella cartella del progetto Xcode

  • Trascina Enterprise.license dalla cartella del progetto Xcode nel progetto Xcode.

    Spostare nel progetto Xcode

Modificare info.plist per abilitare il salvataggio e l'invio di file

Se l'applicazione deve registrare EIF e inviarli tramite l'app File di visionOS a computer o altri dispositivi, aggiungi i seguenti campi a Info.plist:

  • Aggiungi LSSupportsOpeningDocumentsInPlace e impostalo su true.
  • Aggiungi UIFileSharingEnabled e impostalo su true.

Modificare Info.plist

Consiglio

Dopo l'aggiunta, la chiave visualizzata in Xcode potrebbe differire dalla stringa inserita manualmente (es. inserendo LSSupportsOpeningDocumentsInPlace ma visualizzando Supports opening documents in place). Questo comportamento è normale.