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:

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:

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

Przykład:

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:

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

albo jako element ścieżki URL:

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.

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.

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

`numberPlates`

Lookup image-setu po numerze rejestracyjnym pojazdu.

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

`numberplates`

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

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:

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:

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

`autoplay`

Steruje automatycznym odtwarzaniem prezentacji.

Domyślna wartość:

true

Przykład włączenia autoplay:

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

Przykład wyłączenia autoplay:

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ść:

Przykład — HUD zawsze widoczny:

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

Przykład — HUD ukrywany po 10 sekundach:

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

Przykład — HUD niewyświetlany:

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

`bg`

Steruje kolorem tła Playera.

Domyślna wartość:

#000

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

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

Przykład:

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

Przykład z kolorem HEX:

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ść:

auto

Przykład:

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.

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ść:

false

Przykład:

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ść:

true

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

Przykład:

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

Przykład wyłączenia:

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

Przykłady konfiguracji

Minimalna konfiguracja po `carId`

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

Lookup po numerze VIN

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

Lookup po numerze rejestracyjnym

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

Player z językiem polskim i jasnym tłem

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

Player z sekcją „Inne pojazdy”

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

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

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

Player bez HUD-u

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

Player z HUD-em zawsze widocznym

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

Player w trybie carousel

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

Konfiguracja przez ścieżkę URL

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

Przykład osadzenia skonfigurowanego Playera

<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>

.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.

Personalizacja

Sposób przekazywania konfiguracji

Identyfikacja pojazdu

Parametry konfiguracyjne

Parametry identyfikujące galerię

key

carId

vin

numberPlates

numberplates

Parametry interfejsu

lang

autoplay

hudhide

bg

slide_mode

Sekcja „Inne pojazdy”

ann_dealer_id

ann_show_more

Zdjęcia interior

interior_fullscreen

Przykłady konfiguracji

Minimalna konfiguracja po carId

Lookup po numerze VIN

Lookup po numerze rejestracyjnym

Player z językiem polskim i jasnym tłem

Player z sekcją „Inne pojazdy”

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

Player bez HUD-u

Player z HUD-em zawsze widocznym

Player w trybie carousel

Konfiguracja przez ścieżkę URL

Przykład osadzenia skonfigurowanego Playera

Dobre praktyki

Czy to było pomocne?

`key`

`carId`

`vin`

`numberPlates`

`numberplates`

`lang`

`autoplay`

`hudhide`

`bg`

`slide_mode`

`ann_dealer_id`

`ann_show_more`

`interior_fullscreen`

Minimalna konfiguracja po `carId`