Instrukcja integracji z porównywarką cen Radar.pl Ostatnia modyfikacja: 2007-09-19 16:12 o2.pl Spółka z o.o. ul. Jutrzenki 177 02-231 Warszawa NIP: 521-31-11-513 REGON: 016366823 KRS 0000140518, Sąd Rejonowy dla m.st. Warszawy Kapitał zakładowy: 308.250,00 zł Ostatnia modyfikacja: 2007-09-19 16:12 Strona 1 / 10
Spis treści: I. Informacje ogólne Instrukcja integracji z porównywarką cen Radar.pl 1. Zasady funkcjonowania systemu 2. Istniejące rozwiązania sklepowe 3. Samodzielna integracja z systemem Radar.pl II. Specyfikacja techniczna protokołu Radar XML 1. Struktura przykładowego pliku XML 2. Opis i specyfikacja dostępnych pól w pliku XML 3. Najczęstsze błedy popełniane podczas tworzenia plików XML 4. Uaktualnianie danych znajdujących się w bazie produktów 5. Kodowanie znaków znajdujących się w plikach XML III. Informacje dodatkowe 1. Mapa kategorii systemu Radar.pl w formacie XML Ostatnia modyfikacja: 2007-09-19 16:12 Strona 2 / 10
1. Informacje ogólne Zasady funkcjonowania systemu Podczas tworzenia porównywarki cen Radar.pl naszym przyświecał nam jeden cel stworzenie systemu, który będzie wymagał jak najmniejszego nakładu ludzkiej pracy, a co za tym idzie, skrócenie czasu oczekiwania na wprowadzenie nowych klientów do bazy danych. Dzięki temu jesteśmy pierwszym na rynku serwisem, w którym czas dodania nowych ofert od momentu rejestracji nie przekracza dwóch dni! Wszystko za sprawą wyspecjalizowanego systemu, który podczas działania potrafi trafnie decydować o powiązaniach kategorii klienta z naszymi. Bez jakiejkolwiek ingerencji ze strony człowieka! Zasada działania jest bardzo prosta: użytkownik wypełnia poprawnie formularz rejestracyjny dostępny pod adresem http://www.radar.pl/rejestracja a następnie aktywuje założone konto, klikając na link aktywacyjny przesłany na adres e-mail podany podczas rejestracji, odrazu po aktywacji konta, użytkownik otrzymuje dostęp do Panelu Sprzedawcy znajdującym się pod adresem http://www.radar.pl/vn7n6v2/. Od tego momentu ma on pełny dostęp do informacji o własnej firmie oraz funkcjonujących w jej ramach sklepach internetowych. Po zalogowaniu się do Panelu Sprzedawcy, użytkownik może przystąpić do dodawania nieograniczonej ilości nowych sklepów! Aby oferty znajdujące się w sklepie użytkownika były widoczne, musi on udostępnić swoją ofertę w formacie Radar XML szczegółowo opisanym w dalszej części tego dokumentu. Bardzo ważnym jest, aby oferta sklepu udostępniona była publicznie oraz w przypadku korzystania z własnych rozwiązań aby umieszczony w niej dane dostępne były w sposób ciągły, tj. aby połączenie z serwerem WWW nie podlegało kontroli ze strony oprogramowania typu firewall. W przypadku specyficznych rozwiązań, prosimy o kontakt z naszymi specjalistami pod adresem integracja@radar.pl. Po pierwszej udanej integracji z bazą danych oraz wstępnym przypisaniu kategorii przez nasz system, nasi specjaliści rozpoczynają tworzenie powiązań kategorii pomiędzy sklepem klienta a kategoriami znajdującymi się w naszej bazie. Dodatkowo w przypadku błędnego przypisania kategorii przez system, moderatorzy tworzą nowe, poprawne powiązania. Szczegółowe informacje na temat powiązań widoczne są na bieżąco w Panelu Sprzedawcy. W przypadku jakichkolwiek uwag bądź sugestii, prosimy o kontakt z naszymi specjalistami pod adresem integracja@radar.pl. Ostatnia modyfikacja: 2007-09-19 16:12 Strona 3 / 10
Istniejące rozwiązania sklepowe Instrukcja integracji z porównywarką cen Radar.pl W celu przyspieszenia procesu integracji, użytkownicy korzystający z gotowych rozwiązań sklepowych mogą użyć istniejących i sprawdzonych rozwiązań, które automatyzują dodawanie produktów do naszej bazy danych. Współpracujemy z następującymi dostawcami oprogramowania sklepowego: GoShop.pl IAI-System.com KQS.pl Netcart.pl SOTE.pl Triger.com.pl Jeżeli jednak jesteś użytkownikiem platformy oscommerce, w Panelu Sprzedawcy systemu Radar.pl umieściliśmy opcję dedykowaną temu rozwiązaniu: Rys 1.1: Panel sprzedawcy, pozycja Integracja z systemem. Wybierając pozycję Radar XML wtyczka oscommerce otrzymasz możliwość pobrania skryptu, generującego poprawny plik XML z ofertą sklepu korzystającego z platformy oscommerce. Wszelkie instrukcje dotyczące instalacji oraz konfiguracji wtyczki dołączone są do pliku pomocy znajdującego się w archiwum ZIP wraz z kodem źródłowym wtyczki. Samodzielna integracja z systemem Radar.pl Dla wszystkich zaawansowanych użytkowników, pod adresem http://www.radar.pl/integracja przygotowaliśmy przykładowy skrypt PHP generujący poprawny plik XML z ofertą sklepu bez względu na zastosowaną budowę bazy danych. Staraliśmy się opisać kod źródłowy wspomnianego skryptu tak, aby każdy bez większych problemów poradził sobie z jego personalizacją. W przypadku jakichkolwiek uwag, sugestii, bądź problemów prosimy o kontakt z naszymi specjalistami pod adresem integracja@radar.pl. Ostatnia modyfikacja: 2007-09-19 16:12 Strona 4 / 10
2. Specyfikacja techniczna protokołu Radar XML Struktura przykładowego pliku XML Poniższy plik XML zawiera dwie przykładowe oferty, zawierające dane które z pewnością zostaną poprawnie dodane do systemu Radar.pl: <?xml version="1.0" encoding="utf-8"?> <radar wersja="1.0"> <oferta> <produkt> <grupa1> <nazwa><![cdata[f.e.a.r.]]></nazwa> <producent><![cdata[cd PROJEKT]]></producent> <opis><![cdata[f.e.a.r. to doskonałe połączenie gry akcji z intrygującą fabułą rodem z najpopularniejszych azjatyckich horrorów(...)]]> </opis> <id>1234</id> <url>http://sklep.pl/oferta1234.html</url> <foto>http://sklep.pl/zdjecia/1234.jpg</foto> <kategoria> Gry i Konsole / Komputerowe PC / Akcja </kategoria> <cena>52.00</cena> <dostepnosc>1-2 dni</dostepnosc> <promocja></promocja> </grupa1> </produkt> <produkt> <grupa1> <nazwa><![cdata[myst V: KONIEC WIEKÓW (GRA PC)]]></nazwa> <producent><![cdata[cenega]]></producent> <opis><![cdata[zdecyduj o losie cywilizacji w ostatnim, niepowtarzalnym rozdziale sagi Myst(...)]]> </opis> <id>1235</id> <url>http://sklep.pl/oferta1235.html</url> <foto>http://sklep.pl/zdjecia/1235.jpg</foto> <kategoria> Gry i Konsole / Komputerowe PC / Akcja </kategoria> <cena>44.00</cena> <dostepnosc>1-2 dni</dostepnosc> <promocja>mousepad gratis!</promocja> </grupa1> </produkt> </oferta> </radar> Ostatnia modyfikacja: 2007-09-19 16:12 Strona 5 / 10
Opis i specyfikacja dostępnych pól w pliku XML Instrukcja integracji z porównywarką cen Radar.pl Budowa pliku XML wykorzystywanego w ramach protokołu Radar.pl uwzględnia następujące pola oraz obowiązujące w nich wartości: Nazwa pola <nazwa> * obowiązkowe <producent> * obowiązkowe <opis> * nieobowiązkowe Specyfikacja pole to definiuje nazwę produktu oferowanego przez sklep. Podczas analizy, nazwy produktów są normalizowane do postaci przystępnej dla użytkowników serwisu Radar.pl w przypadku, gdy system będzie zmuszony do utworzenia nowego produktu w systemie, nazwa MYST V: KONIEC WIEKÓW (GRA PC) automatycznie zamieniona zostanie na Myst V: Koniec Wieków (Gra PC) w polu tym znajdować się może dowolny ciąg znaków, spełniający standard XML 1.1. Zalecane jest otaczanie podawanych w nim wartości tagiem <![CDATA[WARTOŚĆ]]>, oraz zamiana znaków takich jak <, >, '', ' na ich odpowiedniki HTML. pole to definiuje nazwę producenta produktu oferowanego przez sklep. Podczas analizy, nazwy produktów są normalizowane do postaci przystępnej dla użytkowników serwisu Radar.pl w przypadku, gdy system będzie zmuszony do utworzenia nowego produktu w systemie, nazwa CD PROJEKT automatycznie zamieniona zostanie na CD Projekt w polu tym znajdować się może dowolny ciąg znaków, spełniający standard XML 1.1. Zalecane jest otaczanie podawanych w nim wartości tagiem <![CDATA[WARTOŚĆ]]>, oraz zamiana znaków takich jak <, >, '', ' na ich odpowiedniki HTML. pole to definiuje opis produktu oferowanego przez sklep. Podczas analizy, pole to jest czyszczone jest ze wszystkich tagów HTML. w polu tym znajdować się może dowolny ciąg znaków, spełniający standard XML 1.1. Zalecane jest otaczanie podawanych w nim wartości tagiem <![CDATA[WARTOŚĆ]]>, oraz zamiana znaków takich jak <, >, '', ' na ich odpowiedniki HTML. Ostatnia modyfikacja: 2007-09-19 16:12 Strona 6 / 10
Nazwa pola <id> * nieobowiązkowe <url> * obowiązkowe Specyfikacja pole to definiuje unikalny identyfikator produktu w ramach jednego sklepu. Każdy produkt znajdujący się w ofercie jednego sklepu powinien posiadac inny numer lub kod id. w polu tym znajdować się może dowolny alfanumeryczny ciąg znaków, spełniający standard XML 1.1. Zalecane jest otaczanie podawanych w nim wartości tagiem <![CDATA[WARTOŚĆ]]>, oraz zamiana znaków takich jak <, >, '', ' na ich odpowiedniki HTML. Wszystkie znaki nie znajdujące się w zbiorze 0-9, A - Z (a z) zostają odfiltrowywane podczas procesu integracji. pole to definiuje adres url do oferty znajdującej się w sklepie użytkownika. adresy url znajdujące się w tym polu powinny zaczynać się członem http://. Dodatkowo, jeżeli w adresie znajduje się znak &, należy zamienić go na zgodną ze standardem XML 1.1 encję & bądź otaczanie całego adresu url tagiem <![CDATA[WARTOŚĆ]]>. <foto> * nieobowiązkowe Poprawne wartości: <![CDATA[http://www.sklep.pl/adres.php?id=1234&s=7]]> http://www.sklep.pl/adres.php?id=1234&s=7 pole to definiuje adres url do zdjęcia przedstawiającego oferowany produkt. Zdjęcie powinno być udostępnione w rozdzielczości wyższej niż 115x85 pikseli (mniejsze obrazy są ignorowane w procesie integracji). Jest to jedyne pole, które może zostać użyte wielokrotnie w zakresie jednego produktu (wszystkie obrazy zostaną pobrane na nasze serwery oraz dostosowane do obowiązującego w Radar.pl formatu). adresy url znajdujące się w tym polu powinny zaczynać się członem http://. Dodatkowo, jeżeli w adresie znajduje się znak &, należy zamienić go na zgodną ze standardem XML 1.1 encję & bądź otaczanie całego adresu url tagiem <![CDATA[WARTOŚĆ]]>. Poprawne wartości: <![CDATA[http://www.sklep.pl/obraz.php?id=1234&s=7]]> http://www.sklep.pl/obraz.php?id=1234&s=7 http://www.sklep.pl/obrazy/1234.jpg Ostatnia modyfikacja: 2007-09-19 16:12 Strona 7 / 10
Nazwa pola <kategoria> * obowiązkowe Specyfikacja pole to definiuje nazwę kategorii do której należy oferta (w ramach danego sklepu). Wartości w tym polu są bardzo ważne na poziomie automatycznej integracji z systemem (im większe podobieństwo nazw kategorii sklepu do nazw kategorii znajdujących się w Radar.pl, tym szybciej zostanie przeprowadzona integracja z naszą bazą danych). w polu tym znajdować się może dowolny alfanumeryczny ciąg znaków, spełniający standard XML 1.1. Zalecane jest otaczanie podawanych w nim wartości tagiem <![CDATA[WARTOŚĆ]]>, oraz zamiana znaków takich jak <, >, '', ' na ich odpowiedniki HTML. Wszystkie znaki nie znajdujące się w zbiorze 0-9, A - Z (a z) oraz / zostają odfiltrowywane podczas procesu integracji. Dodatkowo, bardzo ważne jest oddzielanie poszczególnych poziomów kategorii znakiem / (wyznacznikiem jest najczęściej ostatni człon kategorii, znajdujący się po ostatnim znaku / ). Poprawne wartości: <![CDATA[Muzyka / Gatunki / Blues, Rhythm'n'Blues]]> Gry i Konsole / Komputerowe PC / Akcja <cena> * obowiązkowe Niepoprawne wartości: <![CDATA[Muzyka > Gatunki > Blues, Rhythm'n'Blues]]> Gry i Konsole < Komputerowe PC < Akcja pole to definiuje cenę brutto oferowanego przez sklep produktu. Jest to cena, jaka będzie widniała w naszej porównywarce cenowej. w polu tym znajdować się może dowolna liczba zmiennoprzecinkowa, przedstawiająca końcową cenę oferowaną przez dany sklep. Wszelkie wartości nieliczbowe są ognorowane przez system integracji i sprowadzane do wartości 0. W wartości znajdować się może tylko jedna kropka (dzieląca wartości złotych od wartości groszy ). Wszystkie przecinki przed kropką są usuwane podczas procesu integracji z systemem. Poprawne wartości: 1234.55 1,234.55 Niepoprawne wartości: Wszystkie, różniące się od wyżej prezentowanych. Ostatnia modyfikacja: 2007-09-19 16:12 Strona 8 / 10
Najczęstsze błędy popełniane podczas tworzenia plików XML Zdarza się, że pomimo poprawnego wypełnienia opisanych powyżej pól, nowo dodane produkty przedstawione są w sposób niezgodny z zamierzeniem użytkownika. Poniżej opisujemy najczęściej popełniane błędy oraz sposoby ich rozwiązania. 1. Po kliknięciu na przycisk Powiększ wyświetlany obraz jest o wiele mniejszy niż wskazany przezemnie w pliku XML Zdjęcia pobierane z adresów wskazanych przez naszych klientów pobierane są podczas procesu integracji a następnie przetwarzane tak, aby powiększenie nie było większe niż 400 x 300 pikseli. Jest to wymuszone potrzebą ujednolicenia wymiarów wszystkich zdjęć i uniknięciem błędnego wyświetlania stron produktu u użytkowników posiadających rozdzielczości ekranu mniejsze niż 1024 x 768 pikseli. Często jednak zdarza się, że użytkownicy umieszczają w plikach XML jednocześnie adresy do miniatur i pełnych zdjęć co jest niepoprawnym rozwiązaniem. Zautomatyzowany system integracji jako domyślne zdjęcie wskazuje to, które umieszczone jest w pliku XML jako pierwsze (w kontekście produktu). Jeżeli w pliku z ofertami jako pierwszy umieszczony jest adres do miniatury a jako drugi adres do obrazu w pełnej rozdzielczości, oba zdjęcia zostaną dodane do naszego systemu, lecz jako domyślna przypisana zostanie miniatura. Rozwiązaniem tego problemu jest albo usunięcie z pliku XML adresów prowadzących do miniatur (są one całkowicie zbędne), albo umieszczanie w nim w pierwszej kolejności adresów prowadzących do zdjęć w pełnej rozdzielczości. Poprawnie: <foto>http://sklep.pl/zdjecia/1235_full.jpg</foto> <foto>http://sklep.pl/zdjecia/1235_miniatura.jpg</foto> Niepoprawnie: <foto>http://sklep.pl/zdjecia/1235_miniatura.jpg</foto> <foto>http://sklep.pl/zdjecia/1235_full.jpg</foto> 2. Opisy umieszczonych przezemnie produktów nie posiadają dodanego przezemnie formatowania tekstu przez co tabele są całkowicie rozsypane! Podczas procesu integracji wszystkie dane zapisywane w naszej bazie są upraszczane do postaci niesformatowanego tekstu, tj. usuwane są wszystkie tagi zarówno (X)HTML jak i JavaScript. Jest to wymuszone kwestiami bezpieczeństwa i zapewnieniem z naszej strony użytkownikom jednolitego wyglądu strony każdego produktu. Naszą sugestią jest nieumieszczanie w polu <opis> tekstu liczącego więcej niż 300 znaków. Dodatkowo prosimy o zachowanie maksimum wartości merytorycznej w umieszczanych opisach produktów. Ostatnia modyfikacja: 2007-09-19 16:12 Strona 9 / 10
Uaktualnianie danych znajdujących się w bazie produktów Podczas każdorazowej analizy produktów, nasz system sprawdza udostępnione przez sklepy oferty w poszukiwaniu zmian wartości pól oznaczonych jako obowiązkowe (patrz tabela powyżej). W naszej bazie przechowywana jest suma kontrolna oparta o dane znajdujące się w tych polach i jeżeli którakolwiek z wartości różni się od tych zapisanych w naszej bazie, oferta jest automatycznie aktualizowana. Kodowanie znaków znajdujących się w plikach XML Ogólnie przyjętym i najlepiej obsługiwanym kodowaniem plików Radar XML jest UTF8. Stosując je masz stuprocentową pewność, że po zakończeniu integracji, nazwy oferowanych przez Ciebie produktów będą wyświetlane poprawnie. W przypadku zastosowania innego kodowania (ISO 8859-2, Windows 1250), system integracji dokonuje konwersji znaków do ich odpowiedników w UTF8. Ważnym jest, aby rodzaj kodowania zaznaczony był w nagłówku pliku XML, tj: <?xml version="1.0" encoding="utf-8"?> dla kodowania pliku w standardzie UTF8, <?xml version="1.0" encoding="iso-8859-2"?> dla kodowania pliku w standardzie ISO 8859-2, <?xml version="1.0" encoding="windows-1250"?> dla kodowania pliku w standardzie Windows, itd. 3. Informacje dodatkowe Mapa kategorii systemu Radar.pl w formacie XML Pod adresem http://www.radar.pl/sitemaps/radar.categories.tree.xml przygotowaliśmy dla Państwa plik XML zawierający kompletną, codziennie aktualizowaną mapę kategorii wchodzących w skład systemu Radar. Korzystanie ze znajdujących się tam nazw kategorii przyspiesza szybkość integracji sklepów z naszą bazą danych oraz dodatkowo zapewnia ponad 95% szansę na trafne przypisanie kategorii już podczas procesu integracji. Ostatnia modyfikacja: 2007-09-19 16:12 Strona 10 / 10