FAQ

Ta sekcja zawiera najczęściej zadawane pytania dotyczące integracji z VirtualCar360. Obejmuje Player, Player 360, konfigurację, video, API, autoryzację oraz typowe problemy występujące podczas wdrożenia.

VirtualCar360 to rozwiązanie do prezentacji pojazdów online. Umożliwia wykorzystanie zdjęć samochodów, galerii 360°, Playera, Playera 360, hotspotów, materiałów video oraz API do integracji z własną stroną internetową, systemem CRM, DMS, portalem ogłoszeniowym albo innym systemem klienta.

Player to gotowy komponent do osadzenia na stronie jako iframe. Nie wymaga budowania własnej galerii ani obsługi zdjęć po stronie klienta.

API służy do pobierania danych, takich jak galerie, zdjęcia, hotspoty i linki video. API jest najlepszym wyborem, gdy klient chce samodzielnie zbudować własny interfejs galerii lub zintegrować dane VirtualCar360 z własnym systemem.

Playera warto użyć, gdy chcesz szybko osadzić gotową prezentację pojazdu na stronie internetowej.

Typowe zastosowania:

• listing ofert,
• strona szczegółów pojazdu,
• główny slider pojazdu,
• dodatkowa galeria w opisie pojazdu,
• prezentacja zdjęć, hotspotów, certyfikatu i video.

Player 360 warto użyć, gdy chcesz zaprezentować płynny obrót samochodu o 360 stopni.

Player 360 najlepiej sprawdza się jako główny element multimedialny na stronie szczegółów pojazdu.

API warto użyć, gdy chcesz:

• pobierać zdjęcia do własnej strony,
• budować własną galerię,
• archiwizować zdjęcia,
• importować dane do CRM lub DMS,
• integrować dane z systemem dealerskim,
• pobierać hotspoty i linki video,
• zasilać własne narzędzia lub systemy administracyjne.

Aby uzyskać klucz API, skontaktuj się z supportem VirtualCar360. Klucz może zostać przypisany do jednej lokalizacji albo do wielu lokalizacji jako klucz grupowy.

Tak. Klucz API jest wymagany w zapytaniach do API oraz w adresie Playera, jeżeli Player ma pobierać dane z systemu VirtualCar360.

W API klucz przekazywany jest jako parametr query string key.

Przykład:

https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/WBA1234567890?key=TWOJ_KLUCZ_API

W Playerze klucz również przekazywany jest w adresie URL.

Przykład:

https://virtualcar360.pl/player/?vin=WBA1234567890&key=TWOJ_KLUCZ_API

Tak, ale wymaga to przygotowania klucza grupowego. Klucz grupowy może agregować dane z wielu kont lub lokalizacji VirtualCar360.

W celu konfiguracji klucza grupowego skontaktuj się z supportem VirtualCar360.

Dla bezpośrednich zapytań do API nie jest to zalecane. Najbezpieczniejszy model to wykonywanie zapytań przez backend klienta albo proxy serwerowe.

W przypadku Playera osadzanego przez iframe klucz jest przekazywany w adresie Playera.

Player jest osadzany za pomocą iframe.

Przykład:

<iframe
  src="https://virtualcar360.pl/player/?vin=WBA1234567890&key=TWOJ_KLUCZ_API"
  width="100%"
  height="600"
  frameborder="0"
  allowfullscreen
></iframe>

Nie. Player nie wymaga własnej integracji backendowej, jeżeli chcesz tylko osadzić gotową prezentację pojazdu. Wystarczy wkleić iframe z odpowiednim adresem.

Tak. Player może pobierać dane po numerze VIN.

Przykład:

https://virtualcar360.pl/player/?vin=WBA1234567890&key=TWOJ_KLUCZ_API

Tak. Player może pobierać dane po numerze rejestracyjnym.

Przykład:

https://virtualcar360.pl/player/?numberplates=WW4433E&key=TWOJ_KLUCZ_API

Nie zawsze. Player może automatycznie wyszukać najnowszą galerię po numerze VIN albo numerze rejestracyjnym. carId jest przydatny wtedy, gdy chcesz wskazać konkretną galerię.

Jeżeli przekazujesz vin albo numberplates, Player wybiera najnowszą dostępną galerię dla danego pojazdu.

Tak, jeżeli hotspoty są dostępne dla danej galerii. Hotspoty mogą oznaczać konkretne elementy pojazdu, takie jak reflektor, felga, rysa, uszkodzenie albo element wyposażenia.

Tak, jeżeli certyfikat jest dostępny i skonfigurowany dla danej galerii lub lokalizacji, Player może go prezentować jako część widoku pojazdu.

Tak, po odpowiedniej konfiguracji Player może wyświetlać sekcję Inne pojazdy. Do tego służy między innymi parametr ann_dealer_id.

Player 360 to wariant Playera przeznaczony do prezentacji płynnego obrotu pojazdu o 360 stopni.

Player 360 wykorzystuje większą liczbę klatek oraz szybsze tempo odtwarzania. W zależności od konfiguracji może wykorzystywać 180 albo 360 zdjęć.

Zwykły Player służy głównie do prezentacji galerii zdjęć, a Player 360 do płynnego obrotu samochodu.

Zdjęcia dla Playera 360 mogą być generowane na podstawie 4 albo 8 oryginalnych ujęć samochodu. Klatki pomiędzy ujęciami są generowane przez AI.

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

Powiększenie działa przez pinch zoom na urządzeniach dotykowych albo przez kółko myszy na desktopie.

Jeżeli użytkownik powiększa widok na klatce wygenerowanej przez AI, Player przewija samochód do najbliższej pozycji oryginalnego zdjęcia i wykonuje zoom na zdjęciu źródłowym.

Nie. Implementacja jest taka sama. Player 360 jest osadzany przez iframe i może korzystać z tych samych parametrów identyfikujących pojazd, takich jak vin, numberplates, carId i key.

Player obsługuje między innymi:

• key,
• carId,
• vin,
• numberPlates,
• numberplates,
• lang,
• autoplay,
• hudhide,
• bg,
• slide_mode,
• ann_dealer_id,
• ann_show_more,
• interior_fullscreen.

Do ustawienia języka służy parametr lang.

Przykład:

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

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

Do zmiany tła służy parametr bg.

Przykład:

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

Dla wartości HEX znak # należy zakodować jako %23.

Przykład:

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

Do sterowania HUD-em służy parametr hudhide.

Przykłady:

hudhide=-1

HUD zawsze widoczny.

hudhide=0

HUD niewyświetlany.

hudhide=5

HUD znika po 5 sekundach bez interakcji.

Do wyświetlenia sekcji Inne pojazdy użyj parametru ann_dealer_id.

Przykład:

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

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

Nie zawsze. Aby video było dostępne, należy skontaktować się z supportem VirtualCar360 i zgłosić chęć aktywacji tej funkcji.

Domyślne video przedstawia obrót samochodu o 360 stopni. Materiał trwa około 20 sekund i jest tworzony na podstawie 4 albo 8 zdjęć pojazdu.

Video jest zapisywane w systemie VirtualCar360 oraz na Vimeo. Na życzenie klienta może być również automatycznie przesyłane na konto YouTube klienta.

Tak. Automatyczne przesyłanie video na YouTube wymaga wcześniejszej konfiguracji i autoryzacji konta klienta.

Tak, jeżeli video jest dostępne dla galerii. Linki do filmu w systemie VirtualCar360, Vimeo i YouTube mogą być widoczne w Playerze.

Linki video mogą być dostępne w polu video zwracanym przez endpoint /image-set.

Pole video może być stringiem zawierającym JSON. Przed użyciem należy wykonać JSON.parse().

Przykład:

if (data.video) {
  const video = JSON.parse(data.video);

  console.log(video.vimeo);
  console.log(video.youtube);
}

Adres bazowy API:

https://img-out.virtualcar360.pl/api/v6.0/virtual-360

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/vin/WBA1234567890?key=TWOJ_KLUCZ_API

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/numberplates/WW4433E?key=TWOJ_KLUCZ_API

Po VIN:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/list/vin/WBA1234567890?key=TWOJ_KLUCZ_API&Sorting=-1&Page=1&PageSize=20

Po numerze rejestracyjnym:

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/list/numberplates/WW4433E?key=TWOJ_KLUCZ_API&Sorting=-1&Page=1&PageSize=20

Najpierw pobierz galerię po VIN albo numerze rejestracyjnym, a następnie użyj pola id jako carId w endpoincie /image-set.

GET https://img-out.virtualcar360.pl/api/v6.0/virtual-360/image-set?carId=10209937&key=TWOJ_KLUCZ_API

Endpoint /image-set może zwracać między innymi:

• id,
• vin,
• numberPlates,
• type,
• inspection,
• video,
• hotspots,
• carImageSets,
• carImageSets1080p.

Pole type opisuje techniczny standard zdjęć.

Przykład:

3000_2250_8_JPG_SKODAPLUS

Może oznaczać:

• szerokość zdjęcia,
• wysokość zdjęcia,
• liczbę zdjęć,
• format pliku,
• nazwę standardu zdjęć.

Sprawdź, czy:

• przekazano poprawny key,
• przekazano poprawny vin, numberplates albo carId,
• pojazd posiada galerię w systemie VirtualCar360,
• klucz API ma dostęp do właściwej lokalizacji,
• używasz właściwego środowiska.

Najczęściej oznacza to, że nie znaleziono galerii dla podanego VIN, numeru rejestracyjnego albo carId.

Sprawdź poprawność danych pojazdu oraz dostęp klucza API do właściwej lokalizacji.

Najczęściej oznacza to nieprawidłowe parametry zapytania. Sprawdź, czy wszystkie wymagane parametry są przekazane i mają poprawny format.

Błąd 500 oznacza błąd serwera. W takim przypadku skontaktuj się z supportem VirtualCar360 i przekaż szczegóły zapytania.

Możliwe przyczyny:

• funkcja video nie została aktywowana,
• video nie zostało jeszcze wygenerowane,
• galeria nie posiada materiału video,
• integracja YouTube nie została skonfigurowana,
• link YouTube nie jest dostępny dla danej galerii.

Możliwe przyczyny:

• galeria nie posiada hotspotów,
• hotspoty nie zostały oznaczone w systemie,
• aktualny widok Playera 360 pokazuje klatkę wygenerowaną przez AI,
• dana galeria nie obsługuje hotspotów.

Jeżeli Player działa po VIN albo numerze rejestracyjnym, wybiera najnowszą dostępną galerię. Jeżeli pojazd ma wiele galerii, wyświetlona może zostać ostatnio utworzona galeria.

Aby wskazać konkretną galerię, użyj carId.

Nie. W dokumentacji publicznej nie należy używać technicznych nazw takich jak VirtualCarControllerV albo VirtualCarControllerV2. Endpointy powinny być pogrupowane według funkcji biznesowej, na przykład:

• Wyszukiwanie galerii,
• Listowanie galerii,
• Najnowsza galeria,
• Zdjęcia,
• Ogłoszenia.

Tak. Nazwy sekcji w dokumentacji opisowej i w API Reference powinny być możliwie spójne. Ułatwia to użytkownikowi przechodzenie między opisem procesu integracji a szczegółami endpointów.

Każdy endpoint powinien zawierać:

• krótki opis zastosowania,
• listę parametrów,
• przykład zapytania,
• przykładową odpowiedź,
• możliwe kody błędów,
• informację, kiedy używać danego endpointu.

Skontaktuj się z supportem VirtualCar360, gdy:

• potrzebujesz klucza API,
• potrzebujesz klucza grupowego,
• chcesz aktywować video,
• chcesz skonfigurować YouTube,
• Player nie wyświetla galerii,
• API zwraca błąd serwera,
• pojazd nie jest znajdowany mimo poprawnych danych,
• potrzebujesz pomocy przy wdrożeniu produkcyjnym.

W zgłoszeniu warto podać:

• nazwę klienta lub lokalizacji,
• VIN albo numer rejestracyjny pojazdu,
• identyfikator carId, jeżeli jest znany,
• opis problemu,
• środowisko: testowe lub produkcyjne,
• fragment odpowiedzi API,
• zrzut ekranu,
• adres zapytania bez ujawniania pełnego klucza API.

Jeżeli chcesz szybko osadzić prezentację pojazdu, użyj Playera albo Playera 360. Jeżeli chcesz samodzielnie pobierać i przetwarzać dane, użyj API.

W przypadku braku danych, problemów z dostępem, konfiguracją video albo integracją YouTube skontaktuj się z supportem VirtualCar360.