#Najlepsze praktyki

Ta sekcja opisuje najlepsze praktyki korzystania z dokumentacji oraz integracji z rozwiązaniami VirtualCar360. Zalecenia dotyczą całej platformy: **Playera**, **Playera 360**, **konfiguracji**, **video** oraz **API**.

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.

## Wybór właściwego sposobu integracji

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.

| Scenariusz | Zalecane rozwiązanie |
|  --- | --- |
| Chcesz szybko osadzić gotową prezentację pojazdu na stronie | **Player** |
| Chcesz pokazać płynny obrót samochodu 360° | **Player 360** |
| Chcesz konfigurować wygląd i zachowanie osadzonego widoku | **Configuration** |
| Chcesz prezentować gotowe filmy pojazdów | **Video** |
| Chcesz samodzielnie pobierać zdjęcia, hotspoty i linki video | **API** |


Wskazówka
Jeżeli nie musisz budować własnej galerii, zacznij od Playera. Jest to najszybsza i najmniej kosztowna forma integracji.

## Zalecany proces wdrożenia

Najbezpieczniejszy proces wdrożenia powinien przebiegać etapami.

1. Wybierz sposób integracji: Player, Player 360 albo API.
2. Uzyskaj klucz API dla jednej lokalizacji albo klucz grupowy dla wielu lokalizacji.
3. Przygotuj środowisko testowe.
4. Przetestuj integrację na kilku pojazdach.
5. Sprawdź przypadki brzegowe: brak galerii, brak video, brak hotspotów, wiele galerii dla jednego pojazdu.
6. Dopasuj konfigurację Playera do strony klienta.
7. Zweryfikuj działanie na desktopie, tablecie i telefonie.
8. Sprawdź wydajność strony z większą liczbą ofert.
9. Przejdź na środowisko produkcyjne.
10. Monitoruj błędy i zgłaszaj nietypowe przypadki do supportu.


## Identyfikacja pojazdu

W integracjach VirtualCar360 pojazd może być identyfikowany na kilka sposobów:

- po `carId`,
- po `vin`,
- po `numberPlates`,
- po `numberplates`.


Najbardziej jednoznaczny jest `carId`, ponieważ wskazuje konkretną galerię lub image-set. VIN i numer rejestracyjny są wygodne wtedy, gdy chcesz, aby system automatycznie wybrał najnowszą galerię pojazdu.

Wskazówka
Na stronach ofertowych najczęściej najlepiej używać `vin` albo `numberPlates`, ponieważ te dane są zwykle dostępne w systemie klienta.

## Player — najlepsze praktyki

Player jest najlepszym wyborem, gdy chcesz szybko osadzić gotową prezentację pojazdu bez budowania własnego interfejsu galerii.

Zalecenia:

- osadzaj Player przez `iframe`,
- ustaw `width="100%"`,
- używaj responsywnego kontenera,
- dla wielu Playerów na jednej stronie stosuj `loading="lazy"`,
- nie ładuj jednocześnie zbyt wielu Playerów na pierwszym widoku listingu,
- używaj Playera jako głównego elementu strony pojazdu, jeżeli chcesz szybko wdrożyć kompletną prezentację,
- testuj Playera z pojazdami posiadającymi różne typy materiałów: zdjęcia, hotspoty, video, interior, certyfikat.


Przykład zalecanego osadzenia:

```html
<div class="vc360-player-wrapper">
  <iframe
    src="https://virtualcar360.pl/player/?vin=1NKCLR0X1XR568641&key=TWOJ_KLUCZ_API"
    title="VirtualCar360 Player"
    frameborder="0"
    allowfullscreen
    loading="lazy"
  ></iframe>
</div>
```

```css
.vc360-player-wrapper {
  position: relative;
  width: 100%;
  padding-bottom: 56.25%;
  height: 0;
  overflow: hidden;
}

.vc360-player-wrapper iframe {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  border: 0;
}
```

## Player 360 — najlepsze praktyki

Player 360 służy do płynnego obrotu samochodu. Najlepiej sprawdza się jako główny element multimedialny na stronie szczegółów pojazdu.

Zalecenia:

- używaj Playera 360 na stronach szczegółów pojazdu,
- na listingach stosuj go ostrożnie, aby nie obciążać strony zbyt dużą liczbą osadzonych komponentów,
- informuj użytkownika, że może obracać samochód i powiększać zdjęcie,
- testuj zoom na urządzeniach dotykowych i desktopie,
- pamiętaj, że zoom wykonywany jest na oryginalnych zdjęciach, a nie na klatkach wygenerowanych przez AI,
- nie zakładaj, że wszystkie klatki Playera 360 posiadają hotspoty.


Ostrzeżenie
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.

## Konfiguracja Playera

Konfiguracja Playera powinna być możliwie prosta i przewidywalna.

Zalecenia:

- przekazuj tylko jeden identyfikator pojazdu: `carId`, `vin` albo `numberPlates`,
- używaj `lang`, jeżeli chcesz wymusić konkretny język interfejsu,
- stosuj `bg`, aby dopasować tło Playera do strony,
- używaj `hudhide`, aby kontrolować widoczność elementów interfejsu,
- używaj `ann_dealer_id` tylko wtedy, gdy chcesz pokazać sekcję **Inne pojazdy**,
- jeżeli używasz koloru HEX w URL, pamiętaj o zakodowaniu znaku `#` jako `%23`.


Przykład:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&lang=pl&bg=black&hudhide=5
```

## Video — najlepsze praktyki

Video jest dodatkową formą prezentacji pojazdu i może zwiększać atrakcyjność oferty.

Zalecenia:

- przed wdrożeniem skontaktuj się z supportem, aby aktywować generowanie video,
- ustal, czy video ma być generowane automatycznie dla każdej sesji,
- jeżeli video ma trafiać na YouTube klienta, skonfiguruj integrację YouTube przed wdrożeniem produkcyjnym,
- nie zakładaj, że każda galeria posiada video,
- w interfejsie zawsze obsługuj sytuację, w której pole `video` jest puste albo `null`,
- oznaczaj jasno, czy link prowadzi do VirtualCar360, Vimeo czy YouTube,
- wykorzystuj link YouTube w portalach ogłoszeniowych, jeżeli portal pozwala dodać film do oferty.


Uwaga
Video może być dostępne w systemie VirtualCar360, na Vimeo oraz opcjonalnie na kanale YouTube klienta.

## API — najlepsze praktyki

API jest najlepszym wyborem, gdy chcesz samodzielnie budować interfejs galerii lub pobierać dane do własnego systemu.

Zalecenia:

- wykonuj zapytania API przez backend klienta,
- nie umieszczaj klucza API bezpośrednio w kodzie frontendowym,
- używaj zmiennych środowiskowych do przechowywania kluczy,
- nie zapisuj pełnych URL-i z parametrem `key` w logach,
- stosuj cache po stronie własnej aplikacji,
- obsługuj błędy `400`, `404` i `500`,
- przy listowaniu galerii używaj paginacji,
- nie zakładaj, że każdy pojazd ma galerię,
- nie zakładaj, że każda galeria ma video lub hotspoty,
- dla wielu lokalizacji używaj klucza grupowego.


Zalecany przepływ API:

1. Pobierz najnowszą galerię po VIN albo numerze rejestracyjnym.
2. Odczytaj `id` galerii.
3. Przekaż `id` jako `carId` do endpointu `/image-set`.
4. Pobierz zdjęcia, hotspoty i linki video.
5. Wyświetl dane we własnym systemie.


## Bezpieczeństwo

Klucz API powinien być traktowany jako informacja poufna.

Zalecenia bezpieczeństwa:

- nie publikuj klucza API w repozytorium,
- nie przesyłaj klucza w publicznych zgłoszeniach,
- nie loguj pełnych adresów URL zawierających `key`,
- używaj backend proxy dla integracji API,
- ogranicz dostęp do klucza tylko do osób odpowiedzialnych za integrację,
- w przypadku podejrzenia wycieku skontaktuj się z supportem,
- dla większych organizacji używaj kluczy grupowych zamiast wielu oddzielnych kluczy w różnych miejscach aplikacji.


Ostrzeżenie
Player osadzany przez `iframe` wymaga przekazania klucza w adresie Playera. Dla bezpośrednich zapytań do API zalecane jest jednak ukrycie klucza po stronie backendu klienta.

## Wydajność

Integracja powinna być zaprojektowana tak, aby nie obciążać niepotrzebnie strony i API.

Zalecenia:

- stosuj `loading="lazy"` dla Playerów osadzanych na listingach,
- ogranicz liczbę Playerów ładowanych jednocześnie,
- dla listingów rozważ użycie statycznego zdjęcia jako miniatury, a Playera dopiero na stronie szczegółów,
- cache’uj odpowiedzi API po stronie własnego backendu,
- nie pobieraj `/image-set` wielokrotnie dla tego samego pojazdu w krótkim czasie,
- używaj paginacji przy pobieraniu list galerii,
- pobieraj tylko dane potrzebne w danym widoku.


## UX i prezentacja pojazdu

Dobra prezentacja pojazdu powinna być czytelna, szybka i spójna na wszystkich urządzeniach.

Zalecenia:

- na stronie szczegółów pojazdu używaj dużego Playera albo Playera 360,
- zapewnij odpowiednią wysokość Playera na desktopie i mobile,
- zadbaj o kontrast tła Playera względem strony,
- wyświetlaj video jako dodatkowy element prezentacji, nie jako jedyne źródło zdjęć,
- pokazuj hotspoty w sposób zrozumiały dla użytkownika,
- jeżeli dostępny jest certyfikat pojazdu, umieść go blisko galerii,
- testuj prezentację na różnych rozdzielczościach ekranu.


## Obsługa braków danych

Nie każda galeria musi posiadać wszystkie typy danych.

Integracja powinna poprawnie obsługiwać sytuacje, w których:

- pojazd nie ma galerii,
- galeria nie ma video,
- galeria nie ma hotspotów,
- galeria nie ma zdjęć 1080p,
- numer VIN jest błędny,
- numer rejestracyjny nie został znaleziony,
- klucz API nie ma dostępu do danej lokalizacji,
- video nie zostało jeszcze wygenerowane.


Wskazówka
Brak jednego elementu, np. video, nie powinien blokować wyświetlenia pozostałych danych galerii.

## Spójność dokumentacji

Podczas rozwijania dokumentacji warto zachować spójną strukturę i nazewnictwo.

Zalecenia:

- używaj tych samych nazw sekcji w dokumentacji opisowej i w OpenAPI,
- unikaj technicznych nazw kontrolerów, takich jak `VirtualCarControllerV`,
- grupuj endpointy według funkcji biznesowej, np. **Listowanie galerii**, **Najnowsza galeria**, **Zdjęcia**,
- każdy endpoint powinien mieć opis, przykład zapytania i przykładową odpowiedź,
- każda sekcja powinna wyjaśniać, kiedy należy użyć danego rozwiązania,
- przykłady powinny używać tych samych placeholderów, np. `TWOJ_KLUCZ_API`,
- nazwy parametrów powinny być konsekwentne w całej dokumentacji,
- OpenAPI powinien być traktowany jako źródło dla sekcji API Reference, a strony Markdown jako wyjaśnienie procesu integracji.


## Wersjonowanie i zmiany

Dokumentacja powinna jasno informować, której wersji API dotyczy.

Zalecenia:

- umieszczaj wersję API w dokumentacji, np. `v6.0`,
- opisuj zmiany w sekcji **Changelog**,
- informuj o zmianach w strukturze odpowiedzi,
- oznaczaj endpointy przestarzałe albo niezalecane,
- nie usuwaj informacji o istniejących parametrach bez wskazania alternatywy,
- w przypadku migracji dodaj osobną sekcję **Migration**.


## Testowanie integracji

Przed przejściem na produkcję przetestuj integrację na różnych przypadkach.

Lista kontrolna:

- pojazd z jedną galerią,
- pojazd z wieloma galeriami,
- pojazd z video,
- pojazd bez video,
- pojazd z hotspotami,
- pojazd bez hotspotów,
- pojazd z Playerem 360,
- błędny VIN,
- błędny numer rejestracyjny,
- brak dostępu klucza do lokalizacji,
- widok desktop,
- widok mobile,
- wolniejsze połączenie internetowe.


## Kontakt z supportem

Skontaktuj się z supportem VirtualCar360, gdy:

- potrzebujesz klucza API,
- potrzebujesz klucza grupowego dla wielu lokalizacji,
- chcesz aktywować generowanie video,
- chcesz skonfigurować automatyczne przesyłanie video na YouTube,
- dane pojazdu nie są widoczne mimo poprawnego VIN lub numeru rejestracyjnego,
- Player nie wyświetla galerii,
- API zwraca błąd serwera,
- potrzebujesz pomocy przy wdrożeniu produkcyjnym.


W zgłoszeniu warto podać:

- klucz lub nazwę lokalizacji,
- VIN albo numer rejestracyjny pojazdu,
- adres zapytania bez ujawniania pełnego klucza API,
- środowisko: testowe lub produkcyjne,
- opis problemu,
- zrzut ekranu albo fragment odpowiedzi API, jeżeli jest dostępny.


## Podsumowanie

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.

Dobrze przygotowana integracja powinna:

- używać właściwego sposobu identyfikacji pojazdu,
- chronić klucz API,
- obsługiwać brakujące dane,
- działać responsywnie,
- wykorzystywać cache,
- mieć jasny proces testowania,
- być zgodna z aktualną wersją dokumentacji.