Przejdź do treści
Darmowy audyt

Konfiguratory 3D Problem i rozwiązanie

Model 3D nie działa w AR na iPhonie - plik USDZ, typ MIME i przycisk AR krok po kroku

Autor: Bartosz Gromek Zaktualizowano: 5 min czytania

W skrócie

  • Objaw: na Androidzie model otwiera się w AR, a na iPhonie przycisk AR nie pojawia się, nic nie robi albo otwiera stronę z samym plikiem.
  • Przyczyna: brak pliku USDZ (AR Quick Look nie otwiera plików GLB), serwer wysyła USDZ z niewłaściwym typem MIME, link nie ma atrybutu rel="ar" z jednym obrazkiem w środku albo strona jest otwarta w przeglądarce wbudowanej w aplikację.
  • Rozwiązanie: przygotuj plik USDZ, ustaw na serwerze typ model/vnd.usdz+zip, popraw link albo użyj model-viewer z atrybutem ios-src i testuj na prawdziwym iPhonie w Safari.

Nie masz czasu? Zrobimy to za Ciebie - Konfigurator 3D na stronę od 3 500 zł netto

Model 3D nie działa w AR na iPhonie najczęściej dlatego, że strona podaje tylko plik GLB, a AR Quick Look, czyli systemowy podgląd AR w iOS, przyjmuje pliki .usdz i .reality. Drugą częstą przyczyną jest serwer, który wysyła plik USDZ z niewłaściwym typem MIME, albo link zbudowany niezgodnie z wymaganiami Safari. Naprawa zwykle sprowadza się do przygotowania pliku USDZ, jednej zmiany na serwerze i poprawnego przycisku AR.

Jak to wygląda

  • na Androidzie przycisk AR działa, a na iPhonie w ogóle się nie pojawia,
  • przycisk jest widoczny, ale po dotknięciu nic się nie dzieje,
  • zamiast podglądu AR otwiera się strona z ikoną pliku albo pobieranie,
  • AR działa w Safari, ale nie po wejściu z reklamy w aplikacji społecznościowej,
  • model otwiera się w AR, ale ma inne kolory, złą skalę albo leży na boku.

Dlaczego AR nie działa na iPhonie?

Brak pliku USDZ

Według dokumentacji Apple treści do AR Quick Look dostarcza się w formacie .usdz albo .reality. Plik GLB, który działa w przeglądarce i w Scene Viewer na Androidzie, na iPhonie nie otworzy się w AR. Jeśli strona korzysta z komponentu model-viewer i nie podaje osobnego pliku w atrybucie ios-src, komponent może wygenerować USDZ w locie po naciśnięciu przycisku AR, ale tylko wtedy, gdy tryb quick-look jest włączony w atrybucie ar-modes.

Niewłaściwy typ MIME na serwerze

Safari oczekuje, że plik USDZ będzie wysyłany z typem model/vnd.usdz+zip. Część serwerów nie zna tego rozszerzenia i wysyła plik jako ogólny typ binarny, a wtedy iPhone nie rozpoznaje go jako modelu AR. Problem często wychodzi dopiero po przeniesieniu strony na inny hosting albo po dodaniu CDN.

Przy ręcznie zbudowanym przycisku Safari otwiera AR Quick Look tylko wtedy, gdy link ma atrybut rel="ar" i zawiera dokładnie jeden element img lub picture. Link tekstowy, link z kilkoma elementami w środku albo przycisk otwierający plik przez JavaScript prowadzą do zwykłej strony z plikiem.

Przeglądarka wbudowana w aplikację

Dokumentacja Apple opisuje otwieranie takiego linku w Safari i w widoku przeglądarki wyświetlanym w aplikacji, ale w praktyce przeglądarki wbudowane w aplikacje społecznościowe nie zawsze przekazują model do AR Quick Look. Klient, który wszedł z reklamy, widzi wtedy przycisk, który nic nie robi.

Problemy z samym plikiem

Plik USDZ przekonwertowany automatycznie może mieć inne materiały niż GLB, a jeśli model źródłowy zapisano w milimetrach albo z osią Z w górę, także złą skalę i orientację. Zbyt ciężki plik otwiera się długo, więc klient uznaje, że AR nie działa.

Jak to naprawić?

Sprawdzenie Poprawny stan
Plik do AR na iPhonie Osobny plik .usdz albo włączone generowanie USDZ w model-viewer
Typ MIME model/vnd.usdz+zip dla plików .usdz
Link ręczny rel="ar" i dokładnie jeden element img lub picture w środku
model-viewer Atrybut ar, tryb quick-look w ar-modes i ios-src z adresem pliku USDZ
Skala i orientacja Metry, oś Y w górę, punkt zero na poziomie podłoża
Test Prawdziwy iPhone, Safari i ścieżka z reklamy

Typ MIME ustawia się w konfiguracji serwera, a przy CDN w jego ustawieniach. Na serwerze Apache wystarczą dwie linie w pliku .htaccess lub konfiguracji serwera (druga ustawia typ dla plików GLB):

AddType model/vnd.usdz+zip .usdz
AddType model/gltf-binary .glb

Po zmianie sprawdź w narzędziach przeglądarki albo poleceniem curl -I, jaki nagłówek Content-Type zwraca adres pliku. Najprostszy przycisk AR, który sam dobiera tryb do urządzenia, daje komponent model-viewer:

<model-viewer src="altana.glb" ios-src="altana.usdz" ar
  ar-modes="webxr scene-viewer quick-look"
  poster="altana.webp" alt="Altana ogrodowa, model 3D"></model-viewer>

AR na iPhonie testuj zawsze na prawdziwym urządzeniu. Narzędzia na komputerze nie pokażą, czy AR Quick Look faktycznie się otwiera, a różnice w materiałach i skali widać dopiero w AR.

Co jeszcze sprawdzić

Po naprawie sprawdź też Androida, bo tam działa inny mechanizm (Scene Viewer lub WebXR) z innymi wymaganiami, oraz wagę plików: ciężki USDZ otwiera się długo, a klient może uznać, że przycisk nie działa. Jak odchudzić model, opisujemy we wpisie za duży plik GLB, a osadzenie modelu w karcie produktu we wpisie jak dodać model 3D do sklepu WooCommerce. Pliki GLB i USDZ, przycisk AR i osadzenie na stronie lub w sklepie przygotowujemy w ramach usługi wizualizacje 3D produktu.

Ten problem jest jednym z naszej listy 30 problemów z modelem 3D i AR na stronie.

Jak to rozwiązać krok po kroku

Model 3D nie działa w AR na iPhonie - plik USDZ, typ MIME i przycisk AR krok po kroku - https://codescriptum.pl/blog/model-3d-nie-dziala-w-ar-na-iphonie/

  1. Otwórz stronę na prawdziwym iPhonie w Safari i sprawdź, czy przycisk AR się pojawia i co dzieje się po jego dotknięciu.
  2. Sprawdź, czy strona wskazuje plik USDZ (ios-src w model-viewer albo link z rel="ar"); jeśli nie, przygotuj USDZ z tego samego modelu co GLB albo włącz generowanie w locie.
  3. Sprawdź nagłówek Content-Type adresu pliku USDZ i ustaw na serwerze lub w CDN typ model/vnd.usdz+zip.
  4. Przy ręcznie zbudowanym linku upewnij się, że ma atrybut rel="ar" i zawiera dokładnie jeden element img lub picture.
  5. Sprawdź w AR skalę, orientację i kolory modelu i porównaj je z wersją na stronie.
  6. Przetestuj ścieżkę z reklamy w aplikacji społecznościowej i, jeśli AR tam nie działa, pokaż komunikat z prośbą o otwarcie strony w Safari.

Jak sprawdzić, że zadziałało

Na iPhonie w Safari przycisk AR otwiera AR Quick Look, a model stoi na podłodze w prawdziwej skali i ma właściwe kolory. Adres pliku USDZ zwraca nagłówek Content-Type: model/vnd.usdz+zip, a na Androidzie AR działa tak jak wcześniej.

Usługa CodeScriptum

Konfigurator 3D na stronę

od 3 500 zł netto

  • Model 3D produktu z wymiarami, kolorami i dodatkami
  • Cena na żywo z Twojego cennika i zapytanie z konfiguracją
  • Pełny kod u Ciebie, bez abonamentu

Najczęściej zadawane pytania

Czy iPhone otworzy w AR plik GLB?

Nie. AR Quick Look przyjmuje pliki .usdz i .reality. Plik GLB wystarczy do podglądu 3D w przeglądarce i do AR na Androidzie, ale na iPhonie potrzebny jest USDZ, przygotowany osobno albo wygenerowany w locie przez model-viewer.

Od której wersji iOS działa AR w Safari?

Według WebKit oglądanie modeli 3D i AR w Safari jest dostępne od iOS 12, na urządzeniach obsługujących AR. Klienci ze starszymi urządzeniami powinni widzieć zwykły podgląd 3D albo zdjęcia.

Czy USDZ wygenerowany w locie wystarczy?

Przy prostych produktach często tak. Przy produktach, w których liczy się kolor i materiał, przygotuj osobny USDZ i porównaj go z wersją GLB na iPhonie, bo konwersja może zmienić wygląd materiałów.

Źródła

  1. Apple: Previewing a Model with AR Quick Look (otwiera się w nowej karcie) developer.apple.com
  2. WebKit: Viewing Augmented Reality Assets in Safari for iOS (otwiera się w nowej karcie) webkit.org
  3. model-viewer: dokumentacja komponentu (ar, ar-modes, ios-src) (otwiera się w nowej karcie) modelviewer.dev

Podobne problemy

O autorze

Bartosz Gromek

Założyciel CodeScriptum, technologia i rozwój

Założyciel CodeScriptum - firmy technologicznej z Łodzi, działającej od 2022 roku. Odpowiada za technologię i rozwój, a projekty realizuje razem z zespołem specjalistów od stron, sklepów internetowych, systemów CRM, integracji, AI i marketingu. Na blogu opisuje problemy, z którymi zgłaszają się klienci CodeScriptum, i sprawdzone sposoby ich rozwiązania.

Newsletter

Konkretne porady raz na jakiś czas

Nowe problemy i rozwiązania z bloga, zmiany w przepisach dla sklepów i stron oraz sprawdzone sposoby na więcej klientów z internetu. Bez spamu, wypis jednym kliknięciem.