DEPLOYMENTGUIDE DØGNPOSTEN FOR PARTNERSITES INDLEDNING... 2 BRUGSSCENARIER... 2 RESPONSIVE DESIGN OG JAVASCRIPT... 2 MODULOVERSIGT... 3 1. Simpel installation (evt. indtastede data sendes ikke til oprettelsesflowet)... 3 1.1 Banner / Købsflow... 3 2. Udvidet installation i købsflow med udveksling af data... 3 2.1 Afsendelse af data til oprettelsesflowet fra webshoppen... 3 2.2 Modtagelse af data fra oprettelsesflowet til webshoppen kun https... 4 3. Fejlhåndtering... 5 KOMPLET KODEEKSEMPEL... 6 INSTALLATIONSSUPPORT... 7 ILLUSTRATIONER... 8 Vers.03 1
DEPLOYMENTGUIDE DØGNPOSTEN FOR PARTNERSITES INDLEDNING Løsningen giver en privat kunde mulighed for via 3 steps at oprette sig, søge en automat og få hjælp til, hvordan man udfylder adressefeltet, hvis man ønsker levering i Døgnposten. Løsningen er udviklet således, at den også kan hjælpe en allerede oprettet bruger med f.eks. at få gensendt Døgnposten IDnummeret. Dette er en teknisk introduktion til, hvordan oprettelsesflowet til Døgnposten skal implementeres på en ekstern webside. Dette sker ved at inkludere et javascript på eller et link i din webshop. Fordelen ved at inkludere javascriptet er, at oprettelsesflowet åbner som en lightbox, hvis din side er sikker (https). Derudover giver javascriptet også mulighed for at overføre data til og fra oprettelsesflowet, så din kunde ikke skal udfylde felter både i bestillingsflowet og i oprettelsesflowet. BRUGSSCENARIER Løsningen har to brugsscenarier: Installation i et banner eller ikon, der åbner løsningen ved klik Installation et sted i et købsflow (e-shop), hvor brugeren har indtastet data, som videresendes til løsningen ved klik på denne. Hvis din hjemmesides købsflow er sikkert (https), er der også mulighed for, at de indtastede værdier bliver sendt tilbage til leveringsfelterne, når oprettelsen er gået igennem. Simpel installation til banner eller ikon er beskrevet i afsnit 1.1 Simpel installation i et købsflow (e-shop) uden dataoverførsel er beskrevet i afsnit 1.1 Avanceret installation i et købsflow (e-shop) (http og https) med dataoverførsel til oprettelsesflowet er beskrevet i afsnit 2.1 Avanceret installation i et købsflow (e-shop) (kun https) med dataoverførsel fra oprettelsesflowet tilbage til leveringsoplysningerne er beskrevet i afsnit 2.2 RESPONSIVE DESIGN OG JAVASCRIPT Løsningen fungerer på både mobil, tablet og desktop. Designet er tilpasset de forskellige devices. Funktionsmæssigt er løsningen også tilpasset, så siden indlæses i en ny tab på mobil, åbner som en landing side på ipad, mens den på desktop vil åbnes i en lightbox eller en landing side, alt efter om løsningen kører https/http (se illustration sidst i denne guide). Javascriptet finder selv ud af, hvilken version af løsningen der skal åbnes. Du kan nøjes med at installere javascriptet i en simpel version (afsnit 1.1), hvis der ikke skal overføres data mellem din hjemmeside og oprettelsesflowet i løsningen. Der kan tilføjes yderligere javascript, hvis dataoverførsel ønskes (afsnit 2.1 og 2.2). Kodestykke 1+2 skal altid som minimum installeres. Vi anbefaler, at du derudover også installerer kodestykke 6+7, som vil sikre information til kunden ved fejl, så snart kunden forsøger at tilgå løsningen. Vers.03 2
MODULOVERSIGT 1. Simpel installation (evt. indtastede data sendes ikke til oprettelsesflowet) (kodestykke 1+2 eller kodestykke 1+6+7) 1.1 Banner / Købsflow For at oprettelsesflowet til Døgnposten kan indlæses, kan du blot inkludere følgende link et sted i din webshop, som et link, en banner eller et ikon. http://thirdparty-appservices.postdanmark.dk/doegnposten/banner.aspx Alternativt kræver det, at der inkluderes et JavaScript dokument på siden. JavaScripten kan indsættes i <head> eller et vilkårligt sted i <body>: Kodestykke 1: <script src="http://thirdparty-appservices.postdanmark.dk/doegnposten/js/postdanmark.partner.js" type="text/javascript"></script> For at åbne oprettelsesflowet kaldes en JavaScript funktion f.eks. med et link: Kodestykke 2: <a href="#" onclick="return Post.Partner.initialize();">Åben Døgnposten</a> Funktionen, som kaldes, hedder Post.Partner.initialize(), og kan kaldes alle steder på siden. I overstående eksempel sendes der ikke data frem og tilbage. Kun selve oprettelsen til Døgnposten sker. Når oprettelsesflowet er gennemført, lukkes løsningen, og bruger vender tilbage til hjemmesiden, han/hun befandt sig på, uden at siden genindlæses. 2. Udvidet installation i købsflow med udveksling af data Med denne løsning gøres det nemt for bruger, da navn, Døgnposten ID, mobilnummer og e-mail ikke skal indtastes igen af brugeren. Kundeoplysningerne kan overføres automatisk fra købsflowet til løsningen eller overføres fra købsflowet til løsningen og retur igen til købsflowet. For at køre den udvidede installation skal du udover kodestykke 1 også sørge for at indlæse oprettelsesflowets JavaScript fil først. 2.1 Afsendelse af data til oprettelsesflowet fra webshoppen (kodestykke 1+3+4 eller kodestykke 1+3+6+7) Som i kodestykke 2 kan man åbne oprettelsesflowet til Døgnposten. Denne løsning gør det derudover muligt at medsende data, som bruges til at udfylde felterne på forhånd i første step af flowet. For at medsende data skal de defineres i et objekt, som kaldes via en funktion. Funktionen skal se således ud: Vers.03 3
Kodestykke 3: <script type="text/javascript"> function senddata() var data = firstname: document.getelementbyid("firstname").value, lastname: document.getelementbyid("lastname").value, email: document.getelementbyid("email").value, mobilenumber: document.getelementbyid("mobilenumber").value, company: 'www.domæne.dk' return data; </script> De parametre, der kan overføres fra din hjemmeside til løsningen, er: fornavn, efternavn, e-mail, mobilnr. og firma web-adresse. I kodestykke 3 er der taget udgangspunkt i, at der er en række inputfelter, som har et ID, som hentes via getelementbyid. Dette er blot et eksempel på brug af objektet. Parametrene skal hedde nøjagtigt: firstname lastname email mobilenumber company Company parameteren bruges til at danne en relation for brugeren mellem oprettelsesflowet og webshoppens site (din side). Det er valgfrit, om man sender alle eller kun enkelte parametre med til oprettelsesflowet. Det anbefales dog, at company altid sendes med, da det for brugeren vil være nøglen til genkendelighed fra webshoppens. Det er valgfrit, hvad company indeholder, men det anbefales, at det er web-adressen, som bruges. Mobilenumber skal være uden +45. For at åbne oprettelsesflowet med data skal objektet sendes med i funktionen, som beskrevet tidligere: Kodestykke 4: <a href="#" onclick="return Post.Partner.initialize(sendData);">Åben Døgnposten</a> <a href="#" onclick="return Post.Partner.initialize(sendData);">Åben Døgnposten</a> Det, der sker ved åbning, er, at Post Danmark vil kalde funktionen senddata og forsøge at sende objektet videre til oprettelsesflowet. Hvis parametrene er defineret, vil de blive brugt. Parametrene vil ikke blive valideret, når de sendes til oprettelsesflowet. I dette tilfælde går oprettelsesflowet ud fra, at data er i korrekt format. Valideringen vil først foregå i selve oprettelsesflowet. 2.2 Modtagelse af data fra oprettelsesflowet til webshoppen kun https (kodestykke 1+3+5+4 eller 1+3+5+6+7) Når brugeren er færdig med sin oprettelse til Døgnposten og har trykket OK, er det muligt at modtage data fra oprettelsesflowet retur til købsflowet (din hjemmeside). Vers.03 4
Obs. Dette er dog kun muligt, hvis din webshop kører en sikker løsning (HTTPS). Oprettelsesflowet kaldes via en sikker, og derfor er det teknisk ikke muligt at sende informationer tilbage til din webshop pga. manglende sikkerhed i browseren, hvis din webshop kører http. JavaScripten fra oprettelsesflowet vil forsøge at kalde en funktion, som webshoppen selv skal definere. Funktionen skal hedde getdoegnpostendata(data) og indeholder kun en parameter. Parameteren bliver udfyldt som et objekt fra oprettelsesflowet med data om brugeren. Hvis webshoppen ikke har defineret funktionen, kan der ikke returneres data. Der ses her i kodestykke 5 et eksempel på funktionen. I dette eksempel går funktionen ud fra, at der er et inputfelt f.eks. med ID firstname. Dette felt vil blive udfyldt med data fra oprettelsesflowet. Kodestykke: 5 <script type="text/javascript"> function getdoegnpostendata(data) document.getelementbyid("firstname").value = data.firstname; document.getelementbyid("lastname").value = data.lastname; document.getelementbyid("address").value = data.address; document.getelementbyid("city").value = data.city; document.getelementbyid("postal").value = data.postal; </script> Mulige returparametre fra oprettelsesflowet til webshoppen: firstname lastname address city postal 3. Fejlhåndtering Det er muligt, at der kan opstå en form for fejl ved åbning af oprettelsesflowet. Hvis det er tilfældet, kan du give brugeren besked om, at der ikke er kontakt til Post Danmarks server. Dette gøres ved at sende en funktion med i kaldet til oprettelsesflowet, som kaldes ved fejl. Først defineres funktionen: Kodestykke 6: <script type="text/javascript"> function handleerror(errormessage) alert(errormessage); </script> Dernæst sendes funktionen med i kaldet, som åbner oprettelsesflowet, som nu kaldes, som vist i kodestykke 7. Kodestykke 7: <a href="#" onclick="return Post.Partner.initialize(sendData, handleerror );">Åben Døgnposten</a> Oprettelsesflowet returnerer en fejlbesked om, at der ikke er kontakt til Post Danmarks servere. Vers.03 5
Denne fejl kan som i kodestykke 6 enten laves som en "alert eller håndteres, som webshoppen selv ønsker det. KOMPLET KODEEKSEMPEL Her ses det komplette eksempel, som er forklaret under sektion 2. Udvidet installation i købsflow med udveksling af data Javascript kodestykke 8: <!-- Script includes, use https:// if you are using a secure solution --> <script src="http://thirdparty-appservices.postdanmark.dk/doegnposten/js/postdanmark.partner.js" type="text/javascript"></script> <script type="text/javascript"> // Send data to Døgnposten function senddata() var data = firstname: document.getelementbyid("firstname").value, lastname: document.getelementbyid("lastname").value, email: document.getelementbyid("email").value, mobilenumber: document.getelementbyid("mobilenumber").value, company: 'www.trendsales.dk' return data; // Handle errors like you want function handleerror(errormessage) alert(errormessage); // function name getdoegnpostendata is required for returning data function getdoegnpostendata(data) document.getelementbyid("firstname").value = data.firstname; document.getelementbyid("lastname").value = data.lastname; document.getelementbyid("address").value = data.address; document.getelementbyid("city").value = data.city; document.getelementbyid("postal").value = data.postal; </script> HTML kodestykke 9: <!-- Input elements --> <form> <label for="firstname">fornavn:</label> <input type="text" name="firstname" id="firstname" value="peter" /><br /><br /> <label for="lastname">efternavn:</label> <input type="text" name="lastname" id="lastname" value="petersen" /><br /><br /> <label for="email">email:</label> <input type="text" name="email" id="email" value="test@test.dk" /><br /><br /> <label for="mobilenumber">mobilnummer:</label> <input type="text" name="mobilenumber" id="mobilenumber" value="11223344" /><br /><br /> Vers.03 6
<label for="address">adress:</label> <input type="text" name="address" id="address" value="opfindervej 1" /><br /><br /> <label for="city">by:</label> <input type="text" name="city" id="city" value="københavn" /><br /><br /> <label for="postal">post nr.:</label> <input type="text" name="postal" id="postal" value="2300" /> </form> <!-- Open Døgnposten --> <a href="#" onclick="return Post.Partner.partner(sendData, handleerror);">tilmeld Døgnposten</a> INSTALLATIONSSUPPORT CREUNA kan kontaktes mellem kl. 9.30 og 15.30 på telefonnr. 22685802 for installationssupport. Post Danmark kan kontaktes på fktpk26@post.dk for forbedringsforslag til løsningen eller denne installationsvejledning. Vers.03 7
ILLUSTRATIONER HTTP DESKTOP/tablet åbnes som landing page Webshop http://www.webshop.dk/checkout.aspx Opret dig til Døgnposten Oprettelse til fra banner over http Oprettelse til https://appservices.postdanmark.dk/doegnposten Oprettelse til Døgnposten fra webshop over http Mulighed for at data kan sendes til oprettelsessiden, men ikke retur HTTP - Mobil Webshop 12:38 Døgnpost Shop 12:38 Oprettelse i fra banner over http Opret dig til Oprettelse til Døgnposten fra webshop over http Data kan sendes til oprettelsessiden, men ikke retur Vers.03 8
Webshop https://www.webshop.dk/checkout.aspx HTTPS Desktop åbnes i Iframe Opret dig til Døgnposten Oprettelse til fra banner Oprettelse i fra webshop Data kan sendes til oprettelsessiden og retur Oprettelse til https://appservices.postdanmark.dk/doegnposten Opret dig til Døgnposten Vers.03 9
HTTPS Tablet åbnes som landing page Webshop https://www.webshop.dk/checkout.aspx Opret dig til Døgnposten Oprettelse til fra banner Oprettelse til https://appservices.postdanmark.dk/doegnposten Oprettelse i fra webshop Data kan sendes til oprettelsessiden og retur HTTPS - Mobil Webshop 12:38 Døgnpost Shop 12:38 Oprettelse i fra banner Opret dig til Oprettelse i fra webshop Data kan sendes til oprettelsessiden og retur Vers.03 10