For utviklere

Å ta i bruk Postautomat-popupen fra Bring krever følgende steg:

• Lage knapp som linker til popup
• Lage side som tar i mot resultatet fra popupen og lukker popupen

I tillegg må callback-URLen som brukes godkjennes. Mer informasjon om dette finnes lengre ned på siden.

Lage knapp som åpner popupvindu

Eksempel på HTML-kode for en knapp som kaller en JavaScript-funksjon som åpner en popup:

<input type="button" onclick="popupVelgPostautomat()" 
    value="Velg Postautomat"/>

Popupen bør åpnes av en knapp og ikke en link, da brukere ofte høyreklikker på linker og velger å åpne i egen fane. Dersom popupen åpnes i en ny fane vil ikke JavaScriptet som redirecter resultatet tilbake til nettbutikken virke. Bruk av knapp hindrer brukeren i å åpne ny fane.

Funksjonen som kalles av denne knappen skal åpne følgende URL i et popup-vindu: http://fraktguide.bring.no/fraktguide/popup/postautomat.do

Dette kan for eksempel gjøres ved å bruke følgende JavaScript-funksjon:

<script type="text/javascript">
   function popupVelgPostautomat() {
      url = "http://fraktguide.bring.no/fraktguide/popup/postautomat.do?from=2000&length=30&width=20&height=10&nextDayStopTime=14:00&callbackUrl=http://www.minNettbutikk123.no/bringPopupCallback.jsp";
      day = new Date();
      id = day.getTime();
      eval("page" + id + " = window.open(url, '" + id + "', 'toolbar=0,scrollbars=1,location=0,statusbar=1,menubar=0,resizable=1,width=690,height=680,left = 160,top = 50');");
   }
</script>

Merk her at en del av parametrene må settes dynamisk i nettbutikken, mens andre kan være konstante.

Popupen tar inn følgende parametre:

Eksempel
En pakke skal sendes fra postnummer 2000 med lengde 30 cm, bredde 20 cm og høyde 10 cm. Nettbutikken ønsker stopptid kl 14:00. Det brukes en dummy callback URL.

URL til popupen blir følgende: http://fraktguide.bring.no/fraktguide/popup/postautomat.do?from=2000&length=30&width=20&height=10&nextDayStopTime=14:00 &callbackUrl=http://www.minNettbutikk123.no/popupCallback.jsp

Ta i mot resultat fra popupen

Når brukeren har valgt postautomat og trykket "Bekreft", blir innholdet i popupen redirectet til URLen som er definert i callbackUrl-parameteren. Denne callbackUrl siden må ligge på nettbutikkens server, på samme domene som siden som åpnet popup'en. På dette tidspunkt (etter redirect) har både popupen og siden som åpnet popupen samme domene, og kan dermed gjøre JavaScript-kall mot hverandre. Popupen har tilgang til siden som åpnet popupen via JavaScript-referansen "window.opener", og kan f.eks kalle en funksjon på window.opener slik at resultatet vises i siden som åpnet popupen.

Fra nettbutikkens "registrer resultat-side" som det redirectes til i popupen kan man ta imot resultatet fra popupen og sende dette videre til en JavaScript-funksjon i siden som åpnet popupen. Når resultatet er blitt registrert, må popupen lukkes. Siden trenger ikke ha noe innhold siden popupen lukkes rett etter at siden vises. Dog bør siden inneholde feilhåndtering dersom kallet tilbake feiler.

Følgende request-parametre sendes fra velg postautomat-siden til "registrer resultat-siden". Disse må tas i mot, og brukes til å registrere resultatet på siden som åpnet popupen. Merk at prisen av sikkerhetsmessige årsaker ikke returneres. Den må slås opp i etterkant, for eksempel fra fraktguiden via XML API eller Web Services.

Eksempelkode for å ta i mot resultat fra popupen

Følgende er et eksempel på kode som kan ligge på siden som ligger på callbackUrl adressen. Den tar i mot resultatet fra popup'en, kaller siden som åpnet popupen for å vise resultatet og lukker popupen. Denne siden brukes Java/JSP i tillegg til JavaScript, men vil prinsippet vil være likt også for andre språk. Man trenger ikke ta med alle parametre her, kun de man har bruk for.

VIKTIG: Alle HTML metategn må escapes når resultatet tas i mot slik at Cross Site Scripting angrep ikke blir mulig. Dette gjøres av "getXssSafeValue"-metoden i eksempelet under.

<%!
/** Method for picking out a named request parameter, with HTML meta characters deleted */
String getXssSafeValue(HttpServletRequest req, String paramName) {
   String value = req.getParameter(paramName);
   if (value == null || "".equals(value.trim())) {
      return "";
   }
   return value.replaceAll("&", "").replaceAll("<", "").replaceAll(">", "").replaceAll("\"", "").replaceAll("'", "");
}
%>
<script type="text/javascript">
   //nested server-side code (for getting request parameters) 
   //and JavaScript client side code for invoking page that opened popup (to display results): 
   try {
      window.opener.updatePostautomatValg(
            "<%=getXssSafeValue(request, "productCode")%>", 
            "<%=getXssSafeValue(request, "machineId")%>", 
            "<%=getXssSafeValue(request, "machineName")%>", 
            "<%=getXssSafeValue(request, "address")%>", 
            "<%=getXssSafeValue(request, "postalCode")%>", 
            "<%=getXssSafeValue(request, "city")%>", 
            "<%=getXssSafeValue(request, "locationDescription")%>", 
            "<%=getXssSafeValue(request, "bookingNumber")%>",
            "<%=getXssSafeValue(request, "shippingDate")%>",
            "<%=getXssSafeValue(request, "correlationId")%>"
      ); 
      window.close();
   } catch (err) {
      document.write("Beklager, en feil har oppstått.");      
      throw err;	
   }   
</script>

Siden koden over er server-side kode, kan man også legge parametre som brukes til pakkeadressering/booking/betaling på server-side objekter.

Følgende er et eksempel på JavaScript-funksjon som kan ligge på siden som åpnet popupen. Funksjonen populerer html-elementer med resultatet fra nettbutikkens "registrer resultat-side". Man trenger ikke ta med alle parametre her, kun de man har bruk for. Funksjonen bruker jQuery for å adressere elementer.

Dette eksempelet populerer et tenkt skjema med verdier i hidden elementer og tekst i visningsfelt. I en virkelig nettbutikk må man definere og populere sine egne form elementer og visningsfelt.

VIKTIG: Husk å slå opp prisen i etterkant for å validere input slik at de ikke kan tukles med av klienten. Dette kan du gjøre ved hjelp av XML API og XPath. Eksempel på prisoppslag.

<script type="text/javascript">

   //update this page's contents with the passed in postautomat data
   function updatePostautomatValg(productCode, machineId, machineName, address, postalCode, city, locationDescription, bookingNumber, shippingDate, correlationId) {
      
      $("#postautomatProductCode").val(productCode); //set hidden field value
      $("#postautomatMachineId").val(machineId); //set hidden field value
      
      $("#postautomatMachineName").val(machineName); //set hidden field value
      $("#postautomatMachineNameLabel").html(machineName); //show
      
      $("#postautomatAddress").val(address); //set hidden field value
      $("#postautomatAddressLabel").html(address); //show
      
      $("#postautomatPostalCode").val(postalCode); //set hidden field value
      
      $("#postautomatCity").val(city); //set hidden field value
      $("#postautomatCityLabel").html(city); //show
      
      $("#postautomatLocationLabel").html(locationDescription); //show
      
      $("#postautomatShippingDate").val(shippingDate); //set hidden field value
      $(".postautomatResultsBox").show();
   }
</script>

Godkjenning av callback URL

For å unngå misbruk må redirect URLer som skal brukes med popupen godkjennes av Bring. For å få godkjent din URL, send en e-post til fraktguide kundestøtte. Å få godkjent en URL er naturligvis gratis.

Bekrefte postautomat-reservasjon

Når postautomat er valgt i popupen vil fraktguiden i fremtiden midlertidig reservere en fysisk luke i postautomaten. Denne reservasjonen må senere bekreftes når utsjekksprosessen er fullført og betaling er i orden. Reservasjonen er knyttet til bookingnummeret som returneres fra popupen.

Reservasjonen bekreftes ved å kalle URLen
http://fraktguide.bring.no/fraktguide/postautomat/ bekreftAutomatreservasjon.do?bookingNumber=12345 med bookingnummeret som parameter.

Det faktiske bookingnummeret som skal bekreftes returneres fra popupen. For et eksempel på dette, se Prøv tjenesten: Postautomat.

Foreløpig er ikke booking- og bekreftelsesmekanismene i bruk, men det er likevel svært viktig å implementere disse, da det i fremtiden vil være slik at reservasjonen kan bli kansellert dersom den ikke blir bekreftet innen et gitt tidsvindu.