Configurer EasyAR sur Apple Vision Pro

Ce guide vous conduit à travers la configuration des projets Unity et Xcode afin de débloquer toutes les capacités principales d’EasyAR, y compris la localisation cloud Mega, pour une application Apple Vision Pro.

Avant de commencer

• Apprendre à utiliser les exemples de casque
• S’assurer que l’environnement de développement satisfait aux exigences suivantes :
  • visionOS 2.0 ou supérieur
  • Xcode 16.0 ou supérieur correspondant à la version visionOS, avec le simulator visionOS installé
  • Version Unity LTS recommandée : 6000.0.23 ou plus récente

Demander à Apple Inc. une licence d’API d’entreprise

Comme l’accès à l’image de la caméra et à ses paramètres sur Apple Vision Pro nécessite une entitlement en tant qu’API d’entreprise, vous devez demander à Apple Inc. un fichier license incluant cette entitlement. Pour la demande et l’usage de cette licence, consultez Building spatial experiences for business apps with enterprise APIs for visionOS.

Important

Le Bundle ID contenu dans l’entitlement fourni par Apple doit correspondre exactement à celui saisi lors de la création de la EasyAR Sense License Key.

Choisir le mode d’application visionOS

Une application exécutée sur visionOS ne peut obtenir les données ARKit que dans Immersive Space. Pour une application compilée depuis Unity Editor, dans Immersive Space, il faut choisir entre RealityKit with PolySpatial et Metal Rendering with Compositor Services selon le pipeline de rendu et l’API utilisés.

Pour la définition de Immersive Space, consultez la documentation officielle d’Apple.

Pour une présentation détaillée des modes d’application Unity, consultez la vue d’ensemble visionOS dans la documentation PolySpatial de Unity : visionOS Platform Overview.

Astuce

Conseils de choix du mode d’application

• Choix prioritaire : RealityKit with PolySpatial

  Si vous découvrez visionOS pour la première fois, il est recommandé de choisir ce mode en priorité. Son avantage est une intégration profonde avec le rendu système de visionOS, avec une bonne stabilité et un bon rendu. Ce mode ne prend pas en charge les shaders personnalisés (HLSL/ShaderLab) ; il faut utiliser Shader Graph, et seules les fonctionnalités ayant passé la vérification de compatibilité PolySpatial sont prises en charge (elles sont converties en MaterialX).

  Les shaders Unity intégrés Standard (Built-in) et Lit (URP) ont déjà été adaptés officiellement et peuvent être utilisés directement.

• Avancé / besoins spécifiques : Metal Rendering with Compositor Services

  Convient aux projets complexes ayant beaucoup d’actifs 3D existants à migrer ou nécessitant obligatoirement des shaders personnalisés. Dans ce mode, Unity gère toute la logique de rendu et contourne le pipeline RealityKit du système ; le rendu est en général moins bon qu’avec RealityKit et peut présenter des problèmes de rendu imprévus.

Conseil d’intégration EasyAR :

Lors de la première intégration d’EasyAR, veillez à faire passer d’abord le flux de base avec le mode RealityKit with PolySpatial. Cela permet d’isoler efficacement les variables et d’éviter que les problèmes d’adaptation Metal bas niveau et les problèmes liés à l’AR s’emmêlent, ce qui rendrait le diagnostic beaucoup plus difficile.

Configuration dans le projet Unity

Le projet Unity doit être configuré comme suit :

Importer les paquets nécessaires dans le projet Unity

Unity 6 (recommandé) :

• RealityKit/Hybrid
• Metal

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

Important

Les numéros de version de tous les packages doivent être strictement identiques.

Il est recommandé d’utiliser Unity 6 en priorité ; certaines versions anciennes de Unity 2023.x ne prennent pas encore en charge visionOS.

Unity 2022.3 :

• RealityKit/Hybrid
• Metal

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

Important

Les versions de tous les packages doivent être strictement identiques.

Les versions 1.3.x ne sont pas prises en charge ; veillez à rester en 1.2.3.

Choisir la plateforme de build

Cliquez dans la barre de menus sur File > Build Profiles pour basculer la plateforme sur visionOS.

Configurer le système d’entrée

Assurez-vous d’utiliser la nouvelle version du Input System Package :

Cliquez dans la barre de menus sur Edit > Project Settings > Player, puis définissez Active Input Handling sur Input System Package(New).

Unity peut alors vous demander de redémarrer le projet ; cliquez sur Apply pour appliquer les changements.

Configurer XR Plug-in Management

Cliquez dans la barre de menus sur Edit > Project Settings > XR Plug-in Management, puis dans l’onglet visionOS cochez Apple visionOS dans Plug-in Providers.

Configurer le plug-in Apple visionOS

Cliquez dans la barre de menus sur Edit > Project Settings > XR Plug-in Management > Apple visionOS.

Choisissez le App Mode approprié selon la section précédente.

Note

Le mode Windowed n’étant pas exécuté dans Immersive Space, il ne peut pas utiliser les capacités AR.

Le mode Hybrid suppose que le développeur passe manuellement entre les modes Metal et RealityKit. Comme son utilisation est assez complexe, il n’est pas recommandé. Consultez la documentation officielle Unity sur ce mode pour plus de détails.

Effectuez ensuite les modifications suivantes sur la même page :

• Ajouter une description dans le champ World Sensing Usage Description.

• Définir Metal Immersion Style sur Mixed.

• Définir Reality Kit Immersion Style sur Mixed.

• Cocher IL2CPP Large Exe Workaround.

[RealityKit uniquement] Importer TextMesh Pro Essentials

Cliquez dans la barre de menus sur Edit > Project Settings > TextMesh Pro > Import TMP Essentials.

Note

À l’heure actuelle, le mode RealityKit with PolySpatial ne prend en charge que le texte TextMesh Pro. Sans cet import, le texte ne pourra pas être rendu.

[RealityKit uniquement] Réglages liés à PolySpatial

Cliquez dans la barre de menus sur Edit > Project Settings > PolySpatial, puis effectuez les modifications suivantes sur cette page :

• Définir Default Volume Camera Window Config sur Default Unbounded Configuration.

• Cocher Auto-Create Volume Camera

Si vous devez spécifier autrement Default Volume Camera Window Config, assurez-vous que son Mode est Unbounded.

Si une Volume Camera existe dans la scène, supprimez-la.

Avertissement

• Les Volume Camera dont la valeur de World Transform n’est pas identity ne sont pas prises en charge.
• Si, pour des raisons particulières, vous devez ajouter une unique Volume Camera personnalisée dans la scène, assurez-vous impérativement :
  • de définir son World Transform sur identity.
  • de définir le Mode de sa Volume Camera Window Configuration sur Unbounded.
  • de l’utiliser en ayant bien compris sa signification et son usage dans la documentation officielle Unity.

[Lors de l’utilisation de Mega] Ajouter Location Usage Description

Attention

Si l’autorisation Location est activée dans la configuration EasyAR (lors de l’utilisation de Mega), vous devez ajouter la description de l’autorisation, sinon le build échouera.

Comme le champ Location Usage Description n’apparaît pas actuellement dans l’onglet Project Settings > Player > visionOS de Unity, configurez-le comme suit :

1. Basculer l’onglet de plateforme : passez temporairement à l’onglet iOS.
2. Saisir la description : renseignez le texte d’usage de l’autorisation dans Location Usage Description.
3. Revenir à visionOS : revenez à l’onglet visionOS ; la configuration saisie est conservée et prend effet automatiquement.

Configuration dans le projet Xcode

Le projet Xcode généré par Unity doit être configuré comme suit :

Configurer l’entitlement des données caméra

• Copiez le fichier Enterprise.license obtenu dans le dossier du projet Xcode.

  

• Faites glisser Enterprise.license du dossier du projet Xcode vers le projet Xcode.

  

Modifier info.plist pour permettre à l’application de sauvegarder et de distribuer des fichiers

Si vous devez enregistrer des EIF dans l’application et les distribuer vers un ordinateur ou un autre appareil via l’application Fichiers de visionOS, ajoutez et modifiez les champs suivants dans Info.plist :

• Ajouter LSSupportsOpeningDocumentsInPlace et définir la valeur sur true.

• Ajouter UIFileSharingEnabled et définir la valeur sur true.

Astuce

Après l’ajout des champs, le Key affiché par Xcode diffère de la chaîne saisie manuellement (par exemple, saisir LSSupportsOpeningDocumentsInPlace peut afficher Supports opening documents in place ; c’est normal).