# Personalizacja

Player VirtualCar360 oraz Player 360 mogą być konfigurowane za pomocą parametrów przekazywanych w adresie URL. Parametry pozwalają określić sposób wyszukania galerii, język interfejsu, tryb odtwarzania, kolor tła, zachowanie HUD-u oraz dodatkowe funkcje, takie jak sekcja innych pojazdów z tej samej lokalizacji.

Konfiguracja jest przekazywana jako query string albo, w wybranych przypadkach, jako część ścieżki URL.

## Sposób przekazywania konfiguracji

Najczęściej konfiguracja przekazywana jest jako parametry query string:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&bg=black&autoplay=true
```

W wybranych wariantach Playera klucz oraz identyfikator samochodu mogą być również przekazane w ścieżce URL:

```txt
https://player360-staging.web.app/dealers/{key}/cars/{carId}
```

Przykład:

```txt
https://player360-staging.web.app/dealers/2f2b265625d76a6704b08093c652fd79/cars/10209937?ann_dealer_id=72&ann_show_more=true&bg=aaa
```

## Identyfikacja pojazdu

Player może pobrać galerię pojazdu na kilka sposobów:

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


Najbardziej jednoznaczną metodą jest przekazanie `carId`. Jeżeli `carId` nie jest dostępny, można użyć numeru VIN albo numeru rejestracyjnego pojazdu.

Wskazówka
W typowej integracji z listingiem ofert najwygodniejsze jest użycie `vin` albo `numberPlates`, ponieważ te wartości są zwykle dostępne w systemie klienta.

## Parametry konfiguracyjne

| Parametr | Domyślna wartość | Opis |
|  --- | --- | --- |
| `key` | `''` | Klucz image-setu. Może być również przekazany jako parametr ścieżki. |
| `carId` | `''` | Identyfikator samochodu. Pozwala bezpośrednio wskazać konkretną galerię lub image-set. |
| `vin` | `''` | Alternatywny lookup image-setu po numerze VIN. |
| `numberPlates` | `''` | Alternatywny lookup image-setu po numerze rejestracyjnym. |
| `numberplates` | `''` | Alias dla parametru `numberPlates`. |
| `lang` | język przeglądarki, fallback `en` | Język interfejsu. Obsługiwane wartości: `bg`, `hr`, `cs`, `da`, `nl`, `en`, `et`, `fi`, `fr`, `de`, `el`, `is`, `hu`, `it`, `lv`, `lt`, `mt`, `pl`, `pt`, `ro`, `sk`, `sl`, `es`, `sv`. Tłumaczenia interfejsu mogą być wspierane przez AI. |
| `autoplay` | `true` | Włącza automatyczne odtwarzanie prezentacji. |
| `hudhide` | `5` | Steruje widocznością HUD-u. `-1` oznacza HUD zawsze widoczny, `0` oznacza HUD niewyświetlany, a dodatnia liczba oznacza czas w sekundach, po którym HUD znika bez interakcji. |
| `bg` | `#000` | Kolor tła Playera. Akceptuje wartości obsługiwane przez CSS, np. `bg=fff`, `bg=black`, `bg=%23000000`. Niepoprawna wartość powoduje powrót do `#000`. |
| `slide_mode` | `auto` | Tryb przesuwania zdjęć. Obsługiwane wartości: `auto`, `basic`, `carousel`, `swipe`. Niepoprawna wartość powoduje powrót do `auto`. |
| `ann_dealer_id` | `''` | ID dealera z portalu ogłoszeń dla sekcji **Inne pojazdy**. Jeżeli parametr nie zostanie przekazany albo jego wartość nie jest liczbą, przycisk **Inne pojazdy** nie jest wyświetlany. |
| `ann_show_more` | `false` | Po najechaniu kursorem na miniaturkę pojazdu w sekcji **Inne pojazdy** wyświetla duży podgląd na środku ekranu. |
| `interior_fullscreen` | `true` | Zdjęcia wnętrza w proporcji `2:1` wyświetla jako `cover` względem okna przeglądarki. |


## Parametry identyfikujące galerię

### `key`

Klucz image-setu wymagany do pobrania danych galerii. Może zostać przekazany jako parametr query string:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937
```

albo jako element ścieżki URL:

```txt
https://player360-staging.web.app/dealers/TWOJ_KLUCZ/cars/10209937
```

### `carId`

Identyfikator samochodu lub galerii. Jest najbardziej bezpośrednim sposobem wskazania danych do wyświetlenia.

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937
```

### `vin`

Lookup image-setu po numerze VIN. Przydatny, gdy system klienta nie przechowuje `carId`, ale posiada VIN pojazdu.

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&vin=1NKCLR0X1XR568641
```

### `numberPlates`

Lookup image-setu po numerze rejestracyjnym pojazdu.

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&numberPlates=WW4433E
```

### `numberplates`

Alias dla `numberPlates`. Może być używany zamiennie.

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&numberplates=WW4433E
```

Uwaga
Zalecane jest konsekwentne używanie jednej wersji parametru w całej integracji. Preferowana forma to `numberPlates`.

## Parametry interfejsu

### `lang`

Steruje językiem interfejsu Playera.

Jeżeli parametr `lang` nie zostanie przekazany, Player próbuje użyć języka przeglądarki. Jeżeli język przeglądarki nie jest obsługiwany, używany jest fallback `en`.

Obsługiwane języki:

```txt
bg, hr, cs, da, nl, en, et, fi, fr, de, el, hu, it, lv, lt, mt, pl, pt, ro, sk, sl, es, sv
```

Przykład:

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

### `autoplay`

Steruje automatycznym odtwarzaniem prezentacji.

Domyślna wartość:

```txt
true
```

Przykład włączenia autoplay:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&autoplay=true
```

Przykład wyłączenia autoplay:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&autoplay=false
```

### `hudhide`

Steruje widocznością HUD-u, czyli elementów interfejsu nakładanych na Player.

Wartości:

| Wartość | Znaczenie |
|  --- | --- |
| `-1` | HUD zawsze widoczny. |
| `0` | HUD niewyświetlany. |
| liczba dodatnia | Liczba sekund bez interakcji, po których HUD zostanie ukryty. |


Domyślna wartość:

```txt
5
```

Przykład — HUD zawsze widoczny:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&hudhide=-1
```

Przykład — HUD ukrywany po 10 sekundach:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&hudhide=10
```

Przykład — HUD niewyświetlany:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&hudhide=0
```

### `bg`

Steruje kolorem tła Playera.

Domyślna wartość:

```txt
#000
```

Parametr akceptuje wartości zgodne z CSS, na przykład:

```txt
bg=fff
bg=black
bg=%23000000
bg=%23ffffff
```

Przykład:

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

Przykład z kolorem HEX:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&bg=%23ffffff
```

Ostrzeżenie
Znak `#` w adresie URL powinien być zakodowany jako `%23`. Dlatego wartość `#ffffff` należy przekazać jako `bg=%23ffffff`.

Jeżeli wartość parametru `bg` jest niepoprawna, Player użyje wartości domyślnej `#000`.

### `slide_mode`

Steruje trybem przesuwania zdjęć.

Obsługiwane wartości:

| Wartość | Opis |
|  --- | --- |
| `auto` | Player automatycznie dobiera najlepszy tryb. |
| `basic` | Podstawowy tryb przesuwania zdjęć. |
| `carousel` | Tryb karuzeli. |
| `swipe` | Tryb zoptymalizowany pod przesuwanie gestem. |


Domyślna wartość:

```txt
auto
```

Przykład:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&slide_mode=carousel
```

Jeżeli przekazana wartość jest niepoprawna, Player wraca do trybu `auto`.

## Sekcja „Inne pojazdy”

Player może wyświetlać sekcję **Inne pojazdy**, która prezentuje dodatkowe oferty z tej samej lokalizacji albo z powiązanego portalu ogłoszeń.

### `ann_dealer_id`

ID dealera z portalu ogłoszeń dla sekcji **Inne pojazdy**.

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&ann_dealer_id=72
```

Jeżeli parametr `ann_dealer_id` nie zostanie przekazany albo jego wartość nie jest liczbą, przycisk **Inne pojazdy** nie jest wyświetlany.

### `ann_show_more`

Steruje dużym podglądem pojazdu po najechaniu kursorem na miniaturkę w sekcji **Inne pojazdy**.

Domyślna wartość:

```txt
false
```

Przykład:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&ann_dealer_id=72&ann_show_more=true
```

Jeżeli `ann_show_more=true`, po najechaniu kursorem na miniaturkę pojazdu w listingu **Inne pojazdy** wyświetlany jest duży podgląd na środku ekranu.

## Zdjęcia interior

### `interior_fullscreen`

Steruje sposobem wyświetlania zdjęć typu interior w proporcjach `2:1`.

Domyślna wartość:

```txt
true
```

Jeżeli `interior_fullscreen=true`, zdjęcia interior są wyświetlane jako `cover` względem okna przeglądarki.

Przykład:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&interior_fullscreen=true
```

Przykład wyłączenia:

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&interior_fullscreen=false
```

## Przykłady konfiguracji

### Minimalna konfiguracja po `carId`

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937
```

### Lookup po numerze VIN

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&vin=1NKCLR0X1XR568641
```

### Lookup po numerze rejestracyjnym

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&numberPlates=WW4433E
```

### Player z językiem polskim i jasnym tłem

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&lang=pl&bg=%23ffffff
```

### Player z sekcją „Inne pojazdy”

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&ann_dealer_id=72
```

### Player z dużym podglądem innych pojazdów

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&ann_dealer_id=72&ann_show_more=true
```

### Player bez HUD-u

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&hudhide=0
```

### Player z HUD-em zawsze widocznym

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&hudhide=-1
```

### Player w trybie carousel

```txt
https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&slide_mode=carousel
```

### Konfiguracja przez ścieżkę URL

```txt
https://player360-staging.web.app/dealers/2f2b265625d76a6704b08093c652fd79/cars/10209937?ann_dealer_id=72&ann_show_more=true&bg=aaa
```

## Przykład osadzenia skonfigurowanego Playera

```html
<div class="vc360-player-wrapper">
  <iframe
    src="https://virtualcar360.pl/player/?key=TWOJ_KLUCZ&carId=10209937&lang=pl&bg=black&hudhide=5&slide_mode=auto"
    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;
}
```

## Dobre praktyki

- Przekazuj tylko jeden identyfikator pojazdu: `carId`, `vin` albo `numberPlates`.
- Jeżeli znasz `carId`, używaj go jako najbardziej jednoznacznej metody wskazania galerii.
- Jeżeli integrujesz Player na listingu ofert, używaj `vin` albo `numberPlates`, ponieważ te dane zwykle znajdują się już w systemie klienta.
- Dla wielu Playerów na jednej stronie stosuj `loading="lazy"`.
- Używaj `ann_dealer_id` tylko wtedy, gdy chcesz wyświetlać sekcję **Inne pojazdy**.
- Jeżeli używasz koloru HEX w parametrze `bg`, zakoduj znak `#` jako `%23`.
- Niepoprawne wartości `bg` oraz `slide_mode` zostaną zastąpione wartościami domyślnymi.