Affiliate program - technische beschrijving.
Hier vindt u informatie voor het inbouwen van het Affiliate program van euro-boek.nl in het design van uw eigen website.
Vragen kunt u stellen aan db.dev@euro-boek.nl.
Wat is het euro-boek.nl Affiliate program?
- Het laat zoekvragen van Euro-boek in XML- of CSV-formaat toe.
- Daardoor kunt u de Euro-boek boekengegevens in uw eigen stijl op uw eigen homepage weergeven en een bestellink aanbieden.
- Voorbeeld van hoe de resultaten weergegeven kunnen wordenn (ISO-8859-1 Zeichensatz)
- voorbeeld van hoe het resultaat weergegeven kan worden (UTF-8 Zeichensatz)
- Voorbeeld van een realisering
Uw voordeel
- U profiteert van de zoeksnelheid van euro-boek.nl
- U profiteert van de momentaan 150 miljoen doorzochte boeken die in euro-boek.nl bevat zijn.
- U profiteert van het aandeel van t/m 30% van de omzet van verkochte boeken.
- U kunt de boek gegevens van euro-boek.nl verder verwerken zoals u het wilt en tevens extra diensten, die op euro-boek.nl niet voorhanden zijn, aan de gebruikers aanbieden.
Wat moet u doen?
- Om de Euro-boek.nl zoekresultaten op uw website te zien, moet uw webprogrammeur een programma schrijven dat onze boekgegeven per XML of CSV oproept.
-
Dit programmeerwerk kost niet meer moeite (meestal minder) dan het zoeken en presenteren van de zoekresultaten van de boekengegevens van uw eigen boeken op uw website (ingeval u die reeds aanbiedt).
Alles bij elkaar genomen kost het programmeren weinig moeite. -
Op deze webpagina geven we uw programmeur goede tips en fragmenten van de source code in PHP, die het programmeren van het opvraag-program behoorlijk vergemakkelijken.
Vragen hierover dient u te richten aan db.dev@euro-boek.nl. - Hieronder worden er een eenvoudig en een iets complexer voorbeeld gegeven, dat u ook kunt downloaden. Hiermee kunt u een zoekopdracht op de allereenvoudigste manier in uw website integreren. Deze voorbeeld-programma's zijn door uw programmeurs ook makkelijk te modificeren, zodat u ze aan uw eigen layout en functionaliteit kunt aanpassen.
Hoe werkt het?
- U vraagt bij ons om een gebruikersnaam en een paswoord voor het Affiliate program.
- U test deze door het oproepen van de opvraag-URL op onze website (zie beneden).
- Uw programmeur leest deze pagina's door en implementeert de zoekopdrachten naar uw wensen.
- Klaar.
- Aanmelding voor het Affiliate program..
- Voorbeeld van een realisering
- Tools downloaden in ZIP-archief (3KB)
Technische vragen indienen bijdb.dev@euro-boek.nl gericht te worden.
Informatie voor uw programmeur
Wij gebruiken de volgende begrippen:
- Affiliate-website: De website van onze Euro-boek.nl Affiliates, d.w.z. uw Website of de Website waarin u als programmeerder de zoekfunctie wilt inbouwen.
- Boekenplatformen: Dit zijn de webstekken, die Euro-boek.nl hun boekengegevens ter beschikking stellen (b.v. z.B. Amazon, Antbo, Booklooker, Abebooks etc.)
- Gebruiker: Dit is de gebruiker van de Affiliate webstek , die b.v. een boek zoekt , de gegevens invoert en dan de resultaten wil zien
Wat moet ik doen?
Het centrale punt is deze URL:
https://www.euro-boek.nl/extreq/meta/extquery.php?platform=<Your Username>& password=<Your Password>&author=<Autor>&title=<Titel> &search=<Schluesselwort>&isbn=<ISBN>&&mediatype=0&clientip=<Enduser-IP-Adresse>&format=xml
Als u deze URL in een browser (b.v. IE) oproept(usernaam en paswoord krijgt u van ons dan wel van de Affiliate) en bij
u ziet hier XML-output(meer over het XML-formaat vindt u onder https://www.w3c.org/XML/) van de zoekresultaten die Euro-boek over de auteur "Holl" en de titel "Jesus" gevonden heeft. Als u nog geen ervaring met XML-formaten heeft, hoeft u niet verward te zijn door de massa aan informatie, die bij w3c.org gegeven wordt, het is lang niet zo gecompliceerd als het er uit ziet. Als u de programmeertaal PHP op de site gebruikt, kunt u de in PHP ingebouwde XML-parser gebruiken om onze XML-output in te lezen. Andere programmeertalen(Perl, Phyton, ASP etc.) hebben eveneens ingebouwde XML-parsers, die veel van het werk voor u doen en de data die wij u sturen als passende variabelen doorgeven. De output is in de ISO-8859-1 (Westeuropa, latin1) tekenvoorraad. Met "&format=xml8" kunt u de data in de internationale UTF-8 tekenvoorraad laten uitgeven. In dit geval moet ook de output van de data(auteur, titel, ...) in UTF-8 gecodeerd zijn! Als het XML-formaat (dat wij echter aanraden) niet naar uw smaak is, kunt u de gegevens ook per CSV opvragen, door aan het eind i.p.v. "&format=xml" eenvoudig "&format=csv" aan te geven. Dat ziet er dan ongeveer zo uit (Hier zijn nieuwe regels met inleidende spaties voor de betere leesbaarheid ingevoegd):
231932123 16079133 ~||~ Holl, Adolf ~||~ Jesus in schlechter Gesellschaft ~||~ Wien : Buchgemeinschaft Donauland; Stuttgart : Europ. Bildungsgemeinschaft; [1972]; 21 cm; 215 S.; Aufl.: Lizenzausgabe; Leinen, Schutzumschlag, gut; ~||~ ~||~ 1972 ~||~ 8.00 ~||~ EUR ~||~ 8.00 ~||~ A ~||~ SFB1050 ~||~ https://www.euro-boek.nl/extreq/meta/bestellung.php?qid=16079133 ~||~ ~||~ ~||~ ~||~ ~||~ ~||~ Booklooker.de 16079134 ~||~ Holl, Adolf ~||~ Jesus in schlechter Gesellschaft. (Was Menschen bewegt). ~||~ 190 S. 21,5 cm. Gebunden. 318gr. Kreuz, ~||~ 3783118166 ~||~ 0 ~||~ 7.45 ~||~ EUR ~||~ 7.45 ~||~ D ~||~ Laetare Büchermarkt ~||~ https://www.euro-boek.nl/extreq/meta/bestellung.php?qid=16079134 ~||~ https://www.booklooker.de/images/cover/user_thumb/0309/0803/bl1060.jpg ~||~ 0 ~||~ 1 ~||~ 0 ~||~ 0 ~||~ Booklooker.de ...
Er worden exact dezelfde gegevens als in XML doorgegeven, alleen wordt er per boek één regel getoond en de velden worden met "~||~" gescheiden.
De volgende data worden in het XML (of CSV) bestand aangegeven:
- id: Dit is een uniek nummer voor ieder boek in ons datenbestand. Dit nummer blijft ongeveer drie uur lang geldig, daarna wordt het boek uit ons datenbestand geschrapt.
- author: Auteur van het boek
- title: Titel van het boek
- comment: Commentaar bij het boek. Kan zeer lang zijn.
- isbn: ISBN-Nummer van het boek, kan ook leeg zijn, dit attribuut wordt dan niet vermeld.
- year: Jaar van verschijnen
- price: Prijs van het boek
- currency: Valuta waarin de prijs aangegeven is.
- priceeur: Prijs van het boek omgerekend in Euro. Als de "currency" niet EUR is wordt "priceeur" met de dagprijs van de euro aangegeven. Veel boekplatformen geven hun prijzen in US$ aan, deze worden dan door ons in de dagprijs voor EUR omgerekend. De EUR prijs is in dit geval een "ca." prijs.
- country: Het land waarin het boek zich concreet bevindt. Wordt weergegeven met de landencodes (b.v. "D" voor Duitsland, "A" voor Oostenrijk enz.). Niet altijd zijn deze codes correct, omdat de boekenplatformen fouten maken, de codes niet vermelden of er zelf niet van op de hoogte zijn.
- dealer: De naam van de handelaar. Bij veel boekenplatformen leeg of hetzelfde als de naam van het platform.
- url: Dit is de URL, waar het boek besteld of gedetailleerd bekeken kan worden. De hier gegeven link blijft ongeveer drie uur lang geldig, daarna wordt het gezoche boek uit ons datenbestand geschrapt en de link functioneert niet meer.
- picurl: Dit is een link naar een overzichtplaatje (deze kan ook leeg zijn of geheel afwezig). Dit overzichtsplaatje is meestal zo klein, dat het in de boekenlijst getoond kan worden. Deze link verbindt dus in de regel niet met Euro-boek.nl, maar met een server van het boekenplatform waar het boek vandaan komt.
- paperback: Is een Ja/Nee-waarde(0=Nee, 1= Ja), die aangeeft of het boek een pocket is of niet.
- hardcover: Ja/Nee-waarde(0=Nee, 1= Ja), of het boek gebonden is of niet.
- signed: Ja/Nee-waarde(0=Nee, 1= Ja), of het boek gesigneerd is of niet.
- firstedition: Ja/Nee-waarde(0=Nee, 1= Ja), of het boek een eerste oplage is of niet.
- platform: De naam van het boekenplatform, waarvan de gegevens afkomstig zijn.
Vergeet niet, dat wij in de toekomst zowel het XML als ook het CSV-formaat kunnen uitbreiden. Er kunnen bij het XML formaat attributen, bij het CSV formaat aan het einde van regels extra velden worden toegevoegd. Het is belangrijk dat uw programma's daarmee kunnen omgaan, anders is hun functioneren op termijn niet zeker.
Een geval op zichzelf is de "id", die in het CSV-formaat in de eerste regel doorgegeven wordt, maar in het XML-formaat als attribuut van "ResultList". De ID die hier doorgegeven wordt staat uitsluitend voor de aan Euro-boek gegeven zoekopdracht, die wij "Zoek-ID" noemen.
Als programmeur doet u het volgende:
- U maakt een zoekformulier dat min of meer met ons zoekformulier overeenkomt (Velden voor auteur/titel/trefwoord en ISBN). Het layout van het zoekformulier kunt u zelf bepalen.
- Dit formulier stuurt u naar een resultaten-pagina.
- Op deze resultaten-pagina roept u onze URL op (extquery.php) en geeft deze de door de gebruiker ingegeven waarden als parameters door.
- U parst nu onze resultaten.pagina en schrijft de resultaten in een datenbestand.(b.v. de gratis en vrij toegankelijke mySQL datenbank). Houdt de "Zoek-ID" vast, ook in het datenbestand, zodat u bij een nieuwe oproep van de resultaten-pagina (b.v. bij het bladeren) Euro-boek.nl niet opnieuw hoeft op te roepen, maar de in het datenbestand voorlopig opgeslagen resultaten kunt bekijken. Deze voorlopig opgeslagen resultaten kunt u met willekeurig gekozen criteria sorteren en tonen.
- Na zekere tijd (op zijn laatst na drie uur) verwijdert u de voorlopige resultaten weer uit het datenbestand.
Denk eraan, dat u niet steeds bij aanvragen (extquery.php) bij het opbouwen van een nieuwe pagina een nieuwe aanvraag oproept. Dat heeft namelijk ten gevolge, dat u opnieuw een nieuwe zoek-id (en daarmee volslagen nieuwe Boek-ids) toegewezen krijgt. Wij kunnen ook niet garanderen, dat de resultaten bij iedere oproep van extquery.php in dezelfde volgorde aankomen, dat hangt onder andere van de snelheid van de deelnemende servers af (en dat zijn er veel, o.m. die van de boekenplatformen zelf) af. De verhouding van bestelclicks tot zoekclicks die u dan krijgt is beduidend slechter, hetgeen ons weer opvalt, zodat de winstparticipatie van de Affiliate-website aan onze website vermindert. Een oproep van extquery.php dient overeen te komen met een zoekopdracht bij u.
Voor de volgende problemen bieden wij u hier in beginsel oplossingen in de programmeertaal PHP:
PHP heeft een eigen ingebouwde XML-parser (zie http://www.php.net/manual/de/ref.xml.php)
U kunt heel eenvoudig
function xml_startElement($parser, $name, $attrs)
{
if($name=="RESULTLIST") {
print "SUCH-ID: ".$attrs["ID"]."<br><hr>";
} else if($name=="BOOK") {
print "ID: ".$attrs["ID"]."<br>";
print "Autor: ".$attrs["AUTHOR"]."<br>";
print "Titel: ".$attrs["TITLE"]."<br>";
print "<a href='".$attrs["URL"]."' target='_blank'>Bestellen</a><br><hr>";
flush();
}
}
function xml_endElement($parser, $name)
{
}
function parseURL($url) {
$fp=fopen($url,"rb");
if(!$fp) {
return("Could not open $url");
}
$xml_parser = xml_parser_create();
xml_set_element_handler($xml_parser, "xml_startElement", "xml_endElement");
while($data=fread($fp,4096)) {
if (!xml_parse($xml_parser, $data,feof($fp))) {
$ret=sprintf("XML error: %s at line %d",
xml_error_string(xml_get_error_code($xml_parser)),
xml_get_current_line_number($xml_parser));
xml_parser_free($xml_parser);
return($ret);
} } xml_parser_free($xml_parser); fclose($fp); return(false); }
parseURL("https://www.euro-boek.nl/extreq/meta/extquery.php?platform=test&password=test".
"&author=holl&title=jesus&clientip=".$_SERVER["REMOTE_ADDR"]."&format=xml");
Met dit korte program kunnen zoekresultaten reeds in een doorlopende rij weergegeven worden. Met Username/paswoord "test" kunt u tests uitvoeren, voor deze gebruikers worden er geen provisies uitbetaald.
In uw geval schrijft u de output niet uit via "print" in "xml_startElement()", maar u schrijft de gegevens eenvoudig in uw datenbestand. We zeiden al, dat de oproep aan "parseURL" slechts éénmaal per uur dient plaats te vinden, d.w.z. u onthoudt bij het bladeren ook de "ZOEK-ID" en wanneer deze al voorhanden is, haalt u de resultaten uit het gegevensbestand, en anders roept u ons op en schrijft dan de gegevens in het datenbestand.
Als de parameters aan extquery.php afkomstig zijn uit een door de gebruiker ingevoerd zoekformulier, mag u niet vergeten deze volgens de regels van HTML tussen aanhalingstekens te zetten, d.w.z. "...author=".rawurlencode($author)."&title=".rawurlencode($title)."&...".
Als er op uw webserver geen datenbestand ter beschikking staat of als u het progammeerwerk voor het opslaan van gegevens in een bestand wilt vermijden, maar anderzijds functies als sorteren en pagina indeling niet wilt missen, ondersteunt extquery.php u zoveel mogelijk. U kunt extquery.php nog alternatief (na de eerste oproep met auteur/titel enz.) met de zoek-id oproepen, waarbij u de mogelijkheid heeft de resultaten te sorteren en aan de hand van boektitels te beperken.
https://www.euro-boek.nl/extreq/meta/extquery.php?platform=<Ihr Username> &password=<Ihr Passwort>&suchid=<Such-ID>&start=<Start>&end=<End> &order=<Order>&clientip=<Enduser-IP-Adresse>&format=xml
- Zoek-id: Geef hier de teruggegeven zoek-id aan.
- Start: Geef hier het nummer van het boek (genummerd vanaf 1) aan, waarvoor u de uitgave in XML of CSV-formaat wilt hebben.
- End: Geef het nummer van het boek (vanaf 1 genummerd, dit boek wordt niet meegerekend) tot aan diegene, waarvoor u de uitgave in het XML- of CSV.formaat wilt hebben.
- Order: zonder nadere gegevens wordt naar volgorde van binnenkomst sorteert. Andere waarden zijn "author", "title" en "price". Dan wordt op de overeenkomstige criteria gesorteerd.
- platform: Uw gebruikersnaam.
- password: Uw paswoord.
- author: De gezochte auteur of kunstenaar.
- title: De gezoche titel.
- search: tekst-zoekopdracht.
- isbn: ISBN- of EAN-nummer.
- mediatype: 0 voor boeken, 1 für muziek.
- suchid: Voer hier de teruggegeven zoek-id in.
- start: Geef hier het nummer van het boek aan (van 1 af aan genummerd), van waar af u de uitgave in het XML of het CSV-formaat wilt hebben.
- end: Geef hier het nummer van het boek aan (van 1 af genummerd, dit boek wordt niet meegerekend) tot waar u de uitgave in het XML of het CSV-formaat wilt hebben.
- order: Zonder nadere gegevens wordt op volgorde van binnenkomst gesorteerd. Andere waarden zijn "author", "title" en "price". Dan wordt op de overeenkomstige criteria gesorteerd.
- clientip: Geef hier het IP-adres van de aanvragende eindgebruiker aan. Zonder deze aangave worden er geen zoekresultaten doorgegeven. Het vermelden van "-" zorgt ervoor, dat het adres van de aanvragende computer en het adres van de computer van de eindgeruiker identiek zijn. Vergeet niet dat het Client-IP-adres beslissend is om een lawine van zoekopdrachten tegen te gaan. Als steeds het adres van uw server aangenomen wordt, heeft dit een relatief gering aantal aanvragen aan Euro-boek.nl ten gevolge. Deelt u ons daarom steeds het IP-adres van de eindgebuiker mee.
- format: xml voor XML-formaat in de ISO-8859-1 tekenvoorraad, xml8 voor het XML-formaat in de UTF-8 tekenvoorraad, csv voor het CSV-formaat (ISO-8859-1 tekenvoorraad).
Het voorbeeldprogramma betsaat uit twee PHP-files, het formulier(search.php) en de resultatenpagina (result.php). Om te testen kunt u het formulier hier oproepen. De sourcecode staat om te downloaden in een ZIP-archief (3KB) ter beschikking.
Het voorbeeldprogramma heeft geen datenbestand nodig en ondersteunt het invoeren van alle zoekcriteria alsook de uitgave van de resultaten per pagina en de sortering naar verschillende sorteercriteria.
Wij versturen de resultaten zodra wij ze van de boekenplatformen krijgen. D.w.z. soms kunt u een rij van resultaten binnenkrijgen, dan een tijdlang niets (omdat geen platform resultaten oplevert) en dan opnieuw enige en dan tot slot geen enkel meer. Daarom kan het voor u zinvol zijn, de resultaten door een proces in het datenbestand te laten schrijven en met een ander proces weer uit te schrijven of op zijn minst een "bezig"-teken te maken. Dit is gemakkelijk te bewerkstelligen door de resultaten in een klein HTML-FRAME of IFRAME te schrijven, en dit in een ander frame te tonen.
Denk eraan, dat het het doel van deze asynchrone transmissie is, de gegevens meteen op uw website te tonen, wanneer ze binnenkomen. Daarbij moet u er op letten, dat:
- De XML-parser moet de resultaten ofwel in een datenbank schrijven of meteen uitgeven.
- Uitgaven moeten met een
flush();(in PHP, andere programmeertalen heben iets vergelijkbaars) worden afgesloten, opdat ze onmiddellijk aan de client-browser overgegeven worden - Tabellen door de meeste browsers pas gerenderd (weergegeven), wanneer de tabel met
</table>afgesloten is. D.w.z. wanneer boeken in de regels van een tabel weergegeven worden, is het zinvol voor iedere regel in de tabel (dus voor ieder boek)een eigen tabel te maken en deze af te sluiten.
Technische vragen kunt u sturen aan: db.dev@euro-boek.nl.