{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Wybór właściwego sposobu integracji","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["#Najlepsze praktyki"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ta sekcja opisuje najlepsze praktyki korzystania z dokumentacji oraz integracji z rozwiązaniami VirtualCar360. Zalecenia dotyczą całej platformy: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Playera"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Playera 360"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["konfiguracji"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["video"]}," oraz ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Celem tych praktyk jest ułatwienie wdrożenia, ograniczenie błędów integracyjnych, poprawa wydajności strony oraz zapewnienie spójnej prezentacji pojazdów we wszystkich kanałach sprzedaży."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"wybór-właściwego-sposobu-integracji","__idx":0},"children":["Wybór właściwego sposobu integracji"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["VirtualCar360 można integrować na kilka sposobów. Wybór zależy od tego, ile kontroli nad prezentacją pojazdu chcesz mieć po stronie własnej aplikacji."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scenariusz"},"children":["Scenariusz"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Zalecane rozwiązanie"},"children":["Zalecane rozwiązanie"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Chcesz szybko osadzić gotową prezentację pojazdu na stronie"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Player"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Chcesz pokazać płynny obrót samochodu 360°"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Player 360"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Chcesz konfigurować wygląd i zachowanie osadzonego widoku"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Configuration"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Chcesz prezentować gotowe filmy pojazdów"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Video"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Chcesz samodzielnie pobierać zdjęcia, hotspoty i linki video"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Wskazówka"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Jeżeli nie musisz budować własnej galerii, zacznij od Playera. Jest to najszybsza i najmniej kosztowna forma integracji."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"zalecany-proces-wdrożenia","__idx":1},"children":["Zalecany proces wdrożenia"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Najbezpieczniejszy proces wdrożenia powinien przebiegać etapami."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wybierz sposób integracji: Player, Player 360 albo API."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Uzyskaj klucz API dla jednej lokalizacji albo klucz grupowy dla wielu lokalizacji."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Przygotuj środowisko testowe."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Przetestuj integrację na kilku pojazdach."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sprawdź przypadki brzegowe: brak galerii, brak video, brak hotspotów, wiele galerii dla jednego pojazdu."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Dopasuj konfigurację Playera do strony klienta."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Zweryfikuj działanie na desktopie, tablecie i telefonie."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sprawdź wydajność strony z większą liczbą ofert."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Przejdź na środowisko produkcyjne."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Monitoruj błędy i zgłaszaj nietypowe przypadki do supportu."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identyfikacja-pojazdu","__idx":2},"children":["Identyfikacja pojazdu"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["W integracjach VirtualCar360 pojazd może być identyfikowany na kilka sposobów:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["po ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carId"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["po ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vin"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["po ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["numberPlates"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["po ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["numberplates"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Najbardziej jednoznaczny jest ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carId"]},", ponieważ wskazuje konkretną galerię lub image-set. VIN i numer rejestracyjny są wygodne wtedy, gdy chcesz, aby system automatycznie wybrał najnowszą galerię pojazdu."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Wskazówka"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Na stronach ofertowych najczęściej najlepiej używać ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vin"]}," albo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["numberPlates"]},", ponieważ te dane są zwykle dostępne w systemie klienta."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"player--najlepsze-praktyki","__idx":3},"children":["Player — najlepsze praktyki"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Player jest najlepszym wyborem, gdy chcesz szybko osadzić gotową prezentację pojazdu bez budowania własnego interfejsu galerii."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecenia:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["osadzaj Player przez ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iframe"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ustaw ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["width=\"100%\""]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używaj responsywnego kontenera,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["dla wielu Playerów na jednej stronie stosuj ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loading=\"lazy\""]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie ładuj jednocześnie zbyt wielu Playerów na pierwszym widoku listingu,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używaj Playera jako głównego elementu strony pojazdu, jeżeli chcesz szybko wdrożyć kompletną prezentację,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["testuj Playera z pojazdami posiadającymi różne typy materiałów: zdjęcia, hotspoty, video, interior, certyfikat."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Przykład zalecanego osadzenia:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"
\n \n
\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"css","header":{"controls":{"copy":{}}},"source":".vc360-player-wrapper {\n position: relative;\n width: 100%;\n padding-bottom: 56.25%;\n height: 0;\n overflow: hidden;\n}\n\n.vc360-player-wrapper iframe {\n position: absolute;\n inset: 0;\n width: 100%;\n height: 100%;\n border: 0;\n}\n","lang":"css"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"player-360--najlepsze-praktyki","__idx":4},"children":["Player 360 — najlepsze praktyki"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Player 360 służy do płynnego obrotu samochodu. Najlepiej sprawdza się jako główny element multimedialny na stronie szczegółów pojazdu."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecenia:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używaj Playera 360 na stronach szczegółów pojazdu,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["na listingach stosuj go ostrożnie, aby nie obciążać strony zbyt dużą liczbą osadzonych komponentów,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["informuj użytkownika, że może obracać samochód i powiększać zdjęcie,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["testuj zoom na urządzeniach dotykowych i desktopie,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pamiętaj, że zoom wykonywany jest na oryginalnych zdjęciach, a nie na klatkach wygenerowanych przez AI,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie zakładaj, że wszystkie klatki Playera 360 posiadają hotspoty."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Ostrzeżenie"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Klatki wygenerowane przez AI nie posiadają hotspotów. Hotspoty mogą być dostępne tylko na oryginalnych zdjęciach, jeżeli zostały oznaczone w systemie."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"konfiguracja-playera","__idx":5},"children":["Konfiguracja Playera"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Konfiguracja Playera powinna być możliwie prosta i przewidywalna."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecenia:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["przekazuj tylko jeden identyfikator pojazdu: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vin"]}," albo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["numberPlates"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używaj ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lang"]},", jeżeli chcesz wymusić konkretny język interfejsu,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["stosuj ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bg"]},", aby dopasować tło Playera do strony,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używaj ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hudhide"]},", aby kontrolować widoczność elementów interfejsu,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używaj ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ann_dealer_id"]}," tylko wtedy, gdy chcesz pokazać sekcję ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Inne pojazdy"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["jeżeli używasz koloru HEX w URL, pamiętaj o zakodowaniu znaku ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#"]}," jako ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%23"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Przykład:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"txt","header":{"controls":{"copy":{}}},"source":"https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&lang=pl&bg=black&hudhide=5\n","lang":"txt"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"video--najlepsze-praktyki","__idx":6},"children":["Video — najlepsze praktyki"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Video jest dodatkową formą prezentacji pojazdu i może zwiększać atrakcyjność oferty."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecenia:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["przed wdrożeniem skontaktuj się z supportem, aby aktywować generowanie video,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ustal, czy video ma być generowane automatycznie dla każdej sesji,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["jeżeli video ma trafiać na YouTube klienta, skonfiguruj integrację YouTube przed wdrożeniem produkcyjnym,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie zakładaj, że każda galeria posiada video,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["w interfejsie zawsze obsługuj sytuację, w której pole ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["video"]}," jest puste albo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["oznaczaj jasno, czy link prowadzi do VirtualCar360, Vimeo czy YouTube,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["wykorzystuj link YouTube w portalach ogłoszeniowych, jeżeli portal pozwala dodać film do oferty."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Uwaga"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Video może być dostępne w systemie VirtualCar360, na Vimeo oraz opcjonalnie na kanale YouTube klienta."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api--najlepsze-praktyki","__idx":7},"children":["API — najlepsze praktyki"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API jest najlepszym wyborem, gdy chcesz samodzielnie budować interfejs galerii lub pobierać dane do własnego systemu."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecenia:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["wykonuj zapytania API przez backend klienta,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie umieszczaj klucza API bezpośrednio w kodzie frontendowym,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używaj zmiennych środowiskowych do przechowywania kluczy,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie zapisuj pełnych URL-i z parametrem ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key"]}," w logach,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["stosuj cache po stronie własnej aplikacji,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["obsługuj błędy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," i ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["przy listowaniu galerii używaj paginacji,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie zakładaj, że każdy pojazd ma galerię,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie zakładaj, że każda galeria ma video lub hotspoty,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["dla wielu lokalizacji używaj klucza grupowego."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecany przepływ API:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pobierz najnowszą galerię po VIN albo numerze rejestracyjnym."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Odczytaj ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," galerii."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Przekaż ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," jako ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carId"]}," do endpointu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/image-set"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pobierz zdjęcia, hotspoty i linki video."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wyświetl dane we własnym systemie."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"bezpieczeństwo","__idx":8},"children":["Bezpieczeństwo"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Klucz API powinien być traktowany jako informacja poufna."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecenia bezpieczeństwa:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie publikuj klucza API w repozytorium,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie przesyłaj klucza w publicznych zgłoszeniach,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie loguj pełnych adresów URL zawierających ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używaj backend proxy dla integracji API,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ogranicz dostęp do klucza tylko do osób odpowiedzialnych za integrację,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["w przypadku podejrzenia wycieku skontaktuj się z supportem,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["dla większych organizacji używaj kluczy grupowych zamiast wielu oddzielnych kluczy w różnych miejscach aplikacji."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Ostrzeżenie"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Player osadzany przez ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iframe"]}," wymaga przekazania klucza w adresie Playera. Dla bezpośrednich zapytań do API zalecane jest jednak ukrycie klucza po stronie backendu klienta."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"wydajność","__idx":9},"children":["Wydajność"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Integracja powinna być zaprojektowana tak, aby nie obciążać niepotrzebnie strony i API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecenia:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["stosuj ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["loading=\"lazy\""]}," dla Playerów osadzanych na listingach,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ogranicz liczbę Playerów ładowanych jednocześnie,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["dla listingów rozważ użycie statycznego zdjęcia jako miniatury, a Playera dopiero na stronie szczegółów,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["cache’uj odpowiedzi API po stronie własnego backendu,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie pobieraj ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/image-set"]}," wielokrotnie dla tego samego pojazdu w krótkim czasie,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używaj paginacji przy pobieraniu list galerii,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pobieraj tylko dane potrzebne w danym widoku."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ux-i-prezentacja-pojazdu","__idx":10},"children":["UX i prezentacja pojazdu"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dobra prezentacja pojazdu powinna być czytelna, szybka i spójna na wszystkich urządzeniach."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecenia:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["na stronie szczegółów pojazdu używaj dużego Playera albo Playera 360,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["zapewnij odpowiednią wysokość Playera na desktopie i mobile,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["zadbaj o kontrast tła Playera względem strony,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["wyświetlaj video jako dodatkowy element prezentacji, nie jako jedyne źródło zdjęć,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pokazuj hotspoty w sposób zrozumiały dla użytkownika,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["jeżeli dostępny jest certyfikat pojazdu, umieść go blisko galerii,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["testuj prezentację na różnych rozdzielczościach ekranu."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"obsługa-braków-danych","__idx":11},"children":["Obsługa braków danych"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nie każda galeria musi posiadać wszystkie typy danych."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Integracja powinna poprawnie obsługiwać sytuacje, w których:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pojazd nie ma galerii,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["galeria nie ma video,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["galeria nie ma hotspotów,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["galeria nie ma zdjęć 1080p,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["numer VIN jest błędny,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["numer rejestracyjny nie został znaleziony,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["klucz API nie ma dostępu do danej lokalizacji,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["video nie zostało jeszcze wygenerowane."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Wskazówka"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Brak jednego elementu, np. video, nie powinien blokować wyświetlenia pozostałych danych galerii."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"spójność-dokumentacji","__idx":12},"children":["Spójność dokumentacji"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Podczas rozwijania dokumentacji warto zachować spójną strukturę i nazewnictwo."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecenia:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używaj tych samych nazw sekcji w dokumentacji opisowej i w OpenAPI,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["unikaj technicznych nazw kontrolerów, takich jak ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VirtualCarControllerV"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["grupuj endpointy według funkcji biznesowej, np. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Listowanie galerii"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Najnowsza galeria"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Zdjęcia"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["każdy endpoint powinien mieć opis, przykład zapytania i przykładową odpowiedź,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["każda sekcja powinna wyjaśniać, kiedy należy użyć danego rozwiązania,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["przykłady powinny używać tych samych placeholderów, np. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TWOJ_KLUCZ_API"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nazwy parametrów powinny być konsekwentne w całej dokumentacji,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["OpenAPI powinien być traktowany jako źródło dla sekcji API Reference, a strony Markdown jako wyjaśnienie procesu integracji."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"wersjonowanie-i-zmiany","__idx":13},"children":["Wersjonowanie i zmiany"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dokumentacja powinna jasno informować, której wersji API dotyczy."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Zalecenia:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["umieszczaj wersję API w dokumentacji, np. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v6.0"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["opisuj zmiany w sekcji ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Changelog"]},","]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["informuj o zmianach w strukturze odpowiedzi,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["oznaczaj endpointy przestarzałe albo niezalecane,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["nie usuwaj informacji o istniejących parametrach bez wskazania alternatywy,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["w przypadku migracji dodaj osobną sekcję ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Migration"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"testowanie-integracji","__idx":14},"children":["Testowanie integracji"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Przed przejściem na produkcję przetestuj integrację na różnych przypadkach."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Lista kontrolna:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pojazd z jedną galerią,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pojazd z wieloma galeriami,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pojazd z video,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pojazd bez video,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pojazd z hotspotami,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pojazd bez hotspotów,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pojazd z Playerem 360,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["błędny VIN,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["błędny numer rejestracyjny,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["brak dostępu klucza do lokalizacji,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["widok desktop,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["widok mobile,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["wolniejsze połączenie internetowe."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"kontakt-z-supportem","__idx":15},"children":["Kontakt z supportem"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Skontaktuj się z supportem VirtualCar360, gdy:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["potrzebujesz klucza API,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["potrzebujesz klucza grupowego dla wielu lokalizacji,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["chcesz aktywować generowanie video,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["chcesz skonfigurować automatyczne przesyłanie video na YouTube,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["dane pojazdu nie są widoczne mimo poprawnego VIN lub numeru rejestracyjnego,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Player nie wyświetla galerii,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["API zwraca błąd serwera,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["potrzebujesz pomocy przy wdrożeniu produkcyjnym."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["W zgłoszeniu warto podać:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["klucz lub nazwę lokalizacji,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["VIN albo numer rejestracyjny pojazdu,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["adres zapytania bez ujawniania pełnego klucza API,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["środowisko: testowe lub produkcyjne,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["opis problemu,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["zrzut ekranu albo fragment odpowiedzi API, jeżeli jest dostępny."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"podsumowanie","__idx":16},"children":["Podsumowanie"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Najlepsze wdrożenia VirtualCar360 są proste, bezpieczne i spójne. W większości przypadków warto zacząć od Playera lub Playera 360, a API wykorzystywać wtedy, gdy potrzebna jest pełna kontrola nad danymi i własnym interfejsem prezentacji pojazdu."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dobrze przygotowana integracja powinna:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["używać właściwego sposobu identyfikacji pojazdu,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["chronić klucz API,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["obsługiwać brakujące dane,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["działać responsywnie,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["wykorzystywać cache,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["mieć jasny proces testowania,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["być zgodna z aktualną wersją dokumentacji."]}]}]},"headings":[{"value":"Wybór właściwego sposobu integracji","id":"wybór-właściwego-sposobu-integracji","depth":2},{"value":"Zalecany proces wdrożenia","id":"zalecany-proces-wdrożenia","depth":2},{"value":"Identyfikacja pojazdu","id":"identyfikacja-pojazdu","depth":2},{"value":"Player — najlepsze praktyki","id":"player--najlepsze-praktyki","depth":2},{"value":"Player 360 — najlepsze praktyki","id":"player-360--najlepsze-praktyki","depth":2},{"value":"Konfiguracja Playera","id":"konfiguracja-playera","depth":2},{"value":"Video — najlepsze praktyki","id":"video--najlepsze-praktyki","depth":2},{"value":"API — najlepsze praktyki","id":"api--najlepsze-praktyki","depth":2},{"value":"Bezpieczeństwo","id":"bezpieczeństwo","depth":2},{"value":"Wydajność","id":"wydajność","depth":2},{"value":"UX i prezentacja pojazdu","id":"ux-i-prezentacja-pojazdu","depth":2},{"value":"Obsługa braków danych","id":"obsługa-braków-danych","depth":2},{"value":"Spójność dokumentacji","id":"spójność-dokumentacji","depth":2},{"value":"Wersjonowanie i zmiany","id":"wersjonowanie-i-zmiany","depth":2},{"value":"Testowanie integracji","id":"testowanie-integracji","depth":2},{"value":"Kontakt z supportem","id":"kontakt-z-supportem","depth":2},{"value":"Podsumowanie","id":"podsumowanie","depth":2}],"frontmatter":{"seo":{"title":"Wybór właściwego sposobu integracji"}},"lastModified":"2026-06-16T22:34:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/best-practices","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}