# Player 360
Player 360 VirtualCar360 to interaktywny komponent frontendowy przeznaczony do prezentacji płynnego obrotu samochodu. Implementacja Playera 360 jest taka sama jak standardowego Playera, komponent osadzany jest na stronie jako `iframe` i może zostać załadowany po numerze VIN albo numerze rejestracyjnym pojazdu.
div
iframe
Główna różnica polega na sposobie prezentacji zdjęć. Player 360 wykorzystuje większą liczbę klatek oraz szybsze tempo odtwarzania, dzięki czemu obrót samochodu jest znacznie płynniejszy niż w standardowej galerii zdjęć.
W zależności od konfiguracji Player 360 może wykorzystywać:
- 180 zdjęć,
- 360 zdjęć.
Zdjęcia pośrednie są generowane przez AI na podstawie 4 albo 8 oryginalnych ujęć samochodu. Oryginalne zdjęcia stanowią punkty referencyjne, a klatki pomiędzy nimi są tworzone automatycznie poprzez autorskie rozwiązanie AI, aby uzyskać płynny efekt obrotu pojazdu.
Wskazówka
Implementacja Playera 360 jest identyczna jak zwykłego Playera. Wystarczy osadzić `iframe` z adresem Playera oraz przekazać `vin` albo `numberplates` i `key`.
## Zastosowanie
Player 360 jest przeznaczony do prezentacji pojazdu w formie płynnego, interaktywnego obrotu. Najczęściej wykorzystywany jest:
- jako główny element multimedialny na stronie pojazdu,
- jako slider strony szczegółów pojazdu,
- jako uzupełnienie standardowego Playera,
- jako element zwiększający atrakcyjność oferty,
- jako forma prezentacji samochodu zbliżona do oglądania pojazdu na żywo.
Player 360 pozwala użytkownikowi samodzielnie obracać samochód, zatrzymywać widok na wybranym kącie oraz powiększać zdjęcie w celu dokładniejszego obejrzenia detali.
## Zasada działania
Player 360 działa jako zewnętrzny widget osadzany przez `iframe`.
Po załadowaniu Player:
1. odczytuje parametry z adresu URL,
2. identyfikuje pojazd po numerze VIN albo numerze rejestracyjnym,
3. pobiera najnowszą galerię przypisaną do pojazdu,
4. ładuje zestaw zdjęć przeznaczony do prezentacji 360,
5. odtwarza płynną sekwencję obrotu pojazdu,
6. umożliwia użytkownikowi interakcję z widokiem, w tym przesuwanie, zatrzymywanie i powiększanie zdjęcia.
W zależności od konfiguracji galeria może składać się z 180 albo 360 klatek. Klatki pośrednie są generowane przez AI na podstawie 4 albo 8 oryginalnych ujęć pojazdu.
## Różnice względem zwykłego Playera
| Obszar | Zwykły Player | Player 360 |
| --- | --- | --- |
| Sposób prezentacji | Galeria zdjęć pojazdu | Płynny obrót samochodu |
| Liczba zdjęć | Zależna od galerii i konfiguracji | Najczęściej 180 albo 360 klatek |
| Płynność | Standardowa prezentacja zdjęć | Szybkie odtwarzanie wielu klatek |
| Zdjęcia AI | Nie są wymagane | Klatki pośrednie mogą być generowane przez AI |
| Źródło zdjęć | Zdjęcia wykonane podczas sesji | 4 albo 8 oryginalnych ujęć + klatki AI |
| Zoom | Powiększanie zdjęć galerii | Powiększanie oryginalnego zdjęcia po przewinięciu do jego pozycji |
| Hotspoty | Mogą występować na zdjęciach | Klatki wygenerowane przez AI nie posiadają hotspotów |
## Generowanie klatek
Player 360 może wykorzystywać zestaw 180 albo 360 klatek. Nie wszystkie klatki muszą pochodzić bezpośrednio z sesji zdjęciowej.
Typowy proces wygląda następująco:
1. Podczas sesji wykonywane są 4 albo 8 oryginalnych zdjęć samochodu.
2. System VirtualCar360 wykorzystuje te zdjęcia jako punkty referencyjne.
3. Klatki pomiędzy oryginalnymi ujęciami są generowane przez AI.
4. Player 360 odtwarza pełną sekwencję jako płynny obrót samochodu.
Dzięki temu możliwe jest uzyskanie efektu pełnego obrotu pojazdu bez konieczności wykonywania 180 albo 360 fizycznych zdjęć podczas sesji.
Klatki wygenerowane przez AI służą do płynnej animacji obrotu pojazdu. Do powiększania i analizy detali wykorzystywane są oryginalne zdjęcia samochodu.
## Powiększanie zdjęcia
Player 360 umożliwia powiększanie zdjęcia na dwa sposoby:
- przez gest pinch zoom na urządzeniach dotykowych,
- przez kółko myszy na komputerach.
Podczas powiększania Player 360 nie powiększa klatki wygenerowanej przez AI. Zamiast tego samochód zostaje automatycznie przewinięty do pozycji najbliższego oryginalnego zdjęcia, a następnie powiększenie wykonywane jest na zdjęciu źródłowym.
Dzięki temu użytkownik otrzymuje płynną animację obrotu, ale podczas oglądania detali korzysta z jakości oryginalnego zdjęcia.
Przykład działania:
1. Użytkownik obraca samochód do dowolnej pozycji.
2. Aktualnie widoczna klatka może być klatką wygenerowaną przez AI.
3. Użytkownik wykonuje pinch zoom albo używa kółka myszy.
4. Player przewija widok do najbliższej pozycji oryginalnego zdjęcia.
5. Powiększenie wykonywane jest na oryginalnym zdjęciu.
Klatki wygenerowane przez AI nie są przeznaczone do szczegółowego powiększania. Zoom wykonywany jest na oryginalnych zdjęciach źródłowych, aby zachować możliwie najwyższą jakość detali pojazdu.
## Hotspoty w Playerze 360
Klatki wygenerowane przez AI nie posiadają hotspotów.
Hotspoty mogą być dostępne tylko dla zdjęć wnętrza, które pochodzą z oryginalnych materiałów i zostały odpowiednio oznaczone w systemie VirtualCar360.
Hotspot może wskazywać na przykład:
- ekran LCD,
- szyberdach,
- element wyposażenia,
- zadrapanie tapicerki,
## Adres Playera 360
Player 360 jest osadzany przez ten sam mechanizm co zwykły Player.
Adres bazowy:
```txt
https://virtualcar360.pl/player/
```
Do adresu należy przekazać identyfikator pojazdu oraz klucz API.
## Parametry URL
| Parametr | Wymagany | Opis |
| --- | --- | --- |
| `carId` | warunkowo | Identyfikator samochodu. Pozwala bezpośrednio wskazać konkretny player. |
| `vin` | warunkowo | Numer VIN pojazdu. Wymagany, jeżeli nie przekazano `numberplates`. |
| `numberplates` | warunkowo | Numer rejestracyjny pojazdu. Wymagany, jeżeli nie przekazano `vin`. |
| `key` | tak | Klucz API przypisany do lokalizacji albo klucz grupowy dla wielu lokalizacji. |
W jednym adresie Playera należy przekazać tylko jeden identyfikator pojazdu: `carId`, `vin` albo `numberplates`. Nie ma potrzeby przekazywania kilku parametrów jednocześnie. `carId` pozwala wskazać konkretny Player, natomiast `vin` i `numberplates` służą do automatycznego wyszukania najnowszego Playera dostępnego dla danego pojazdu.
## Osadzenie Playera 360 po numerze VIN
```html
```
## Osadzenie Playera 360 po numerze rejestracyjnym
```html
```
## Responsywne osadzenie
Zalecanym sposobem osadzania Playera 360 jest umieszczenie `iframe` w responsywnym kontenerze. Dzięki temu Player dopasowuje się do szerokości strony i działa poprawnie na desktopie, tablecie oraz urządzeniach mobilnych.
```html
```
```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;
}
```
Proporcja `56.25%` odpowiada układowi `16:9`. Jeżeli Player 360 ma być głównym elementem strony pojazdu, można zastosować większą wysokość.
```css
.vc360-player-wrapper {
position: relative;
width: 100%;
height: 720px;
overflow: hidden;
}
.vc360-player-wrapper iframe {
width: 100%;
height: 100%;
border: 0;
}
```
## Przykład użycia jako główny slider pojazdu
```html
Volkswagen Passat Variant
2.0 TDI · DSG · 2022
```
```css
.vehicle-hero__player {
width: 100%;
height: 680px;
}
.vehicle-hero__player iframe {
width: 100%;
height: 100%;
border: 0;
}
```
## Dynamiczne generowanie adresu Playera 360
W typowej integracji system klienta posiada już numer VIN albo numer rejestracyjny pojazdu. Adres Playera 360 można wygenerować dynamicznie.
```js
function createVirtualCar360PlayerUrl({ vin, numberplates, apiKey }) {
const url = new URL('https://virtualcar360.pl/player/');
if (vin) {
url.searchParams.set('vin', vin);
} else if (numberplates) {
url.searchParams.set('numberplates', numberplates);
} else {
throw new Error('VIN albo numer rejestracyjny jest wymagany.');
}
url.searchParams.set('key', apiKey);
return url.toString();
}
const playerUrl = createVirtualCar360PlayerUrl({
vin: '1NKCLR0X1XR568641',
apiKey: 'TWOJ_KLUCZ_API',
});
document.querySelector('#vc360-player').src = playerUrl;
```
```html
```
## Przykład integracji w React
```tsx
type VirtualCar360PlayerProps = {
vin?: string;
numberplates?: string;
apiKey: string;
};
export function VirtualCar360Player({
vin,
numberplates,
apiKey,
}: VirtualCar360PlayerProps) {
const url = new URL('https://virtualcar360.pl/player/');
if (vin) {
url.searchParams.set('vin', vin);
} else if (numberplates) {
url.searchParams.set('numberplates', numberplates);
} else {
throw new Error('VIN albo numer rejestracyjny jest wymagany.');
}
url.searchParams.set('key', apiKey);
return (
);
}
```
## Automatyczny wybór galerii
Player 360 automatycznie wybiera najnowszą galerię przypisaną do przekazanego numeru VIN albo numeru rejestracyjnego.
Oznacza to, że w integracji nie trzeba znać identyfikatora `carId`. Wystarczy, że system klienta posiada VIN albo numer rejestracyjny pojazdu.
Przykład:
```txt
https://virtualcar360.pl/player/?vin=1NKCLR0X1XR568641&key=TWOJ_KLUCZ_API
```
W tym przypadku Player:
1. wyszuka galerie przypisane do VIN `1NKCLR0X1XR568641`,
2. wybierze najnowszą galerię,
3. wyświetli ją w osadzonym widoku,
4. uruchomi prezentację 360 zgodnie z konfiguracją galerii.
## Player 360 a API
Player 360 jest najprostszym sposobem prezentacji płynnego obrotu pojazdu, ponieważ nie wymaga samodzielnego pobierania klatek, obsługi sekwencji zdjęć ani implementowania mechanizmu zoomu.
Jeżeli chcesz samodzielnie zbudować własny interfejs galerii, użyj API. Typowy proces API wygląda wtedy następująco:
1. Pobierz najnowszą galerię po VIN albo numerze rejestracyjnym.
2. Odczytaj `id` galerii.
3. Przekaż `id` jako `carId` do endpointu `/image-set`.
4. Pobierz zestawy zdjęć, hotspoty i linki do materiałów video.
5. Zbuduj własny interfejs prezentacji pojazdu.
W przypadku Playera 360 ten proces jest obsługiwany automatycznie przez komponent osadzony w `iframe`.
## Bezpieczeństwo i dobre praktyki
- Używaj klucza API przypisanego do właściwej lokalizacji albo klucza grupowego, jeżeli Player 360 ma obsługiwać wiele lokalizacji.
- Nie zapisuj prawdziwych kluczy API w publicznych repozytoriach.
- Dla wielu Playerów na jednej stronie stosuj `loading="lazy"`.
- Player 360 najlepiej sprawdza się jako główny element multimedialny na stronie szczegółów pojazdu.
- Na listingu ofert warto ograniczyć liczbę Playerów ładowanych jednocześnie.
- Dla urządzeń mobilnych ustaw szerokość `iframe` na `100%` i kontroluj wysokość przez responsywny kontener.
- Nie należy zakładać, że klatki wygenerowane przez AI posiadają hotspoty.
- Do szczegółowego oglądania detali wykorzystywane są oryginalne zdjęcia źródłowe.
## Najczęstsze problemy
### Player 360 nie wyświetla galerii
Sprawdź, czy:
- przekazano poprawny `vin` albo `numberplates`,
- przekazano poprawny `key`,
- pojazd posiada galerię w systemie VirtualCar360,
- klucz API ma dostęp do lokalizacji, w której znajduje się pojazd,
- dla pojazdu dostępna jest galeria zgodna z konfiguracją Playera 360.
### Player 360 pokazuje inną galerię niż oczekiwano
Player automatycznie wybiera najnowszą galerię dla danego pojazdu. Jeżeli pojazd posiada wiele galerii, wyświetlona zostanie najnowsza dostępna galeria.
### Hotspoty nie są widoczne na wszystkich klatkach
Klatki wygenerowane przez AI nie posiadają hotspotów. Hotspoty mogą występować tylko na oryginalnych zdjęciach, jeżeli zostały oznaczone w systemie VirtualCar360.
### Zoom przełącza widok na inną pozycję samochodu
Jest to oczekiwane zachowanie. Jeżeli użytkownik powiększa klatkę wygenerowaną przez AI, Player przewija samochód do najbliższej pozycji oryginalnego zdjęcia i wykonuje powiększenie na zdjęciu źródłowym.
## Minimalny przykład produkcyjny
```html
```
```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;
}
```