Jak używać AR.js i Three.js, by dodać rozszerzoną rzeczywistość do zwykłej strony HTML

Dlaczego AR w zwykłej stronie HTML i kiedy to ma sens

WebAR kontra natywne frameworki ARKit/ARCore

Rozszerzona rzeczywistość w przeglądarce (WebAR) oparta na AR.js i Three.js działa bez instalowania aplikacji, bez sklepu z aplikacjami i długiego cyklu publikacji. Użytkownik otwiera link, udziela zgody na dostęp do kamery i od razu widzi scenę AR. To kluczowa przewaga nad natywnymi frameworkami ARKit/ARCore, które wymagają dedykowanej aplikacji mobilnej oraz kompilacji na iOS/Android.

ARKit i ARCore oferują znacznie bardziej zaawansowane śledzenie przestrzeni, precyzyjne rozpoznawanie płaskich powierzchni, stabilne śledzenie bez markerów (markerless), oceny głębi i okluzji. Natomiast AR.js skoncentrowany jest głównie na AR markerowej oraz prostym location-based AR, działając w obrębie standardów webowych (WebRTC, WebGL, WebXR). Śledzenie jest prostsze, wymaga zazwyczaj wydrukowanego markera lub odpowiedniego wzorca, a interakcje z otoczeniem są bardziej ograniczone.

Z punktu widzenia architektury rozwiązania: natywne frameworki to wybór, gdy potrzebne jest pełne zanurzenie, śledzenie pomieszczenia, interakcje z rękami użytkownika czy integracja z hardware (np. LiDAR). WebAR z AR.js to lżejsza warstwa wizualna, integrująca się bezpośrednio ze stroną WWW i istniejącym front-endem. Jeśli projekt wymaga ścisłego powiązania z systemem CMS, analityką webową i szybkim A/B testowaniem, WebAR zwykle jest wygodniejszym narzędziem.

Jeśli priorytetem jest szeroka dostępność i brak bariery instalacji – WebAR z AR.js i Three.js daje minimalny próg wejścia kosztem zaawansowanych funkcji śledzenia i realizmu grafiki.

Scenariusze, gdzie prosta AR na WWW jest wystarczająca

Prosta, markerowa AR w przeglądarce sprawdza się, kiedy celem jest krótka interakcja, efekt „wow” lub szybkie przekazanie informacji. Typowe zastosowania to:

• Kampanie marketingowe – ulotki, plakaty lub opakowania z markerem, po zeskanowaniu których na ekranie pojawia się animowany model produktu, logo 3D lub prosta gra promocyjna.
• Edukacja – podręczniki z nadrukowanymi markerami, które po zeskanowaniu wyświetlają model 3D serca, planety czy maszyn, bez konieczności instalowania aplikacji szkolnej na wszystkich urządzeniach.
• Katalogi produktów i instrukcje – możliwość obejrzenia uproszczonego modelu 3D na biurku użytkownika, z podstawową animacją lub wskazówkami montażu.
• Wystawy i eventy – kiosk w galerii handlowej lub stoisko targowe, gdzie użytkownicy skanują wydrukowane markery umieszczone na standach.

W takich scenariuszach kluczowe jest, aby:

• doświadczenie było natychmiastowe (link → AR bez instalacji),
• czas interakcji był relatywnie krótki (kilkadziesiąt sekund do kilku minut),
• aplikacja AR nie wymagała pełnego mapowania pomieszczenia i ruchu użytkownika w większej przestrzeni.

Jeżeli projekt ma charakter „dodatku” do treści WWW, a nie samodzielnej, złożonej aplikacji, AR.js i Three.js zapewniają sensowny kompromis między kosztem wdrożenia a efektem końcowym.

Ograniczenia AR.js i Three.js względem Unity/Unreal

Unity i Unreal Engine, z integracją ARKit/ARCore, potrafią śledzić płaskie powierzchnie, ściany, rozpoznawać obiekty, korzystać z okluzji i zaawansowanych shaderów, jednocześnie renderując wysokiej jakości grafikę 3D. WebAR w przeglądarce jest ograniczany zarówno przez API przeglądarek, jak i moc obliczeniową typowego smartfona przy działającej równolegle stronie WWW.

Najważniejsze ograniczenia AR.js i Three.js to:

• Tryb śledzenia – w typowej konfiguracji marker-based AR, stabilność i dokładność pozycji są zależne od jakości markera, oświetlenia, odległości i kąta kamery.
• Wydajność grafiki – sceny 3D muszą być lekkie: niewiele polygonów, niewiele złożonych materiałów, ograniczona liczba świateł. Nadmiar detalu szybko ujawnia się spadkiem FPS na słabszych smartfonach.
• Interakcje – brak natywnego dostępu do wszystkich czujników, brak zaawansowanego raycastingu w otoczeniu rzeczywistym; interakcje zwykle ograniczają się do kliknięć na ekranie, przycisków HTML lub prostych gestów.
• Środowisko – aplikacja działa w zakładce przeglądarki, współdzieli zasoby z innymi kartami, podlega ograniczeniom bezpieczeństwa (HTTPS, zgody użytkownika, polityka kamery).

Jeżeli projekt wymaga bardzo płynnej, dwuręcznej interakcji, długiej sesji (np. gra na 30–60 minut), zaawansowanej fizyki i wysokiej jakości efektów graficznych, wybór AR.js będzie sygnałem ostrzegawczym – taki projekt zwykle lepiej zrealizować w Unity lub Unreal.

Wymagania techniczne po stronie użytkownika

AR.js i Three.js działają w zwykłej przeglądarce, ale nie w każdych warunkach. Minimum techniczne po stronie użytkownika obejmuje:

• przeglądarkę z obsługą WebGL i getUserMedia/WebRTC (Chrome, Firefox, Safari – nowsze wersje),
• urządzenie z kamerą (smartfon, tablet, laptop z kamerką),
• połączenie przez HTTPS lub lokalnie przez localhost (inaczej kamera zostanie zablokowana),
• wystarczającą moc GPU/CPU do renderowania sceny 3D i równoczesnego przetwarzania obrazu z kamery.

Na starszych urządzeniach mobilnych AR może działać, ale będzie mniej płynna: spadki FPS, „drganie” modelu, wolne reagowanie na ruch markera. W projektach produkcyjnych minimum to testy na kilku typowych urządzeniach (średnia i niższa półka), zamiast zakładania, że jeśli działa na jednym, to wszędzie jest dobrze.

Jeśli wymagany jest dostęp offline, pełne wsparcie starych przeglądarek lub środowisko bez HTTPS (np. legacy intranet), AR.js nie spełni wymagań – to silny punkt kontrolny przed wejściem w WebAR w ogóle.

Kiedy nie używać AR.js – kryteria negatywne

Przed decyzją o wdrożeniu AR.js warto przejść przez zestaw kryteriów, które sygnalizują, że to nie jest właściwe narzędzie:

• projekt wymaga śledzenia bez markerów (pełne rozpoznawanie otoczenia, wykrywanie powierzchni, okluzja za realnymi obiektami),
• sesje AR mają trwać długo, z intensywną interakcją (gra, symulator, narzędzie zawodowe),
• wymagane są zaawansowane efekty graficzne, skomplikowane shader’y i duże modele 3D,
• publiczność korzysta głównie z bardzo słabych urządzeń lub przeglądarek bez WebGL,
• wymagane jest pełne działanie offline bez serwera HTTPS oraz bez zgód na kamerę.

Jeżeli któryś z powyższych punktów jest kluczowym wymaganiem, WebAR z AR.js stanie się wąskim gardłem. Jeżeli natomiast najważniejsza jest szybkość uruchomienia, brak instalacji i prostota utrzymania – AR.js i Three.js będą rozsądnym wyborem.

Podstawy technologii: jak „myśli” AR.js i jak w to wpasowuje się Three.js

Architektura AR.js: kamera, śledzenie, nakładka 3D

AR.js składa się z kilku głównych warstw, które razem budują doświadczenie AR w przeglądarce:

• Warstwa wideo – strumień z kamery pobierany poprzez WebRTC (getUserMedia) i wyświetlany w tle sceny lub na teksturze.
• Warstwa śledzenia markerów – algorytmy wykrywające markery (np. Hiro) w strumieniu wideo i wyliczające ich pozycję oraz orientację względem kamery.
• Warstwa 3D – integracja z Three.js (lub A-Frame), która tworzy scenę 3D, kamerę, światła i modele.

AR.js okresowo (klatka po klatce) analizuje obraz z kamery, szuka wzorców markera, a po ich odnalezieniu aktualizuje macierz transformacji odpowiedzialną za pozycję obiektu 3D. Three.js używa tej informacji do umieszczenia modelu dokładnie „nad” markerem w obrazie z kamery.

Kluczowy punkt kontrolny: AR.js nie przestawia realnej kamery – symuluje ją w wirtualnej scenie Three.js na podstawie tego, jak „widziany” jest marker. Jeśli obraz z kamery jest słabej jakości, oświetlenie kiepskie, a marker ma niski kontrast, dane wejściowe dla Three.js są niestabilne, co przekłada się na drgania i znikanie obiektów.

Rola Three.js w całym procesie

Three.js pełni rolę silnika renderującego 3D – to on odpowiada za:

• tworzenie sceny,
• definicję kamery perspektywicznej lub ortograficznej,
• obsługę renderera WebGL,
• wczytywanie i renderowanie modeli 3D, materiałów i świateł,
• animacje, pętlę renderowania oraz integrację z requestAnimationFrame.

AR.js łączy się z Three.js między innymi przez tzw. AR.js context, który dostarcza parametry kamery (macierze projekcji i widoku) oraz aktualizuje pozycję obiektów przypisanych do markerów. W praktyce Three.js nie musi „wiedzieć”, że rendering jest częścią AR; widzi jedynie dynamicznie zmieniające się transformacje obiektów.

Dla dewelopera WebAR oznacza to, że logika sceny 3D (modele, materiały, animacje) i logika AR (śledzenie markerów) są względnie oddzielne. Jeśli projekt jest poprawnie zaprojektowany, można np. łatwo podmienić model 3D lub materiały bez grzebania w konfiguracji śledzenia AR.

Jak działają markery: Hiro, Kanji, niestandardowe

AR.js bazuje na markerach wzorowanych na kodach binarnych (np. klasyczne HIRO, KANJI) oraz na markerach zdefiniowanych przez użytkownika. W uproszczeniu:

• kamera przekazuje obraz do AR.js,
• AR.js konwertuje obraz na odcienie szarości i szuka wzorców geometrycznych o wysokim kontraście,
• po znalezieniu potencjalnego markera sprawdza, czy pasuje on do załadowanej bazy markerów (np. plik .patt),
• dla dopasowanego markera obliczana jest pozycja i rotacja względem kamery.

Standardowe markery (Hiro, Kanji) są dostarczane z AR.js razem z predefiniowanymi plikami .patt. Marker niestandardowy tworzy się, generując wzorzec z własnej grafiki (np. logotypu lub symbolu) i zapisując go jako plik .patt, który AR.js może wczytać. Im wyraźniejszy kontrast i prostszy kształt, tym stabilniejsza detekcja.

Jeżeli model 3D „skacze”, znika lub jest wykrywany z dużym opóźnieniem, najczęstszą przyczyną jest nieoptymalny marker – zbyt mały, słaby kontrast, zbyt dużo detalu lub odbicia światła. To pierwszy sygnał ostrzegawczy, zanim zacznie się podejrzewać kod czy wydajność Three.js.

Tryb marker-based vs location-based w AR.js

AR.js obsługuje dwa główne podejścia:

• marker-based AR – pozycjonowanie obiektu 3D względem wydrukowanego markera (najpopularniejszy, stabilny tryb),
• location-based AR – pozycja obiektów 3D zależy od lokalizacji GPS użytkownika (np. punkty POI w mieście).

Dla zastosowań „zwykłej” strony HTML najczęściej wybiera się tryb marker-based, ponieważ jest prostszy do testowania i nie wymaga dostępu do GPS. Kod jest krótszy, bardziej przewidywalny, a środowisko testowe (biuro, sala konferencyjna) łatwo kontrolować.

Tryb location-based ma dodatkowe wymagania: dokładność GPS, obsługa uprawnień lokalizacji, interpretacja geokoordynatów i map. Jeśli celem jest szybkie wdrożenie rozszerzonej rzeczywistości do strony WWW, location-based AR jest dodatkową warstwą złożoności i ryzykiem błędów, chyba że zespół ma doświadczenie w systemach mapowych i geolokalizacji.

A-Frame a „czyste” Three.js – dwa podejścia do AR.js

AR.js historycznie zaczęło jako rozszerzenie A-Frame (frameworka deklaratywnego dla WebVR/AR). Dzisiaj można korzystać z dwóch stylów integracji:

• A-Frame + AR.js – deklaratywne komponenty HTML (np. <a-scene>, <a-marker>), mniej kodu JavaScript, mniejsza kontrola nad niskopoziomowymi szczegółami Three.js.
• „Czyste” Three.js + AR.js – pełna kontrola nad sceną, rendererem, materiałami i animacjami, bardziej techniczny kod, ale większe możliwości optymalizacji.

Jeśli priorytetem jest maksymalna kontrola i wydajność, a zespół zna Three.js, drugo podejście jest lepszym wyborem. A-Frame bywa szybszy na start, ale w projektach produkcyjnych, wymagających precyzyjnej optymalizacji, często kończy się i tak na bezpośredniej pracy z Three.js.

Dobór między A-Frame a „czystym” Three.js dobrze poprzedzić krótkim przeglądem wymagań. Jeżeli zespół składa się głównie z front-endowców przyzwyczajonych do pracy w HTML i komponentach, A-Frame będzie mniej bolesnym wejściem, a pierwsze prototypy powstaną szybciej. W sytuacji, w której krytyczne są drobiazgi: niestandardowe shadery, agresywna optymalizacja renderingu, integracja z istniejącym silnikiem 3D – bezpośrednie użycie Three.js z AR.js daje większą przewidywalność i mniej „magii” ukrytej w frameworku. Punkt kontrolny: jeśli w backlogu pojawiają się zadania typu „custom post-processing”, „profilowanie GPU” czy „niestandardowy pipeline ładowania modeli”, A-Frame powinien być traktowany jako etap prototypowy, a nie docelowa platforma.

Rozsądna strategia wdrażania WebAR w organizacji to często podejście dwuetapowe: prosty dowód koncepcji (PoC) z A-Frame, aby zweryfikować samą wartość biznesową AR, a następnie świadoma migracja do czystego Three.js w momencie, gdy wymagania rosną. Sygnał ostrzegawczy, że ten krok jest spóźniony, to mnożące się obejścia i „hacki” w komponentach A-Frame, które tylko po to istnieją, by wymusić zachowanie, jakie w Three.js byłoby naturalne do zaimplementowania. Jeżeli zespół już teraz spędza więcej czasu na walce z ograniczeniami frameworka niż na samej logice AR, to decyzja o przejściu na niższy poziom abstrakcji jest bardziej kwestią higieny technicznej niż ambicji.

Na poziomie organizacyjnym AR.js w połączeniu z Three.js można traktować jak precyzyjne narzędzie: sprawdza się świetnie, gdy zakres jest jasno określony, a scenariusz użycia mieści się w ramach marker-based WebAR. Minimalne środowisko (statyczny hosting HTTPS, kamera, przeglądarka z WebGL) to niskie progi wejścia, ale jednocześnie czytelne kryteria, które łatwo zweryfikować przed startem. Jeżeli po przejściu przez takie kryterialne sito projekt dalej „się spina” – technicznie i biznesowo – WebAR na zwykłej stronie HTML staje się nie tyle ciekawostką, ile praktycznym kanałem dostarczania treści 3D bez instalacji i ciężkich natywnych aplikacji.

Minimalne środowisko pracy: narzędzia, struktura projektu i punkt kontrolny bezpieczeństwa

Najmniejszy działający projekt AR.js + Three.js nie wymaga rozbudowanego toolchainu. W praktyce wystarczą pliki HTML/JS, prosty serwer HTTP z HTTPS oraz przeglądarka mobilna lub desktopowa z kamerą i obsługą WebGL. Problem zaczyna się wtedy, gdy któryś z tych elementów jest „półsprawny” – AR testuje nie tylko kod, ale i cały łańcuch od sterownika kamery po certyfikat TLS.

Podstawowe narzędzia i środowisko uruchomieniowe

Lista obowiązkowa przed pierwszym commitowaniem kodu AR do repozytorium powinna wyglądać mniej więcej tak:

• aktualna przeglądarka (Chrome, Firefox, Safari, Edge) z obsługą WebGL i getUserMedia,
• prosty serwer HTTPS (np. http-server z Node z samopodpisanym certyfikatem lub serwer wbudowany w IDE, skonfigurowany pod TLS),
• zainstalowany Node.js (nawet jeśli nie używa się bundlera – przyda się do uruchomienia serwera lokalnego),
• drukarka lub przynajmniej drugi ekran do wyświetlenia markera,
• repozytorium GIT z rozdzieleniem gałęzi eksperymentalnych od produkcyjnej.

Sygnał ostrzegawczy to sytuacja, w której zespół testuje AR na file:// lub bez HTTPS. Jeżeli na starcie ignorowane są podstawowe wymagania API przeglądarek, każde kolejne „niewyjaśnione” zachowanie kamery będzie kosztować czas i nerwy.

Jeśli środowisko nie przechodzi prostego testu: „HTTPS działa, kamera jest dostępna, WebGL nie zgłasza błędów”, lepiej zatrzymać prace nad AR i najpierw ustabilizować fundament – inaczej debugowanie kodu stanie się maskowaniem braków infrastruktury.

Struktura katalogów w małym projekcie AR

Nawet w minimalnym projekcie opłaca się narzucić porządek plików. Pozornie jest to „tylko demo”, ale nieuporządkowana struktura szybko uniemożliwia kontrolę nad wersjami bibliotek i markerów.

project-root/
├─ index.html
├─ js/
│  ├─ three.min.js
│  ├─ ar.js
│  └─ app.js
├─ assets/
│  ├─ models/
│  │  └─ cube.gltf
│  ├─ textures/
│  └─ markers/
│     ├─ hiro.patt
│     └─ custom-logo.patt
└─ css/
   └─ style.css

Krytyczne jest rozdzielenie:

• kod aplikacyjny (app.js) vs biblioteki (Three.js, AR.js),
• zasoby AR (markery, pliki .patt) vs zasoby 3D (modele, tekstury),
• plik startowy (index.html) vs kod eksperymentalny (np. playground.html w osobnym katalogu).

Punkt kontrolny: jeśli po tygodniu pracy nikt nie jest w stanie wskazać, które wersje Three.js i AR.js są faktycznie używane w produkcyjnym buildzie, struktura katalogów jest zbyt „luźna”. Od takiej niejasności tylko krok do sytuacji, w której jedna scena działa na innej wersji AR.js niż druga, mimo że obie są serwowane z tej samej domeny.

Jeżeli repozytorium zawiera mieszankę plików HTML „test1.html”, „newtest.html”, „last3.html”, a nikt nie chce ich usuwać w obawie, że „coś się rozsypie”, to sygnał ostrzegawczy – trudno audytować jakość w projekcie, który nie ma jasno oznaczonego punktu wejścia.

Konfiguracja lokalnego serwera HTTPS

WebAR w przeglądarce praktycznie wymusza HTTPS. Warto przygotować minimalny, powtarzalny skrypt lub instrukcję dla zespołu, zamiast liczyć na improwizację każdego dewelopera.

Przykładowe uruchomienie z użyciem http-server (Node.js):

npm install -g http-server
http-server -S -C cert.pem -K key.pem -p 8080

Lista kontrolna dla lokalnego HTTPS:

• certyfikat może być samopodpisany, ale cała ekipa zna procedurę dodawania wyjątku w przeglądarce,
• adres URL jest spójny w dokumentacji i zrzutach ekranu (np. https://localhost:8080/),
• port nie koliduje z innymi usługami (backend, proxy),
• czas ważności certyfikatu nie wygaśnie „po cichu” podczas warsztatów z klientem.

Jeśli deweloperzy zaczynają „na szybko” przełączać się z HTTPS na HTTP, bo „na lokalnym nie działa kamera, ale na file:// działa”, to punkt kontrolny, by zatrzymać prace i rozwiązać problem prawidłowo. Tego typu skróty zemszczą się przy pierwszym deployu na staging.

Jeżeli zespół ma spójne, udokumentowane polecenie uruchamiania serwera dev (np. w README) i każdy nowy członek potrafi w 5 minut uruchomić działające demo AR, to poziom ryzyka infrastrukturalnego jest akceptowalny – można spokojniej przejść do pracy z kodem.

Bezpieczeństwo i prywatność a dostęp do kamery

AR w przeglądarce od razu dotyka tematów prywatności. Przeglądarka wymusza wyraźną prośbę o dostęp do kamery, ale to nie zwalnia z przygotowania przejrzystej komunikacji dla użytkownika.

Minimalny standard to:

• osobny, widoczny komunikat na stronie (nie tylko domyślny popup przeglądarki) z wyjaśnieniem, po co jest kamera,
• informacja, że obraz z kamery nie jest wysyłany na serwer (jeśli faktycznie pozostaje lokalnie),
• łatwo dostępny przycisk pozwalający wyłączyć AR (np. zatrzymać stream wideo, ukryć canvas),
• sprawdzenie zachowania w trybie „odmowa dostępu do kamery” – strona musi pozostać używalna.

Sygnał ostrzegawczy: gdy jedyną reakcją aplikacji na odmowę dostępu do kamery jest czarny ekran. Z perspektywy użytkownika oznacza to „strona się popsuła”, a nie „świadomie wyłączyłem AR”.

Jeżeli w logach serwera nie pojawiają się żadne dane obrazowe, a polityka prywatności wyraźnie odzwierciedla sposób działania AR.js (lokalne przetwarzanie obrazu), argument o bezpieczeństwie jest łatwiejszy do przedstawienia działowi prawnemu i klientom biznesowym.

Pierwsza scena AR: od czystego HTML do obiektu 3D na markerze

Najprostsza scena marker-based AR z Three.js i AR.js ma trzy kluczowe elementy: kamerę, marker oraz obiekt 3D. Dopóki te trzy elementy nie współpracują stabilnie, nie ma sensu dokładać animacji, modeli GLTF czy zaawansowanego oświetlenia.

Minimalny szablon HTML pod WebAR

Na początek wystarczy pojedynczy plik HTML ze wstrzykniętym skryptem JS. Struktura DOM jest prosta – AR.js i Three.js same stworzą potrzebne canvasy.

<!DOCTYPE html>
<html lang="pl">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Pierwsza scena AR</title>
  <style>
    body { margin: 0; overflow: hidden; }
    #status { position: fixed; top: 0; left: 0; padding: 6px 10px;
              background: rgba(0,0,0,0.6); color: #fff; font-size: 12px; }
  </style>
</head>
<body>
  <div id="status">Inicjalizacja...</div>

  <script src="js/three.min.js"></script>
  <script src="js/ar.js"></script>
  <script src="js/app.js"></script>
</body>
</html>

Drobny element jak #status często ratuje debugowanie – pozwala przekazać informację „kamera gotowa”, „marker znaleziony” zamiast zgadywać, dlaczego obraz się nie pojawia.

Jeśli na tym etapie szablon HTML zaczyna być obudowywany ciężkimi frameworkami (SPA, routery, złożone layouty), warto się zatrzymać. Najpierw scena AR ma działać samodzielnie, dopiero później sensownie scala się ją z resztą aplikacji.

Konfiguracja kamery AR i sceny Three.js

W pliku app.js konfiguracja polega na spięciu trzech obiektów: renderera, sceny i kontekstu AR.

let renderer, scene, camera;
let arSource, arContext, arMarker;

init();
animate();

function init() {
  // Renderer
  renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
  renderer.setSize(window.innerWidth, window.innerHeight);
  renderer.setPixelRatio(window.devicePixelRatio);
  renderer.domElement.style.position = 'absolute';
  renderer.domElement.style.top = '0';
  renderer.domElement.style.left = '0';
  document.body.appendChild(renderer.domElement);

  // Scena
  scene = new THREE.Scene();

  // Kamera wirtualna
  camera = new THREE.Camera();
  scene.add(camera);

  // Źródło wideo
  arSource = new THREEx.ArToolkitSource({
    sourceType: 'webcam'
  });

  arSource.init(function onReady() {
    onResize();
  });

  window.addEventListener('resize', onResize);

  // Kontekst AR
  arContext = new THREEx.ArToolkitContext({
    cameraParametersUrl: 'data/camera_para.dat',
    detectionMode: 'mono'
  });

  arContext.init(function onCompleted() {
    camera.projectionMatrix.copy(arContext.getProjectionMatrix());
  });

  // Marker
  arMarker = new THREEx.ArMarkerControls(arContext, camera, {
    type: 'pattern',
    patternUrl: 'assets/markers/hiro.patt',
    changeMatrixMode: 'cameraTransformMatrix'
  });

  // Prosty obiekt 3D
  const geometry = new THREE.BoxGeometry(1, 1, 1);
  const material = new THREE.MeshNormalMaterial();
  const cube = new THREE.Mesh(geometry, material);
  cube.position.y = 0.5;

  const markerRoot = new THREE.Group();
  markerRoot.add(cube);
  scene.add(markerRoot);

  document.getElementById('status').textContent = 'Oczekiwanie na marker...';
}

function onResize() {
  arSource.onResizeElement();
  arSource.copyElementSizeTo(renderer.domElement);
}

function animate() {
  requestAnimationFrame(animate);

  if (!arSource || !arSource.ready) return;

  arContext.update(arSource.domElement);
  renderer.render(scene, camera);
}

Punkt kontrolny: jeśli po wdrożeniu takiej minimalnej sceny obiekt nie pojawia się nad standardowym markerem Hiro, trzeba szukać błędu w konfiguracji AR (URL-e, parametry kamery, inicjalizacja), a nie w samym Three.js. Dopiero gdy marker jest stabilnie rozpoznawany, opłaca się inwestować czas w rozbudowę sceny.

Jeżeli po dodaniu prostego boxa na markerze kadr jest stabilny przez kilka sekund i nie występują drgania, można przejść dalej. Gdy obiekt „pływa” lub znika przy minimalnym ruchu ręki, problem leży najczęściej w wydruku, oświetleniu lub błędnym dobraniu parametrów detectionMode/cameraParametersUrl.

Podstawowy cykl życia sceny AR

Procedura działania każdej klatki w marker-based AR wygląda zawsze podobnie. Zrozumienie tego schematu ułatwia późniejsze debugowanie.

1. AR.js pobiera kolejną klatkę z kamery (obraz wideo).
2. Silnik detekcji wyszukuje markery i aktualizuje macierze transformacji.
3. Three.js renderuje scenę z użyciem zaktualizowanej kamery i pozycji obiektów.

W kodzie sprowadza się to do sekwencji: aktualizacja kontekstu AR (np. arContext.update()) i renderowanie sceny (renderer.render()) w pętli requestAnimationFrame.

Sygnał ostrzegawczy: rozbudowana logika w tej pętli (ciężkie obliczenia, fetch-e, logika UI) zaczyna blokować 60 FPS, co bezpośrednio przekłada się na lag i „szarpanie” obiektu AR. Gdy ilość kodu w animate() rośnie, trzeba świadomie wydzielać kosztowne operacje poza pętlę renderującą.

Jeżeli pętla AR jest prosta, a opóźnienie nadal widoczne, winne są zazwyczaj parametry kamery i jakość strumienia wideo, a nie Three.js. Wtedy sens ma zejście do poziomu ustawień rozdzielczości kamery i profilu detekcji markerów.

Konfiguracja i praca z markerami: od Hiro do własnych znaczników

Marker jest najczęściej najsłabszym ogniwem w projektach WebAR. Stabilność detekcji bezpośrednio zależy od jakości wzorca, wydruku oraz warunków oświetleniowych. Rozsądna konfiguracja markerów jest ważniejsza niż jakiekolwiek wizualne fajerwerki w scenie 3D.

Użycie standardowego markera Hiro

Marker Hiro to domyślny wybór w AR.js. Ma wysoki kontrast i prostą geometrię, co przekłada się na niezłą stabilność przy przeciętnym oświetleniu.

Procedura startowa powinna zawierać:

• wydrukowanie markera z pliku dostarczonego przez AR.js (bez skalowania w przeglądarce czy PDF),
• sprawdzenie, czy rozmiar fizyczny jest zgodny z założeniami (np. min. 5–8 cm szerokości),
• umieszczenie markera na matowej, nieodblaskowej powierzchni,
• test wykrywania w kilku odległościach (20–60 cm) przy typowym biurowym oświetleniu.

Punkt kontrolny: jeżeli nawet standardowy Hiro jest wykrywany z trudnością lub tylko pod specyficznym kątem, problem leży głównie w kamerze, oświetleniu lub parametrach AR.js, a nie w samym wzorcu. Migracja na własny marker w takiej sytuacji tylko zamaskuje prawdziwe źródło problemu.

Jeżeli w tych warunkach Hiro działa przewidywalnie, można przejść do bardziej ambitnych wzorców i własnej identyfikacji wizualnej. Dopiero wtedy jest sens inwestować czas w customowe projekty markerów czy druk na lepszych materiałach.

Projektowanie własnego markera: kryteria techniczne, nie estetyczne

Autorski marker kusi brandingiem i „ładnym” wyglądem, ale algorytm detekcji interesuje wyłącznie kontrast i unikalny rozkład kształtów. Powierzchnia wzorca musi zawierać wyraźne przejścia jasne–ciemne, ostre krawędzie i brak dużych jednolitych pól. Symetryczne logotypy, gradienty i cienkie linie obniżają jakość detekcji.

Przed wdrożeniem własnego markera warto przejść przez krótki audyt projektu:

• czy wzorzec ma mocny kontrast (np. czerń na bieli) i czytelne granice figur,
• czy nie dominuje jeden duży, pusty obszar bez szczegółów,
• czy marker nie jest zbyt „okrągły” i symetryczny (algorytm ma problem z ustaleniem orientacji),
• czy rozdzielczość pliku źródłowego jest wystarczająca do ostrego wydruku.

Punkt kontrolny: jeśli atrakcyjny graficznie projekt wymaga podbijania jasności, sztucznego kontrastu i bardzo bliskiego dystansu kamery, z punktu widzenia AR jest to zły marker. W takiej sytuacji lepiej odseparować „ramkę” pod detekcję (czarno-biały wzór) od umieszczonego obok logo niż uparcie stapiać je w jedną formę.

Generowanie i testowanie wzorca w AR.js

Do wygenerowania pliku .patt służą narzędzia dostarczane z AR.js, najczęściej w formie prostego generatora w przeglądarce lub skryptu CLI. Proces wygląda podobnie: wgrywasz obraz referencyjny (np. PNG), określasz parametry i pobierasz wygenerowany plik wzorca.

// Przykładowa konfiguracja własnego markera
arMarker = new THREEx.ArMarkerControls(arContext, camera, {
  type: 'pattern',
  patternUrl: 'assets/markers/moj_marker.patt',
  changeMatrixMode: 'cameraTransformMatrix',
  // warto dodać minimalny próg pewności
  minConfidence: 0.6
});

Po zapisaniu .patt trzeba wykonać serię krótkich testów: wykrywanie z różnych odległości, pod kątem, przy częściowym zasłonięciu i w kilku typach oświetlenia. Sygnał ostrzegawczy: jeśli marker działa dobrze wyłącznie „na biurku autora”, ale zaczyna się gubić na innym monitorze, konferencyjnym stole czy przy świetle dziennym, wzorzec jest za mało odporny na warunki zewnętrzne.

Rozmiar, materiał i warunki pracy markera

Trzy parametry fizyczne mają największy wpływ na stabilność: rozmiar wydruku, rodzaj podłoża i otoczenie świetlne. Zbyt mały marker wymusza bliski dystans kamery, co wzmacnia drgania i zniekształcenia perspektywy. Zbyt duży – utrudnia kadrowanie w małych przestrzeniach. Bezpieczne minimum w typowych projektach to 7–10 cm szerokości roboczej.

W praktyce dobrze sprawdza się druk na matowym papierze lub piance, unikając błyszczących laminatów. Marker powinien mieć sztywną bazę: pofalowany wydruk na kartce A4 leżącej „na oko” prosto daje dużo gorsze wyniki niż ten sam wzór przyklejony do sztywnej planszy. Oświetlenie najlepiej lekko rozproszone; punktowe reflektory i ostre cienie generują duże różnice jasności w obrębie jednego markera.

Punkt kontrolny: jeżeli marker zaczyna znikać, gdy tylko w kadrze pojawi się fragment monitora, błyszczący blat lub mocne źródło światła, zamiast dłubać w kodzie trzeba najpierw ustabilizować fizyczne środowisko pracy. Dopiero po uzyskaniu powtarzalnych warunków testowych można rzetelnie oceniać wpływ pojedynczych parametrów AR.js.

Dla projektów długoterminowych opłaca się przygotować prostą „procedurę odbioru” fizycznej scenografii: zawsze ten sam typ papieru, ten sam format, przykładowy scenariusz testowy (kąt nachylenia, odległość, zmiana źródła światła). To bardziej lista kontrolna niż dokumentacja. Jeśli instalacja ma trafić na targi, do muzeum czy przestrzeni retail, sens ma nawet krótka instrukcja dla obsługi: jak ustawić marker, jak go czyścić, czego unikać w otoczeniu (szkło, LED-y skierowane w dół, podświetlane reklamy).

Punkt kontrolny: jeśli każda instalacja AR „żyje własnym życiem” i przed każdym wdrożeniem trzeba ręcznie korygować parametry detekcji, problem zwykle leży w braku standaryzacji fizycznych markerów i ich otoczenia. Gdy nośnik, format i oświetlenie są powtarzalne, te same ustawienia AR.js działają przewidywalnie w wielu lokalizacjach, a debugowanie wraca na poziom kodu zamiast improwizacji w realu.

Wielomarkowość, aliasing i odporność na tło

Przy kilku markerach w jednej scenie trzeba rozwiązać trzy problemy: rozróżnialność wzorców, kolejność ich obsługi i zachowanie przy ich częściowym nałożeniu. Najpierw selekcja: wzorce nie mogą być do siebie zbyt podobne pod względem układu kontrastów. Dwa markery zbliżone graficznie zwiększają ryzyko fałszywych detekcji lub „przeskakiwania” obiektu między nimi.

Kolejny krok to zarządzanie ich życiem w kodzie. Zamiast rozpraszać logikę po wielu ArMarkerControls, lepiej utrzymywać jednolity rejestr znaczników i jednolitą politykę reagowania: który marker jest priorytetowy, co się dzieje przy jednoczesnym wykryciu dwóch, kiedy obiekty mają znikać, a kiedy tylko „zamrażać” swoją pozycję. Sygnał ostrzegawczy: jeżeli przy szybkim ruchu kamery modele 3D „teleportują” się między markerami, trzeba odbudować tę logikę, a nie kręcić suwakami czułości.

Osobny temat to tło. W środowiskach bogatych wizualnie (plakaty, wzorzyste podłogi, kolorowe półki) marker powinien mieć wyraźny margines „ciszy wizualnej” – obszar bez agresywnych kształtów tuż wokół. W praktyce działa zwykła biała obwódka, która separuje wzorzec od otoczenia. Jeżeli pracujesz w retailu lub eventach, minimum to test na realnej aranżacji, a nie tylko na czystym biurku.

Punkt kontrolny: jeżeli pojedynczy marker jest stabilny, a problemy pojawiają się dopiero po dodaniu kolejnych, trzeba przejść checklistę: podobieństwo wzorców, polityka priorytetów, margines bezpieczeństwa w projekcie graficznym i testy na docelowym tle. Dopiero po przejściu tych czterech punktów ma sens korekta parametrów detekcji.

Strategia awaryjna: co zrobić, gdy marker nie jest opcją

Zdarzają się konteksty, gdzie klasyczny wydrukowany marker nie przejdzie: wymogi brandingu, ograniczenia przestrzeni, sprzeciw klienta wobec „czarno-białej ramki”. Zamiast na siłę wciskać słaby, słabo widoczny znacznik, lepiej mieć zaplanowaną strategię B. Dostępne są co najmniej trzy kierunki: markerless (detekcja płaszczyzn, obrazów, twarzy), pół-markery (dyskretny wzór wpisany w grafikę przestrzeni) oraz hybrydy, gdzie marker pełni funkcję jedynie w fazie kalibracji.

AR.js skupia się na markerach, ale nic nie stoi na przeszkodzie, by w tym samym projekcie delegować inne tryby detekcji do osobnych bibliotek lub warstw. Praktyczne rozwiązanie: scenariusz startuje od pewnego, poprawnie zaprojektowanego markera (szybka, niezawodna inicjalizacja), a po ustabilizowaniu kamery aplikacja przechodzi do mniej zależnych od wzorca efektów (np. nałożenie interfejsu zakotwiczonego w przestrzeni ekranu). Jeśli AR ma funkcjonować w niekontrolowanych warunkach, bezpiecznikiem powinien być tryb degradacji: sensowna wersja „bez AR”, a nie komunikat o błędzie.

Punkt kontrolny: jeżeli projekt jest zakładnikiem „czystego brandingu”, a równocześnie wymaga stabilnej, technicznie przewidywalnej AR, decyzja powinna być binarna. Albo klient akceptuje kontrolowany, czytelny marker (także w formie ukrytego pół-markera), albo zakres funkcji AR jest zredukowany do trybu, który nie udaje pełnego śledzenia przestrzeni. Wszystko pomiędzy to proszenie się o niepowtarzalne błędy i niemożliwy do utrzymania kod.

Integracja z Three.js na poziomie eksperta: światło, materiały, modele 3D

Po opanowaniu stabilnej detekcji markerów największy skok jakościowy daje świadome wykorzystanie Three.js. Zamiast traktować scenę jak demo z przykładów, trzeba ją zaprojektować jak produkt: z ograniczonym budżetem polygonów, przemyślanym oświetleniem i materiałami dostosowanymi do realnych warunków kamery. Minimum to przyjęcie założenia, że pracujesz w środowisku o wysokim szumie, kompresji obrazu i nieprzewidywalnym balansie bieli – wszystko, co zadziała w takich warunkach, będzie wyglądało stabilnie także w idealnym studio.

Praktyczne podejście zaczyna się od oświetlenia: jedna lub dwie dobrze ustawione lampy (np. kombinacja HemisphereLight + DirectionalLight) sprawdzają się lepiej niż rozbudowana siatka źródeł światła z włączonymi cieniami wszędzie. Sygnał ostrzegawczy: jeśli pierwszym odruchem jest włączanie cieni na każdym obiekcie, zanim ocenisz płynność na docelowym urządzeniu, projekt zmierza w stronę slajdów zamiast interaktywnej AR. Konfigurację świateł warto przycinać pod kątem liczby draw calli i stabilności klatek przy ruchu kamery, a nie tylko efektu „wow” w jednym, nieruchomym ujęciu.

Materiały wymagają osobnego audytu. Na streamie z kamery dominują zmienne odbłyski, szumy i artefakty kompresji, dlatego agresywnie refleksyjne powierzchnie (wysoki metalness + niski roughness) najczęściej się nie bronią. Bezpieczniej działa lekko zmatowiony, czytelny materiał, który zachowuje kształt obiektu nawet na słabej jakości obrazie. Jeżeli model ma imitować istniejący fizycznie produkt, lepszy efekt daje solidna tekstura albedo z dobrze zaprojektowaną kolorystyką niż ściganie się na „fotorealistyczne” highlighty. Punkt kontrolny: jeśli model traci czytelność przy zmniejszeniu okna podglądu do wielkości telefonu, materiały są zbyt zależne od subtelnych efektów świetlnych.

Modele 3D trzeba traktować jak zasoby w aplikacji webowej, nie jak pliki z portfolio grafika. Zanim trafią do AR, powinny przejść standaryzację: format (glTF/GLB jako domyślny wybór), limit wielkości pliku, jednolita skala i pivot (punkt obrotu). Każdy dodatkowy megabajt i każdy zbędny mesh to realne opóźnienie przy starcie sceny, które użytkownik odczuje jak „nie działa”. Dobrą praktyką jest wewnętrzny „przegląd modeli”: krótka lista parametrów do odhaczenia – liczba trójkątów, liczba materiałów, użycie tekstur, obecność zbędnych animacji. Sygnał ostrzegawczy: gdy przy kolejnych wydaniach trzeba ręcznie korygować pozycję tego samego typu modelu, problemem nie jest AR.js, tylko brak standardu przygotowania zasobów.

Three.js daje też narzędzia do kontrolowania wrażeń użytkownika przy utracie śledzenia. Zamiast nagłego zniknięcia obiektu można wprowadzić krótki fade-out, „zamrożenie” pozycji lub płynne przejście do wariantu 2D zakotwiczonego w UI. Ta warstwa scenariusza decyduje, czy użytkownik odbiera AR jako „glitchującą technologię”, czy jako środowisko, które przewidywalnie reaguje na gorsze warunki. Punkt kontrolny: jeżeli każdy drobny skok markera kończy się nerwowym miganiem modelu, trzeba wprowadzić bufor czasowy i łagodniejsze przejścia, zamiast zaostrzać progi detekcji.

Optymalizacja wydajności: budżet GPU, CPU i sieci

AR w przeglądarce jest jednocześnie klientem kamery, dekoderem wideo, modułem detekcji markerów i silnikiem 3D. Każdy zbędny „lukier” w kodzie szybko zamienia się w drgania obrazu, spadki FPS i opóźnienia w reakcji na ruch markera. Projekt powinien mieć jasno zdefiniowany budżet wydajności: ile trójkątów, ile draw calli, jaka maksymalna waga zasobów ładowanych na starcie. Bez takich widełek zespół graficzny i deweloperzy zaczynają „po trochu” dokładać detale, aż pierwsze testy na starszym telefonie kończą się artefaktami i szarpaniem ruchu.

W praktyce pierwszym filtrem jest urządzenie docelowe. Jeśli scenariusz zakłada działanie na średniej klasy telefonach z Androidem sprzed kilku lat, limit powinien być agresywny: jedna scena, ograniczona liczba dynamicznych świateł, proste shadery i maksymalnie kilka modeli 3D aktywnych jednocześnie. W środowiskach B2B (np. instalacje na dedykowanych tabletach) budżet można zwiększyć, ale nadal z rezerwą – wąskim gardłem bywa nie tylko GPU, lecz także przepustowość JS na stronie obciążonej innymi skryptami.

Zanim zaczną się eksperymenty z materiałami, trzeba zmierzyć „gołe” środowisko: AR.js + jedna prosta siatka z podstawowym materiałem i minimalną liczbą świateł. Ten stan to punkt odniesienia. Każdy kolejny element (nowy model, tekstura w wysokiej rozdzielczości, dodatkowy post-processing) powinien być testowany z porównaniem do tej bazy. Sygnał ostrzegawczy: jeśli po dodaniu jednego modelu złożoność sceny rośnie o rząd wielkości (np. kilkaset tysięcy trójkątów), a zespół tłumaczy to „stylówą” lub „wizją artystyczną”, trzeba wrócić do liczb i jasno określonych limitów.

Punkt kontrolny: jeżeli płynność sceny AR zależy od tego, czy użytkownik przypadkiem nie ma otwartych kilku innych kart z ciężkimi aplikacjami, budżet wydajności jest fikcyjny. Zestaw minimalny to stabilny FPS na typowym urządzeniu docelowym, ze średnim obciążeniem przeglądarki oraz nieidealnym zasięgiem sieci – dopiero wtedy można mówić o przewidywalnym zachowaniu produkcyjnym.

Architektura kodu: rozdzielenie warstw i kontrola odpowiedzialności

Im bardziej scenariusz AR się rozrasta, tym bardziej opłaca się myślenie warstwami. Inna odpowiedzialność leży po stronie detekcji markera, inna przy zarządzaniu sceną 3D, a jeszcze inna w UI i logice biznesowej. Gdy wszystko ląduje w jednym pliku z kilkoma setkami linii, debugowanie w warunkach produkcyjnych (na telefonie, na evencie) zamienia się w zgadywanie. Efekt: prowizoryczne „if-y” rozrzucone po kodzie, które w kolejnym wydaniu zaczynają się wzajemnie wykluczać.

Bezpieczny wzorzec to trzy wyraźne moduły:

• warstwa AR.js – inicjalizacja kamery, konfiguracja detekcji, obsługa zdarzeń związanych z markerami;
• warstwa Three.js – tworzenie i konfiguracja sceny, świateł, modeli, animacji;
• warstwa aplikacyjna – logika interakcji, zmiany stanów, komunikacja z backendem.

Dzięki takiemu podziałowi można np. wymienić bibliotekę detekcji lub przebudować interfejs, nie dotykając geometrii sceny. Sygnał ostrzegawczy: jeśli zdarzenia typu markerFound bezpośrednio manipulują DOM-em, zmieniają stan aplikacji i w tym samym miejscu obracają modele 3D, architektura wymaga pilnego uporządkowania.

Punkt kontrolny: jeżeli analiza pojedynczego błędu (np. model nie znika po utracie markera) wymaga skakania między kilkoma losowymi fragmentami kodu, moduły są sprzężone za mocno. Po rozdzieleniu odpowiedzialności typowe problemy sprowadzają się do jednego z trzech obszarów (AR.js, Three.js, logika), a czas naprawy skraca się z godzin do minut.

Interakcje użytkownika: gesty, kolizje i scenariusze UI

AR na stronie HTML rzadko kończy się na pasywnym oglądaniu modelu. Zwykle pojawia się oczekiwanie: „użytkownik ma coś kliknąć”, „przeciągnąć”, „zmienić wariant produktu”. Problem w tym, że kamera zajmuje ekran, a przestrzeń interfejsu jest ograniczona. Losowe dodawanie przycisków i gestów prowadzi do chaosu: część akcji nie działa, część koliduje z gestami systemowymi (np. cofanie, przełączanie aplikacji), a część zakrywa sam model.

Podstawową decyzją jest rozdział interakcji ekranowych i przestrzennych. Jeżeli celem jest dopasowanie produktu do otoczenia (np. mebel, sprzęt RTV), dominujące powinny być gesty 2D na ekranie: pinch-zoom, obrót dwoma palcami, przesunięcie modelu po płaszczyźnie markera. Jeśli scenariusz zakłada „zabawkę AR” lub grę, więcej sensu ma interakcja oparta na ruchu kamery i zmiennych odległościach od markera, a UI sprowadza się do prostych przełączników trybów.

Dobrym testem jest nagranie wideo z użytkownikiem, który pierwszy raz korzysta z prototypu, bez instrukcji. Jeżeli pierwsze pytanie brzmi „gdzie mam kliknąć?” albo „dlaczego to się rusza, gdy przesuwam palcem?”, projekt nie ma czytelnej metafory interakcji. Sygnał ostrzegawczy: każdy nowy feature wymaga dodatkowego przycisku na ekranie, który ląduje gdzieś nad obrazem z kamery, zasłaniając część sceny AR.

Punkt kontrolny: jeśli na małym ekranie da się jednocześnie wygodnie manipulować modelem 3D i obserwować jego relację z fizycznym otoczeniem, interfejs jest blisko optimum. Jeśli użytkownik musi „walczyć z UI”, żeby w ogóle zobaczyć model na markerze, trzeba uprościć gesty, zredukować liczbę przycisków i jasno określić priorytet scenariusza.

Integracja z backendem: dane, konfiguracja i analityka

AR.js i Three.js działają po stronie klienta, ale rzadko są wyspą. W realnych projektach trzeba pobrać konfigurację sceny, modele produktów, dane o kampanii, wyniki interakcji użytkownika. Gdy wszystko to miesza się w jednym JSON-ie „od grafika”, łatwo o sytuację, w której drobna zmiana zasobu powoduje awarię całej sceny. Kluczem jest rozdzielenie danych technicznych (geometria, materiały) od biznesowych (id produktu, treść opisów, parametry personalizacji).

Praktyczny podział wygląda tak:

• pliki modeli 3D (GLB/glTF) utrzymywane w repo/asset store z własnym cyklem kontroli jakości;
• lekka konfiguracja sceny (pozycje, skale, warianty) pobierana z backendu lub plików statycznych;
• dane analityczne (zdarzenia, czasy interakcji) wysyłane do systemu zewnętrznego, bez wpływu na logikę AR w czasie rzeczywistym.

Dzięki temu scenę można częściowo rekonfigurować bez przebudowy frontendu – np. podmienić model wariantu kolorystycznego lub zmienić komunikaty tekstowe. Sygnał ostrzegawczy: jeśli analityka wysyłana jest z wnętrza pętli renderowania lub callbacków AR.js uruchamianych kilkadziesiąt razy na sekundę, obciążenie sieci i CPU zaczyna realnie psuć doświadczenie AR.

Punkt kontrolny: jeżeli odłączenie backendu (np. przejście w tryb offline) zmienia AR w bezużyteczny szary ekran z błędem, a nie w ograniczoną, ale działającą wersję sceny, integracja jest zbyt ciasna. Minimalny standard to lokalna konfiguracja awaryjna i bezpieczne kolejkowanie zdarzeń do wysyłki po powrocie połączenia.

Testy międzyprzeglądarkowe i różnice platformowe

To, że AR.js działa w Chrome na laptopie, nie oznacza, że zachowa się tak samo w mobilnym Safari czy w przeglądarce OEM na Androidzie. Różnice obejmują dostęp do kamery, zarządzanie uprawnieniami, strategie oszczędzania energii, a nawet sposób renderowania wideo z kamery na teksturę. Ignorowanie tych różnic kończy się zgłoszeniami typu „u klienta nie działa”, bez możliwości szybkiej reprodukcji błędu.

Minimum to macierz testowa: kilka realnych urządzeń reprezentujących popularne kombinacje system/przeglądarka (Android/Chrome, Android przeglądarka producenta, iOS/Safari, iOS/Chrome). Symulatory i tryby devtools pomagają, ale nie wychwycą np. agresywnego ubijania procesów w tle czy zmian jakości streamu przy słabym zasięgu sieci komórkowej. Przy instalacjach eventowych należy uwzględnić także tryb kioskowy i blokady systemowe.

Przygotowanie sceny testowej z wyraźnym markerem, prostym modelem i licznikami FPS/logami w UI skraca czas diagnostyki. Jeżeli w takim minimalnym środowisku pojawiają się różnice między przeglądarkami (np. jedna gubi marker przy tym samym oświetleniu, druga nie), można je przypisać do implementacji WebRTC/WebGL, a nie do własnego kodu. Sygnał ostrzegawczy: poprawki „pod konkretny telefon” wprowadzane na ślepo, bez zrozumienia różnicy w stosie technologii.

Punkt kontrolny: jeśli po kilku rundach testów większość problemów da się odtworzyć w kontrolowanej scenie testowej, projekt jest pod kontrolą. Jeżeli błędy występują tylko „u klienta”, a zespół nie ma procedury ich reprodukcji, trzeba zainwestować w lepszy zestaw urządzeń testowych i ustandaryzowaną dokumentację przypadków.

Dostępność i ergonomia: AR jako część większego doświadczenia

AR w przeglądarce często bywa traktowana jak „efekt specjalny”, który działa albo nie. Taka perspektywa ignoruje użytkowników, którzy z różnych powodów nie mogą lub nie chcą korzystać z pełnej funkcjonalności: słabsze urządzenia, ograniczenia wzroku, brak zgody na dostęp do kamery. Jeśli scenariusz krytycznie zależy od AR, każda z tych sytuacji kończy się ślepą uliczką – stroną, z której nie da się skorzystać inaczej niż przez rezygnację.

Minimalny zestaw zabezpieczeń obejmuje:

• czytelny komunikat i alternatywny tryb działania dla użytkowników bez dostępu do kamery;
• konsekwentne użycie kontrastów kolorystycznych i rozmiarów fontów w elementach UI nakładanych na obraz z kamery;
• scenariusz „bez AR”, który nadal dostarcza kluczowe informacje lub funkcje (np. konfigurator 3D bez komponentu przestrzennego).

W projektach komercyjnych często wystarczy prosty fallback: ten sam model 3D prezentowany na neutralnym tle, sterowany tymi samymi gestami. Użytkownik bez kamery nie „zobaczy produktu w swoim otoczeniu”, ale nadal może ocenić kształt, kolor i szczegóły. Sygnał ostrzegawczy: jeśli ścieżka bez AR prowadzi do strony z komunikatem „funkcja niedostępna” albo wymaga zamknięcia całej aplikacji, produkt jest zamknięty na część odbiorców.

Punkt kontrolny: jeżeli przepięcie z trybu AR do trybu klasycznego 3D jest płynne, nie wymaga przeładowania strony i nie gubi stanu użytkownika (wybrany wariant, język, krok procesu), doświadczenie jako całość ma większe szanse obronić się w realnym ruchu. W przeciwnym razie każda awaria kamery lub blokada uprawnień kończy się utratą użytkownika.

Bezpieczeństwo i prywatność: kamera, zgody i minimalizacja danych

Korzystanie z AR w przeglądarce to w praktyce prośba o dostęp do kamery. Na poziomie użytkownika jest to silny sygnał ryzyka – szczególnie na urządzeniach prywatnych. Z punktu widzenia twórcy aplikacji trzeba jasno określić, jakie dane są realnie potrzebne i co się z nimi dzieje. W większości projektów AR opartych na AR.js i Three.js obraz z kamery nigdy nie powinien opuszczać urządzenia – detekcja odbywa się lokalnie, a do serwera trafiają co najwyżej zdarzenia interakcji.

Elementy, które wymagają audytu:

• czy jakakolwiek forma streamu wideo jest wysyłana poza urządzenie – jeśli tak, w jakim celu i na jakich zasadach;
• czy aplikacja prawidłowo reaguje na odmowę dostępu do kamery (czytelny komunikat, tryb alternatywny, brak crashy);
• czy biblioteki zewnętrzne (analityka, reklamy) nie próbują równolegle korzystać z kamery lub nie wstrzykują własnych uprawnień.

W kontekście regulacji (RODO/GDPR i lokalne przepisy) brak jednoznacznej informacji o tym, co dzieje się z obrazem z kamery, jest poważnym obciążeniem. Sygnał ostrzegawczy: opisy aplikacji w sklepach i na stronach marketingowych, które chwalą się „analizą zachowania użytkownika w otoczeniu AR”, bez klarownego wyjaśnienia, czy i jak przetwarzane jest wideo.

Punkt kontrolny: jeżeli po odłączeniu sieci aplikacja AR nadal działa poprawnie (poza funkcjami stricte sieciowymi), a logi sieciowe nie wykazują wysyłania klatek wideo, polityka minimalizacji danych jest respektowana. Gdy cała logika AR przestaje działać bez połączenia, trzeba dokładnie sprawdzić, które komponenty uzależniły się od zewnętrznych usług.

Utrzymanie i rozwój: wersjonowanie, regresje i standardy zespołowe

Prototyp AR często powstaje w kilka dni. Problem zaczyna się w momencie, gdy „szybki proof of concept” ma żyć miesiącami, być aktualizowany o nowe modele, nowe markery, nowe kampanie. Bez wersjonowania scen, zasobów i konfiguracji każdy update grozi regresją: drobna zmiana modelu poprawia jeden ekran, ale psuje detekcję na innym nośniku lub w innym kraju. W praktyce bez twardych standardów cały projekt „broni się” tylko pamięcią jednego dewelopera.

Minimum to:

• repozytorium kodu z czytelnymi tagami wydania powiązanymi z kampaniami/instalacjami;

• oddzielne wersjonowanie zasobów (modele, tekstury, shadery, markery) z jasną mapą: który plik jest używany w której scenie i w jakim wydaniu;
• procedura „twardego zamrożenia” stabilnej wersji na czas kampanii lub wdrożenia eventowego, z zakazem wprowadzania ad hoc zmian na produkcji;
• opisany proces aktualizacji bibliotek (AR.js, Three.js, loaderów modeli) wraz z listą testów regresyjnych, które trzeba uruchomić po podbiciu wersji.

Przy kolejnych iteracjach projektu kluczowe stają się sceny referencyjne. To małe, celowo proste konfiguracje (np. jeden znany marker, jeden prosty model, minimalny UI), które służą jako „linijka pomiarowa” przy każdej większej zmianie. Jeżeli po aktualizacji Three.js model w scenie referencyjnej zaczyna migotać albo marker gubi się częściej, wiadomo, że problem jest w warstwie technologicznej, a nie w złożonej logice biznesowej. Sygnał ostrzegawczy: jedynym środowiskiem testowym jest bieżąca produkcja z kompletnym zestawem funkcji.

Przydatne jest także twarde rozdzielenie ról: kto może modyfikować kod logiki AR, kto podmienia modele, kto zarządza markerami i ich fizycznymi nośnikami. W małych zespołach będzie to często ta sama osoba, ale nawet wtedy dobrze mieć formalne „checklisty odbioru”: przed wydaniem kampanii ktoś musi sprawdzić zgodność markerów drukowanych z plikami w repozytorium, a także zgodność nazw zasobów z konfiguracją scen. Punkt kontrolny: jeżeli nowy model lub nowy marker może trafić na produkcję bez żadnego przeglądu i bez wpisu w changelogu, ryzyko trudnej do odtworzenia regresji jest wysokie.

Na poziomie standardów kodu i konfiguracji sens ma prosty, ale twardy minimalizm. Brakujące komentarze przy niestandardowych shaderach, „magiczne” wartości progów detekcji wklejone w kilku miejscach czy rozjechane konwencje nazewnicze w zasobach (np. model_final_v2_reallyFinal.gltf) prowadzą do sytuacji, w której po kilku miesiącach zespół boi się dotknąć starej sceny. Odpowiednio wcześnie ustalone zasady – gdzie trzymamy markery, jak nazywamy modele, jak opisujemy zależności między scenami – sprawiają, że AR na stronie HTML staje się projektem, a nie jednorazowym „efektem specjalnym”. Jeżeli po pół roku można bez stresu wrócić do pierwszej kampanii, odtworzyć ją z repozytorium i uruchomić w trybie testowym, standard utrzymania jest na akceptowalnym poziomie.

Jeżeli prosta scena AR z jedną kamerą, jednym markerem i jednym modelem da się uruchomić lokalnie w przeglądarce, z wyłączoną siecią, na więcej niż jednym urządzeniu – fundament jest. Rozszerzona rzeczywistość w zwykłym HTML’u przestaje być wtedy ryzykownym eksperymentem, a staje się powtarzalnym komponentem produktu, który można rozwijać, audytować i spokojnie podpinać pod realne cele biznesowe.

Checklisty wdrożeniowe: od prototypu lokalnego do produkcji

Sam fakt, że scena AR działa lokalnie na jednym laptopie, nie oznacza, że nadaje się do produkcji. Przejście z trybu „demo na konferencji” do publicznej strony HTML wymaga serii twardych kontroli: konfiguracji serwera, certyfikatów, buforowania zasobów, a także procedur reagowania na awarie. AR.js i Three.js same z siebie są stabilne – problemy pojawiają się na styku z infrastrukturą i procesem wdrożeń.

Przy przejściu z prototypu do produkcji minimum obejmuje trzy obszary: hosting i HTTPS, dystrybucję zasobów (modele, tekstury, skrypty) oraz obsługę wersji w środowiskach (dev/stage/production).

Hosting i HTTPS: techniczne warunki działania AR.js

AR.js korzysta z dostępu do kamery poprzez API przeglądarki oparte na HTTPS lub pochodzącym z localhost. Prototyp bezproblemowo działa na serwerze deweloperskim, ale po wrzuceniu na źle skonfigurowany hosting efekt jest prosty: brak dostępu do kamery i mylący komunikat „brak wsparcia urządzenia”.

Podstawowe kryteria dla środowiska produkcyjnego:

• certyfikat HTTPS poprawnie zainstalowany i aktualny dla wszystkich subdomen wykorzystywanych w projekcie;
• brak mieszanych treści (mixed content) – wszystkie skrypty i zasoby ładowane również po HTTPS;
• odpowiednio ustawione nagłówki CORS dla zasobów 3D, jeśli są serwowane z innej domeny niż główna aplikacja;
• kompresja gzip/brotli włączona dla JavaScript, modeli i tekstur, ale bez łamania nagłówków typów MIME.

Sygnał ostrzegawczy: scena AR działa tylko w trybie „bezpiecznego połączenia” na desktopie, ale na telefonie użytkownik widzi komunikat o braku uprawnień do kamery mimo zaakceptowania zgody. W większości przypadków źródło problemu leży w niedomkniętej konfiguracji HTTPS lub mieszanym kontencie.

Punkt kontrolny: jeżeli ten sam build sceny AR, uruchomiony na localhost i na docelowej domenie produkcyjnej, ma identyczne zachowanie uprawnień do kamery oraz brak ostrzeżeń w konsoli o mieszanych treściach, fundament hostingowy jest poprawnie ułożony.

Dystrybucja zasobów: modele, tekstury, shadery

AR na zwykłej stronie HTML najczęściej rozbija się nie o logikę, lecz o ciężar i strukturę zasobów. Zbyt duży model 3D lub nieprzemyślane tekstury skutkują długim ładowaniem, rozgrzewaniem GPU i spadkami FPS. W wielu projektach pierwsze sekundy po uruchomieniu sceny decydują o tym, czy użytkownik zostanie czy zamknie kartę.

Przygotowując zasoby do produkcji, warto przejść przez kontrolowaną listę:

• format modeli: preferencja dla glTF/GLB, unikanie formatów pośrednich (OBJ, FBX) wprost w przeglądarce;
• optymalizacja: redukcja liczby polygonów do poziomu akceptowalnego wizualnie na mobilu, a nie na monitorze 4K;
• tekstury: powtarzalne rozdzielczości (np. wielokrotności 512), kompresje (KTX2 basis) tam, gdzie przeglądarka na to pozwala;
• podział scen: unikanie jednego dużego modelu „zawierającego wszystko” na rzecz modularnego ładowania tylko wymaganych elementów;
• cache: korzystanie z nagłówków Cache-Control oraz wersjonowania plików w nazwach (tzw. cache busting) zamiast ręcznego „odświeżania” u klienta.

Sygnał ostrzegawczy: pierwsze uruchomienie sceny na LTE trwa kilkanaście sekund, a użytkownicy raportują „czarny ekran” zanim cokolwiek się pojawi. Zwykle oznacza to zbyt ciężkie modele lub brak loading screena, który przejrzyście komunikuje postęp.

Punkt kontrolny: jeżeli w zewnętrznym profilerze sieci (DevTools, Lighthouse) pełne pobranie zasobów dla jednej sceny AR na mobilnym łączu mieści się w akceptowalnym budżecie (np. kilka MB), a interfejs pokazuje użytkownikowi stan ładowania, projekt jest bliżej realnego wykorzystania niż efektowna, ale „ciężka” prezentacja.

Środowiska, branche i migracja scen

W projektach, gdzie AR jest jedną z wielu funkcji, wdrożenia często lecą jednym strumieniem: ta sama gałąź kodu obsługuje nowe moduły CMS, poprawki SEO i sceny AR. W efekcie każda zmiana poza AR potencjalnie wprowadza regresję do warstwy Three.js/AR.js, a odpowiedzialność rozmywa się po całym zespole.

Sprawdzony model to wyodrębnienie logicznego „pakietu AR” wraz z własnym cyklem wersjonowania i testów:

• dedykowana gałąź lub monorepo z wydzielonym pakietem (np. @app/ar-module) aktualizowanym niezależnie od reszty frontendu;
• osobne środowisko testowe (np. ar-stage.example.com) z tymi samymi nagłówkami i HTTPS co produkcja;
• procedura migracji scen: każda nowa scena lub zmiana konfiguracji markerów przechodzi przez scenę referencyjną i checklistę urządzeń.

Sygnał ostrzegawczy: zespół nie jest w stanie odpowiedzieć, jakie wydanie sceny AR jest obecnie na produkcji, ani odtworzyć stanu sprzed ostatniej kampanii. W takiej sytuacji każdy hotfix jest ruletką.

Punkt kontrolny: jeżeli dla dowolnego dnia kampanii można wskazać tag w repozytorium, listę zmian w scenach AR oraz powiązane markery i modele, a także odtworzyć tę wersję na stage w ciągu godzin, proces wersjonowania i środowisk jest na minimalnie bezpiecznym poziomie.

Standardy projektowania scen i interakcji w AR

Nawet najlepiej zoptymalizowana technicznie scena AR zawiedzie, jeśli użytkownik nie zrozumie, co ma zrobić. Strona HTML z AR nie jest samodzielną aplikacją mobilną; użytkownik wchodzi tam z przeglądarki, często z innym celem niż sama zabawa AR. Projektowanie interakcji musi łączyć prostotę obsługi z ograniczeniami realnego otoczenia: odbicia światła, hałas w tle, ograniczona przestrzeń do poruszania się.

Nawigacja, onboarding i informacja zwrotna

Pierwszy kontakt z modułem AR decyduje o tym, czy użytkownik przejdzie proces do końca. Krótkie, jednoznaczne instrukcje oraz natychmiastowa informacja zwrotna o stanie (szukanie markera, wykryto marker, błąd) są ważniejsze niż wizualne fajerwerki.

W projektowaniu onboarding’u do AR warto przejść przez kilka pytań:

• czy użytkownik wie, że potrzebny jest marker lub płaska powierzchnia, zanim przyzna dostęp do kamery;
• czy komunikaty są dostosowane do lokalizacji (język, alfabet) oraz warunków użycia (np. event, dom, sklep);
• czy w każdym momencie można łatwo wrócić do „normalnej” strony bez utraty kluczowych informacji;
• czy stany przejściowe są jasno oznaczone (np. animacja „szukam markera”, zmiana koloru UI po wykryciu).

Sygnał ostrzegawczy: użytkownicy pytają wprost „co mam z tym zrobić?” podczas testów użyteczności, choć scena technicznie działa poprawnie. Najczęściej oznacza to brak wystarczającej warstwy komunikacji, nie problem z samym silnikiem AR.

Punkt kontrolny: jeżeli osoba spoza zespołu, mająca jedynie link i ewentualnie wydrukowany marker, jest w stanie w ciągu kilkudziesięciu sekund samodzielnie uruchomić scenę i wykonać podstawową interakcję bez podpowiedzi, projektowanie onboarding’u jest na dobrym torze.

UI na obrazie z kamery: minimalizm i czytelność

Nakładanie UI na obraz z kamery prowokuje do efektownych, półprzezroczystych paneli, gradientów, neonów. W praktyce obraz z kamery ma nieprzewidywalne tło, więc wszelkie półcienie i subtelne kolory zwykle kończą jako nieczytelna plama. Szczególnie problematyczne są sceny uruchamiane na zewnątrz, w ostrym słońcu, oraz w sklepach z mocnym oświetleniem punktowym.

Dobrą praktyką jest traktowanie UI jak warstwy nadrzędnej nad kamerą, a nie części „świata AR”:

• wysoki kontrast elementów, wyraźne obrysy i cienie odcinające UI od obrazu tła;
• stała pozycja podstawowych kontrolek (np. przycisk wyjścia, przełącznik trybu) – bez „skakania” wraz z rotacją kamery;
• maksymalnie dwa–trzy poziomy hierarchii interfejsu, brak wielostronicowych menu chowających się za ikonami;
• precyzyjne hitboxy elementów dotykowych i testy na mniejszych ekranach (4–5 cali), nie tylko flagowcach.

Sygnał ostrzegawczy: w nagraniach z testów użytkownicy wielokrotnie „nie trafiają” w przyciski, zakrywają palcem marker lub zasłaniają część sceny próbując odnaleźć ikonę. Wtedy problem leży w projekcie UI i ergonomii dotyku, a nie w samej bibliotece AR.js.

Punkt kontrolny: jeśli na urządzeniach o różnych rozdzielczościach UI pozostaje czytelny, a podstawowe interakcje są możliwe jedną ręką, bez zasłaniania kamery i markera, warstwa interfejsu jest wystarczająco stabilna do realnego ruchu.

Scenariusze interakcji: gesty, dotyk, zdarzenia przestrzenne

AR.js z Three.js pozwalają traktować obiekty 3D jak elementy interaktywne: można je obracać, skalować, naciskać, zmieniać ich stan w reakcji na wykrycie lub utratę markera. Problem pojawia się przy zbyt ambitnym scenariuszu: zbyt wiele gestów, niejednoznaczne reakcje, kolizje z natywnymi gestami przeglądarki.

Przed wdrożeniem rozbudowanych interakcji warto przejść przez prostą sekwencję pytań:

• czy dla danego celu biznesowego potrzebny jest pełen zestaw gestów (rotacja, pinch-zoom, drag), czy wystarczy jeden dominujący;
• czy gesty nie kolidują z przewijaniem strony, gestem „wstecz” systemu lub nawigacją w przeglądarce;
• czy w przypadku wielokrotnych kliknięć/gestów scena zachowuje się przewidywalnie (brak „nawarstwiania” animacji, powtarzających się triggerów);
• czy istnieje prosty reset sceny (powrót do stanu początkowego) bez przeładowania strony.

Sygnał ostrzegawczy: użytkownicy przypadkowo uruchamiają gest powiększenia przeglądarki zamiast skalowania modelu, lub tracą scenę AR przesuwając ją poza widok podczas przewijania. W takiej sytuacji potrzebne jest ograniczenie gestów lub ich przemapowanie na bardziej jednoznaczne akcje.

Punkt kontrolny: jeżeli logi błędów nie pokazują lawiny nieobsłużonych zdarzeń wejścia (touch/wheel), a nagrania z testów wskazują, że użytkownicy bez instrukcji są w stanie zrozumieć, jak manipulować obiektem 3D, zestaw interakcji jest adekwatny do kontekstu.

Zaawansowana analityka i pomiar skuteczności scen AR

AR na stronie HTML bywa traktowana jak „dodatkowa atrakcja”, której nikt nie mierzy. To prosty sposób na marnowanie budżetu – bez danych nie można ocenić, czy sceny AR realizują cele, czy są tylko kosztownym eksperymentem. Integracja AR.js i Three.js z systemami analitycznymi wymaga ostrożności: nie wolno przesadzić z ilością danych, a jednocześnie trzeba uchwycić kluczowe zdarzenia.

Definicja zdarzeń: co faktycznie mierzyć

Zamiast wysyłać „wszystko, co się da”, lepiej zdefiniować kilka jednoznacznych punktów pomiaru. W typowej scenie AR przydatne są:

• wejścia do modułu AR (otwarcie widoku z kamerą);
• przyznanie oraz odmowa zgody na dostęp do kamery;
• pierwsze wykrycie markera lub stabilne utrzymanie go przez określony czas;
• kluczowe interakcje z modelem (np. zmiana wariantu, włączenie animacji, kliknięcie hotspotu informacyjnego);
• czas aktywnej sesji AR (od startu do zamknięcia widoku lub przejścia do innej sekcji strony).

Sygnał ostrzegawczy: w analityce widać wiele wejść na stronę z AR, ale niemal brak zdarzeń „wykryto marker” lub „interakcja z modelem”. To wyraźny sygnał problemów z onboardingiem, jakością markerów lub wydajnością na pierwszych sekundach działania.

Punkt kontrolny: jeśli na podstawie kilku kluczowych zdarzeń da się opisać ścieżkę użytkownika (wejście → zgoda → wykrycie markera → interakcja → wyjście) oraz porównać ją między kampaniami lub wersjami scen, warstwa pomiaru jest wystarczająco precyzyjna do decyzji biznesowych.

Integracja z narzędziami analitycznymi a prywatność

Podpinanie AR do analityki (GA4, Matomo, własne rozwiązania) kusi, by wysyłać jak najwięcej danych kontekstowych. W połączeniu z obrazem z kamery łatwo przekroczyć granicę między sensownym pomiarem a ryzykownym profilowaniem. Szczególnie niebezpieczne są automatyczne integracje, które zbierają dane o zdarzeniach wejścia/wyjścia z kamery bez jasnego celu.

Przed wdrożeniem śledzenia warto przejść przez krótką checklistę:

• czy jakiekolwiek identyfikatory sesji AR są powiązane z danymi pozwalającymi na identyfikację osoby (e-mail, login, numer konta);
• czy dane o interakcjach w AR są przechowywane osobno od danych transakcyjnych, a ich retencja jest ograniczona;
• czy w komunikatach o zgodzie na kamerę jasno opisano, w jakim celu dane są przetwarzane (np. wyłącznie do wykrywania markera, bez nagrywania obrazu);
• czy w narzędziu analitycznym wyłączono lub ograniczono funkcje, które mogłyby łączyć sesję AR z dodatkowymi źródłami identyfikującymi użytkownika (np. CRM, system lojalnościowy);
• czy użytkownik ma łatwy dostęp do informacji o zakresie pomiaru w AR (np. osobny akapit w polityce prywatności, krótki link „Jak działają pomiary w AR?” w widoku kamery).

Sygnał ostrzegawczy: zespół produktowy nie jest w stanie w prosty sposób wyjaśnić, po co zbierany jest dany typ zdarzenia AR ani jak długo jest przechowywany. To zwykle oznacza, że analityka powstała „po drodze”, bez jasnego celu i bez uwzględnienia wymogów prawnych.

Punkt kontrolny: jeżeli po przeglądzie konfiguracji analityki można spokojnie pokazać ekran z listą zbieranych zdarzeń działowi prawnemu i zespołowi bezpieczeństwa, a opis „po co i na jak długo” mieści się na jednej stronie, poziom przejrzystości jest wystarczający.

Łączenie danych technicznych z zachowaniem użytkownika

AR.js i Three.js generują szereg danych technicznych, które zwykle lądują w logach: czas inicjalizacji sceny, błędy ładowania tekstur czy spadki FPS. Same w sobie są mało czytelne dla biznesu, ale po połączeniu z podstawowymi zdarzeniami behawioralnymi pokazują, dlaczego użytkownicy rezygnują z doświadczenia AR.

Praktyczne minimum to zderzenie dwóch perspektyw: metryk technicznych (czas renderu pierwszej ramki, liczba błędów shaderów, utrata trackingu) z metrykami zachowania (porzucenie przed wykryciem markera, brak interakcji z modelem, bardzo krótka sesja). Dobry schemat to osobna warstwa logowania technicznego (np. wysyłana do narzędzia logującego) i cienka warstwa „podsumowań” wysyłana do systemu analitycznego w formie znormalizowanych zdarzeń.

Sygnał ostrzegawczy: zespół deweloperski widzi powtarzające się błędy w konsoli przeglądarki lub logach, ale nie potrafi ich powiązać z realnymi spadkami konwersji lub z porzuceniami sceny AR. W takiej sytuacji brakuje kleju między danymi technicznymi a ścieżką użytkownika.

Punkt kontrolny: jeżeli na podstawie kilku raportów da się odpowiedzieć na pytanie „czy spadek wydajności lub awaria wpływa na zachowanie użytkowników i jak mocno”, a nie tylko „co się zepsuło w logach”, system pomiaru wspiera decyzje o priorytetach napraw i optymalizacji.

Testy A/B i iteracje oparte na danych

Sceny AR rzadko trafiają w potrzeby użytkowników od pierwszej wersji. Świadome iteracje wymagają kontrolowanych eksperymentów, a nie wyłącznie opinii zespołu czy pojedynczych „insightów” z testów jakościowych. Nawet proste testy A/B są w stanie pokazać, czy inny onboarding, lżejszy model 3D lub zmiana interfejsu kamery realnie poprawiają zaangażowanie.

Dla scen AR sensowny jest ograniczony zestaw wariantów: różne komunikaty startowe, alternatywne modele (wysoka vs niższa szczegółowość), odmienne poziomy szczegółowości interfejsu. Ważne, aby każdy wariant miał jedno główne założenie do weryfikacji, a wyniki były czytane razem z metrykami technicznymi (np. porównanie współczynnika wykrycia markera i średniego FPS między wersjami).

Sygnał ostrzegawczy: po wdrożeniu nowej sceny AR wyniki kampanii „skaczą”, a zespół nie potrafi jednoznacznie wskazać, czy powodem jest zmiana komunikatu, cięższy model czy inna konfiguracja markerów. To znak, że zmieniono zbyt wiele elementów naraz, bez kontroli nad wariantami.

Punkt kontrolny: jeśli każdy większy refactor sceny AR lub istotna zmiana onboarding’u mają przypisany prosty test porównawczy, a wnioski z poprzednich testów są używane przy projektowaniu kolejnych wersji, zespół faktycznie uczy się na danych zamiast polegać na domysłach.

Technicznie najprostsze są testy oparte na flagach konfiguracyjnych i lekkim routerze wariantów po stronie frontendu. Router decyduje, który model, zestaw tekstur lub layout interfejsu wczytać, a informację o przydzielonym wariancie zapisujesz jako pierwszy event w sesji AR. Dzięki temu każdy kolejny sygnał (wykrycie markera, interakcje, porzucenie) ma jasny kontekst – wiadomo, której wersji sceny dotyczy.

Sygnał ostrzegawczy: w raportach analitycznych widać dane „zmiksowane” z wielu rewizji sceny AR, bez możliwości odfiltrowania konkretnych wersji modelu, tekstur czy onboarding’u. W takim układzie nawet prawidłowo wdrożone testy A/B nie przynoszą praktycznej wiedzy – brakuje spójnego klucza, który pozwala porównać warianty.

Punkt kontrolny: jeżeli do każdego poważniejszego wdrożenia sceny AR można przypisać unikalny identyfikator konfiguracji (zapisany w kodzie i w analityce), a raporty wyników są filtrowane po tym identyfikatorze, zespół ma narzędzie do planowego, a nie przypadkowego uczenia się na danych.

Scena AR zbudowana na AR.js i Three.js nie jest ani gadżetem, ani magiczną czarną skrzynką. To po prostu kolejna warstwa interfejsu: z własnymi wymaganiami co do wydajności, dostępności, bezpieczeństwa i pomiaru. Jeśli spełnione są proste punkty kontrolne – od stabilnego FPS, przez sensownie dobrane modele i markery, aż po przejrzystą analitykę – rozszerzona rzeczywistość staje się przewidywalnym elementem produktu, a nie ryzykowną ciekawostką.

Najczęściej zadawane pytania (FAQ)

Co to jest AR.js i jak działa na zwykłej stronie HTML?

AR.js to biblioteka JavaScript do uruchamiania rozszerzonej rzeczywistości bezpośrednio w przeglądarce, na zwykłej stronie HTML. Korzysta z kamery urządzenia (przez WebRTC), przetwarza obraz wideo, szuka markerów i na tej podstawie oblicza, gdzie umieścić obiekty 3D w scenie.

Na wierzchu AR.js zwykle działa Three.js, który odpowiada za scenę 3D, światła, modele i materiały. AR.js aktualizuje pozycję i orientację „wirtualnej kamery” i obiektów, a Three.js je renderuje. Punkt kontrolny: AR.js nie „zmienia” fizycznej kamery, tylko symuluje ją w scenie 3D na podstawie wykrytego markera.

Kiedy lepiej użyć WebAR z AR.js, a kiedy ARKit/ARCore lub Unity?

AR.js ma przewagę tam, gdzie kluczowe są szybki start i brak instalacji aplikacji: kampanie marketingowe, proste doświadczenia edukacyjne, krótkie interakcje produktowe, stoiska eventowe. Użytkownik otwiera link, zgadza się na dostęp do kamery i od razu widzi AR – to minimum bariery wejścia.

Jeśli potrzebne jest śledzenie bez markerów, wykrywanie płaskich powierzchni, długie sesje (gra, symulator), skomplikowana fizyka lub zaawansowane efekty graficzne, sygnałem ostrzegawczym jest wybór AR.js. W takich przypadkach bardziej adekwatne są: ARKit/ARCore z Unity/Unreal albo natywne aplikacje mobilne.

Jakie są główne ograniczenia AR.js i Three.js w przeglądarce?

Największym ograniczeniem jest tryb śledzenia: standardowo AR markerowa, wrażliwa na jakość wydruku, kontrast, oświetlenie i kąt patrzenia. Jeśli marker jest mały, pognieciony lub źle oświetlony, model zaczyna „drgać” albo znikać – to typowy punkt kontrolny podczas testów.

Drugim obszarem jest wydajność grafiki. Sceny muszą być lekkie: ograniczona liczba polygonów, proste materiały, niewiele świateł. Do tego dochodzi okrojona interakcja z otoczeniem – brak zaawansowanego raycastingu w świecie rzeczywistym i pełnego dostępu do czujników. Jeśli projekt wymaga realizmu klasy konsolowej, AR.js będzie wąskim gardłem.

Jakie są minimalne wymagania sprzętowe i przeglądarkowe dla AR.js?

Minimum po stronie użytkownika to: przeglądarka z obsługą WebGL i getUserMedia (Chrome, Firefox, Safari w aktualnych wersjach), urządzenie z kamerą oraz połączenie przez HTTPS lub localhost. Bez HTTPS przeglądarka zablokuje dostęp do kamery, co kończy projekt już na starcie.

Drugi punkt kontrolny to wydajność urządzenia. Na tańszych smartfonach WebAR będzie działać, ale mniej płynnie: spadki FPS, opóźnienie reakcji na ruch markera. Przy projekcie produkcyjnym minimum to testy na kilku modelach z niższej i średniej półki, zamiast zakładania, że „działa na moim telefonie, więc jest dobrze”.

Do jakich zastosowań WebAR z AR.js i Three.js w praktyce wystarcza?

AR.js dobrze sprawdza się w scenariuszach, gdzie AR jest dodatkiem do treści WWW: kampanie z ulotkami i plakatami z markerem, proste wizualizacje produktów, krótkie doświadczenia edukacyjne w podręcznikach, wystawy i stoiska targowe z wydrukowanymi znacznikami. Interakcja trwa zwykle od kilkudziesięciu sekund do kilku minut.

Jeśli celem jest efekt „wow”, szybkie przekazanie informacji lub wsparcie sprzedaży, a nie długotrwała, złożona aplikacja, WebAR jest rozsądnym kompromisem między kosztem wdrożenia a efektem. Gdy AR ma być głównym produktem (np. rozbudowana gra), sygnał ostrzegawczy to chęć upchania wszystkiego w przeglądarce.

Kiedy zdecydowanie nie używać AR.js na stronie WWW?

Czerwone flagi to: wymaganie śledzenia bez markerów (pełne mapowanie otoczenia, wykrywanie powierzchni), długa i intensywna sesja (30–60 minut), bardzo szczegółowe modele 3D, skomplikowane shadery oraz potrzeba działania offline bez HTTPS i bez zgód na kamerę. W takich warunkach WebAR będzie utrudnieniem, nie rozwiązaniem.

Jeśli choć jeden z tych punktów jest kluczowym wymaganiem biznesowym, punktem kontrolnym powinna być zmiana technologii na Unity/Unreal z ARKit/ARCore albo natywne rozwiązanie mobilne. AR.js zostaje wtedy jako narzędzie do lekkich, webowych dodatków, a nie fundament całej aplikacji.

Jak połączyć AR.js z istniejącą stroną i systemem CMS?

AR.js osadza się w zwykłym kodzie HTML jako skrypt i elementy sceny (np. kontener z Three.js lub A-Frame), więc integruje się z istniejącym front-endem, CMS-em, analityką (Google Analytics, Matomo) czy systemem A/B testów. Strona nadal pozostaje stroną WWW, na którą po prostu nałożony jest moduł AR.

Jeśli priorytetem jest spójność z obecnym ekosystemem webowym: szablonami CMS, tag managerem, systemem zgód, to WebAR jest logicznym wyborem. Punkt kontrolny: jeżeli wdrożenie AR wymagałoby całkowitego „wyrwania” treści z CMS do osobnej aplikacji mobilnej, wtedy AR.js znacząco upraszcza cały łańcuch utrzymania.