XML Datafeeds Volledig geautomatiseerd advertenties plaatsen V 2.3 1-5-2014
Dit document beschrijft de XML datafeed specificatie voor Pro Accounts van AdvertentiePlanet. 1
AdvertentiePlanet is een onderdeel van EasyAds B.V.
2
Inhoudsopgave 1
Inleiding en doelstelling .................................................................................................................. 4
2
Beschikbaar stellen van een XML datafeed bestand....................................................................... 4
3
4
2.1
HTTP(S) protocol op eigen locatie ........................................................................................... 4
2.2
FTP protocol ............................................................................................................................ 4
2.3
Persoonlijke locatie ................................................................................................................. 4
XML datafeed instellen.................................................................................................................... 5 3.1
XML datafeed opgeven............................................................................................................ 5
3.2
Controleren ............................................................................................................................. 5
XML formaat .................................................................................................................................... 6 4.1
Voorbeeld XML datafeed......................................................................................................... 6
4.2
XML Elementen ....................................................................................................................... 7
5
Categorieën en eigenschappen ....................................................................................................... 9
6
FAQ en Support ............................................................................................................................. 10
3
AdvertentiePlanet.nl XML datafeeds 1 Inleiding en doelstelling Dit document beschrijft de wijze waarop XML feeds aangeleverd kunnen worden tbv automatsiche productfeed up-loads. Het format is vrij standaard en vergelijkbaar met staandaard productfeeds voor bijvoorbeeld Google Shopping of een prijsvergelijkingsite. De categorien en extented properties zijn reletief uitgebreid omdat AdvertentiePlanet aan de eisen van haar partners dient te voldoen om de publicatie bij de desbetreffende (ver)koops succesvol te laten verlopen. De XML feed zorgt voor de initiele upload en plaatsingen, daarna de dagelijkse synchronisatie. In het account zijn de publicatiekanalen en eventuele extra zaken zoals omhoogplaatingen te bedienen.
2 Beschikbaar stellen van een XML datafeed bestand Er zijn een drietal mogelijkheden om een datafeed bestand beschikbaar te stellen 1. Door middel van het beschikbaar stellen van de datafeed op eigen HTTP(S) locatie 2. Door middel van het beschikbaar stellen van de datafeed op eigen FTP locatie 3. AdvertentiePlanet stelt een locatie voor je beschikbaar Het instellen van de locatie en authenticatie dien je te doen via Instellingen -> Mijn Datafeeds.
2.1 HTTP(S) protocol op eigen locatie Als je de beschikking hebt over een eigen web locatie, is het mogelijk dat je je XML bestand beschikbaar stelt via het HTTP(S) protocol. Op gezette tijden zal onze service het bestand op de door jou opgegeven locatie uitlezen en de verschillende akties uitvoeren bij onze publishing partners. Door een beveiliging als HTTPS in te stellen weet je zeker dat de verschillende gegevens versleuteld verstuurd worden. Daarnaast is het mogelijk dat je op basis van het IP adres anderen uitsluit om het XML bestand op te vragen.
2.2 FTP protocol Als je de beschikking hebt over een eigen locatie die via FTP beschikbaar is, kun je je XML bestand daarop beschikbaar stellen. Je kunt op basis van het IP adres anderen uitsluiten om het XML bestand op te vragen. Onze service zal op gezette tijden het bestand downloaden en de verwerking van de data starten.
2.3 Persoonlijke locatie Mocht je niet de beschikking hebben over een eigen FTP of HTTP locatie dan zal AdvertentiePlanet een persoonlijke FTP locatie voor je beschikbaar kunnen stellen. Daar kun je vervolgens je XML bestand naar uploaden. Op een gezette tijd zal onze server het bestand uitlezen en de verschillende akties uitvoeren bij onze publishing partners. Als je gebruik wilt maken van deze service zullen wij de specifieke inloggegevens voor je aanmaken en je locatie voor je inrichten. Het enige wat je dient te doen is het periodiek uploaden van het bestand. 4
3 XML datafeed instellen Om je XML datafeed in te stellen heb je een AdvertentiePlanet Pro account nodig. Als je beschikt over een Pro account vind je onder ‘Instellingen’ een menu item ‘Mijn datafeeds’. Daar kan je je XML datafeed instellen voor periodieke verwerking.
3.1 XML datafeed opgeven Om je XML datafeed op te geven klik je op ‘Feed toevoegen’. Vervolgens kan je een naam opgeven voor de feed. Met deze naam kan je je feed makkelijk terug vinden wanneer je meerdere feeds hebt ingesteld. Daarna geef je de locatie op waar het XML datafeed bestand beschikbaar staat. Dit kan een HTTP of FTP locatie zijn.
3.2 Controleren Nadat je een feed hebt toegevoegd kun je deze valideren door op de link ‘valideren’ te klikken. Wanneer de feed fouten bevat zal dat weergegeven worden. Er kunnen twee typen fouten optreden. Kritieke fouten zijn fouten waarbij de structuur van de datafeed niet juist is en de feed in zijn geheel niet verwerkt kan worden. Gewone fouten zijn fouten binnen een enkele advertentie en zorgt ervoor dat die advertentie niet verwerkt kan worden. Daarnaast kunnen er ook waarschuwingen gegeven worden. Daarbij wordt je advertentie wel verwerkt maar zijn er verbeteringen wenselijk voor een betere plaatsing. Al je opgegeven feeds worden getoond in een overzicht met alle bijbehorende gegevens. Feeds die aangevinkt zijn hebben een blauwe achtergrond. Deze feeds zullen elke nacht verwerkt worden. Het is dus mogelijk je feed tijdelijk uit te schakelen. Als er links met fouten of waarschuwingen staan kun je daarop klikken om in een popup te zien welke fouten er in je XML datafeed zitten. De status van de feed zal elke keer nadat de feed verwerkt is worden ge-update. Om je feed direct opnieuw te laten controleren klik je op ‘valideren’. Je XML datafeed bestand wordt gecontroleerd met behulp van een XSD schema bestand. Dit bestand is te vinden op: http://advertentieplanet.nl/support/xsd
5
4 XML formaat 4.1 Voorbeeld XML datafeed
5123.6 Fixed Offered <Title>Test advertentie <WebsiteLink>www.sample.nl http://www.sample.com/one.png http://www.sample.com/two.png <ExtendedProperties> <ExtendedProperty id="78918"> <ExtendedPropertyValue id="457640" /> <ExtendedProperty id="78944"> <ExtendedPropertyValue id="457724" /> <ExtendedProperty id="91634"> <ExtendedPropertyValue id="598690" /> <ExtendedProperty id="81067"> <ExtendedPropertyValue>8 <ExtendedProperty id="81045"> <ExtendedPropertyValue id="472797" />
6
4.2 XML Elementen Naam AdvertentiePlanet
Omschrijving Dit is het hoofd element. De hele feed bevind zich binnen dit element Advertisements Dit element bevat alle advertenties van de adverteerder. Advertisement Dit element bevat alle informatie van een advertentie. Het attribuut ‘customerExternalId’ bevat je eigen ID van de advertentie en is verplicht. Description De volledige omschrijving van de advertentie. Plaats de omschrijving in een CDATA sectie zodat opmaak en karakters bewaard blijven. Price De prijs van de van het aangeboden object. Gebruik een punt als decimaal scheidings teken. Gebruik het getal 0 als de prijs niet van toepassing is. PricingType ‘Fixed’ = vaste prijs ‘Bid’ = bieden ‘Reserved’ = gereserveerd ‘Free’ = gratis ‘ToBeAgreed’ = nog overeen te komen ‘NotApplicable’ = niet van toepassing ‘Trade’ = ruilen ‘AnyReasonableOffer’ = elk aannemelijk bod Type ‘Offered’ = aangeboden ‘Wanted’ = gezocht Title De titel van de advertentie (max 50 karakters) WebsiteLink De website pagina van de adverteerder of de advertentie. Images Dit element bevat de locaties van alle foto’s van de advertentie. Image De URL locatie van een advertentie foto. Category Het attribuut ‘id’ bevat de ID van de categorie waarin geplaatst moet worden. Er is een lijst beschikbaar met alle ID’s van alle ondersteunde categorieën. ExtendedProperties Dit element bevat minimaal alle verplichte extra eigenschappen die nodig zijn voor het plaatsen in de gekozen categorie. ExtendedProperty Het attribuut ‘id’ bevat de ID van de eigenschap die bij de categorie hoort. Het ‘id’-attribuut mag ook de naam van de property bevatten in plaats van de ID. ExtendedPropertyValue Het attribuut ‘id’ bevat de ID van de eigenschap waarde indien beschikbaar. In het geval van een tekst of getal eigenschap plaats je de waarde in dit element. Het ‘id’7
Aantal 1
Verplicht Ja
1
Ja
Onbeperkt Ja
1
Ja
1
Ja
1
Ja
1
Ja
1
Ja
1
Nee
1
Nee
20 1
Nee Ja
1
Ja
Onbeperkt Afhankelijk van de gekozen categorie Onbeperkt Ja
attribuut mag ook de naam van de property bevatten in plaats van de ID.
8
5
Categorieën en eigenschappen
AdvertentiePlanet heeft ruim 2000 verschillende categorieën waarin advertenties geplaatst kunnen worden. Elke categorie heeft specifieke eigenschappen die bij die categorie horen. Sommige eigenschappen hiervan zijn verplicht. Elke eigenschap is van een bepaald type:
Tekst eigenschappen kunnen tekenreeksen bevatten. Bijvoorbeeld ‘Merk’ of ‘Type’ Getal eigenschappen kunnen getallen bevatten. Bijvoorbeeld ‘Aantal’ of ‘Levertijd’ Enkele-keuze eigenschappen kunnen één van de mogelijke waarden bevatten. Bijvoorbeeld ‘Brandstof’ of ‘Conditie’ Meerdere-keuzes eigenschappen kunnen een of meerdere van de mogelijke waarden bevatten. Bijvoorbeeld ‘Extras’ of ‘Regio’
Sommige getal eigenschappen worden beperkt met een minimum en maximum waarde. Tekst en getal eigenschappen worden als inhoud van een ExtendedPropertyValue element meegegeven. <ExtendedProperty id="76847"> <ExtendedPropertyValue>2342
In plaats van de ID kan ook de naam meegegeven worden van het desbetreffend attribuut. Het volgende voorbeeld demonstreert dit: <ExtendedProperty id="Kilometerstand"> <ExtendedPropertyValue>2342
Van enkele-keuze en meerdere-keuze eigenschappen worden de ID’s van de waarden meegegeven als attribuut van het ExtendedPropertyValue element. <ExtendedProperty id="66245"> <ExtendedPropertyValue id="332065" /> <ExtendedPropertyValue id="332074" />
Ook voor het bovenstaand voorbeeld geldt dat in plaats van een ID de naam van de desbetreffende ExtendedPropertyValue meegegeven kan worden. Het volgend voorbeeld demonstreert dit: <ExtendedProperty id="Veiligheid"> <ExtendedPropertyValue id="ABS" /> <ExtendedPropertyValue id="Airbag" />
Een overzicht van ID’s van alle beschikbare categorieën, eigenschappen en waarden is te vinden op: http://advertentieplanet.nl/support/categorieen
9
6
FAQ en Support
Er zitten fouten in mijn xml: Bij de validatie in het account krijg je specifieke foutmeldingen
Er zitten waarschuwingen in mijn xml: Sommige zaken, bv het plaatsen van url’s in de omschrijving, zijn niet toegestaan
Voor vragen of opmerkingen kun je contact opnemen met onze technical support afdeling; 088 4800 800 tijdens kantooruren. Of mail naar
[email protected]
10
