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
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.
Link AR zbudowany niezgodnie z wymaganiami
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/
- Otwórz stronę na prawdziwym iPhonie w Safari i sprawdź, czy przycisk AR się pojawia i co dzieje się po jego dotknięciu.
- 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.
- Sprawdź nagłówek Content-Type adresu pliku USDZ i ustaw na serwerze lub w CDN typ model/vnd.usdz+zip.
- Przy ręcznie zbudowanym linku upewnij się, że ma atrybut rel="ar" i zawiera dokładnie jeden element img lub picture.
- Sprawdź w AR skalę, orientację i kolory modelu i porównaj je z wersją na stronie.
- 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
Podobne problemy
Konfiguratory 3D
Model 3D i AR na stronie: 30 problemów i jak je rozwiązać (2026)
Przy każdym z 30 problemów podajemy przyczynę i rozwiązanie; większość da się wychwycić przed publikacją, testując model na prawdziwych telefonach z iOS i Androidem.
Konfiguratory 3D
Za duży plik GLB: model 3D ładuje się długo, a strona się zacina - jak go odchudzić
Rozwiązanie Sprawdź, co waży najwięcej, zmniejsz tekstury i skompresuj je do KTX2, uprość i skompresuj geometrię (Draco lub Meshopt), usuń zbędne dane, a model ładuj po…
Konfiguratory 3D
Jak dodać model 3D do sklepu WooCommerce - galeria produktu, AR i szybkość krok po kroku
Rozwiązanie Przygotuj lekkie pliki GLB i USDZ, zezwól na ich wgrywanie albo trzymaj je na serwerze plików, osadź przeglądarkę 3D w galerii produktu ze zdjęciem jako podglądem i…
Konfiguratory 3D
Zdjęcia 360 czy model 3D produktu? Porównanie dla sklepów i producentów
Rozwiązanie Zdjęcia 360 przy małych produktach w jednym wariancie, które masz fizycznie; model 3D przy produktach dużych, wielowariantowych, robionych na zamówienie albo gdy…