Follow

Widget dokumentation ver. 1.2

Introduction

PostNord Delivery Checkout Widget is a system that allows you to implement all the PostNord shipping methods to your web shop. The widget is split on two parts: - Front End – JavaScript file package that allows you to initiate all the design templates on you web page or implementation of iFrame. The iFrame solution allows you to initiate the design only by a script implementation in your checkout, without storing any of the files on your server side. - Configuration panel – which you can access from here: https://deliverycheckout.postnord.com/ using the credentials you will receive in a separate e-mail from our partner vConnect. This is were you set all the methods, prices, conditions, additional functionalities and other based on your specific needs and personal preferences.

To be able to use the PostNord widget you need to complete the following steps:

1. Sign-up for the service on: https://developer.postnord.com/delivery-checkout/singlecarrier/widget

2. After activation of your account you can login at https://developer.postnord.com/ and retrieve your API key to be used in your widget configuration panel. Please note that you cannot login to the widget configuration panel using your credentials for developer.postnord.com.

Support

• If you have any questions regarding the widget configuration panel, please contact vConnect at: kontakt@vconnect.dk kontakt@vconnect.dk

Creating and configuring a PostNord widget Steps to follow:
01. To create your first widget, you need to open the PostNord Widget section from the left side menu:

mceclip0.png

02. Than you need to pick a country from which you widget will be executed from (merchant store country) – you have four options.mceclip1.png

03.After choosing you country than you click on “Add Widget” button – on the right side of the screen mceclip2.png

 

04.Next step is to configure the general settings of your widget: mceclip3.png

Fields in the General settings:

  1. Name – which is the name that will appear in the list of widgets .
  2. Short description – in the image bellow you can see how these two fields are displayed.mceclip4.png
  3. Default shipping method – this is the method that will be selected for the customer by default, when they enter the site for the first time.
  4. Color code – this feature allows you to customize the color of your widget, so it can fit at best your web shop design.
  5. Country – this selector is for the country you are shipping from (this selector is important in the data flow for some web shop systems)
  6. Currency – this should be selected the same as your web shop currency setup.

05.Next step is to configure a shipping method:

 

  1. Enable/Disable button – Turning the method ON or OFF
  2. Title – Required field without which the method will not be displayed
  3. Transit Time – in the front-end this field is displayed under the shipping method title row
  4. Description – text field that is displayed beneath the Title and Transit Time fields on the front-end
  5. Sort Order – by this functionality you can order the methods sorting on front -end
  6. Carrier Service Code – this field is not required. In some shop systems these codes are used to execute 3 party modules when an order is made.
  7. Countries – by this functionality you are allowing the specific shipping method to ship to this country.
  8. Rates – also know as the “price matrix”. This is the conditions of your shipping method – Cart Weight and Cart Price. Base on these 2 parameters the widget returns you different price(Cost) of the shipping method.
  9. Allow Bulky Products – this setting is for adding or removing parameter for the specific shipping method that allows or disallows to ship bulky products with this method
  10. Custom attributes – this setting give you the possibility to add some requirement attributes to the products in order to be shipped with this method.
  11. Enable Free Shipping – this is another parameter that you can add in your system, so a specific product group can be shipped for free
  12. Free Shipping Price – this is text field and allows you to put either a price or text for the method for example: “0” or “You have free shipping”
  13. Other Fields – there are some fields that are working only for specific methods, like additional shipping options (flex delivery) or additional prices.

Widget Code implementation

Description

Widget for shipping method and pickup location selection.

The module is implemented as jQuery widget and is represented by popup window or inline in the webpage. This document describes only the inline theme.

The widget has several tabs. Each tab matches exactly one shipping method which is set up through the admin backend website and has its own shipping options. Every time when the user chooses a shipping option or changes the shipping method - an event is triggered. This event should be used by the developer who implements the widget to obtain the selection data.

When initializing the widget – request to the API is made, to obtain all the necessary data about the shipping methods in form of a JSON file. After the user makes a selection the event “optionChangedCallback” is triggered. The developer needs to specify the callback function, which will be responsible for further processing of the data returned by the widget. The function is described later in the document. When implementing the widget there are multiple options, which must be set correctly, so that the module can function properly. The following services and API are used:

Requirements

  • Valid widget data API key - https://deliverycheckout.postnord.com – use your account to login and get the key.
  • Valid Google map API key - https://developers.google.com/maps/documentation/javascript/get-api-key

Example

Html body section:

  <div id="widgetContainer"></div>

  <input type="button" id="openWidget" />


End of body tag:

  <script src="/scripts/jquery-1.12.4.js" type="text/javascript"></script>

  <script src="/scripts/jquery-ui.min.js"></script>

  <script src="https://maps.googleapis.com/maps/api/js?key={GOOGLEMAPAPIKEY}"></script>

  <script src="scripts/vconnect.allinone.min.js"></script>

  <script type="text/javascript">

     $(function () {

         $('#openWidget').click(function () {

             $('#widgetContainer').allInOne({

                 key: '', // update with provided key

                 userPostcode: '113 51',

                 userCountryCode: 'SE',

                 userStreet: 'Roslagsgatan 10',

                 cartTotalWeight: 50,

                 cartTotalPrice: 20,

                 themeFolder: '/widget/themes',

                 langUrl: '/widget/data/aio.lang.json',

                 showLoader: true,

                 loadCompletedCallback: function (success) {

                     if (!success) {

                         alert('Unable to load widget!');

                     }

                 },

                 optionChangedCallback: function(data) { }

             });

         });

     });

    </script> 

 

This snippet uses example options, change the key,, userPostcode, userCountryCode, userStreet, cartTotalWeight, cartTotalPrice,  Also provide the path to the theme folder and language file locations. Fill in the google map API key in the maps.googleapis.com script tag. Subscribe to optionChangedCallback event to handle the result data.

Configuration

  • Key (required): widget API key which is need for initialization for the backend API call. Each store has unique key, defined in the backend. This key will be passed to the API call and the server will use it to find out which shipping methods has to be returned to the end user. 
  • userPostCode (required): Used in combination with “userCountryCode” and “userStreet” to find the geo location of the user and nearest post office locations in the area.
  • userCountryCode (requried): Used in combination with “userPostCode” and “userStreet” to find the geo location of the user and nearest post office locations in the area.
  • userStreet (required): Used in combination with “userPostCode” and “userCountryCode” to find the geo location of the user and nearest post office locations in the area.
  • cartTotalWeight (required): used to find the shipping method price. This price is calculated based on total cart total weight and cart total price (“cartTotalPrice” parameter).
  • cartTotalPrice (required): used to find the shipping method price. This price is calculated based on total cart total weight (“cartTotalWeight” parameter) and cart total price.
  • themeFolder (required): specifies the location of the theme files – images, css and fonts. These files come from the widget package
  • langUrl: (required): specifies the location of the language translation file. Comes from the widget package
  • showLoader: specifies whether the loader animation will be shown before opening the widget.
  • dataAPIUrl: (internal) can be used for testing or to extend the widget.
  • postOfficeAPIUrl: (internal) can be used for testing or to extend the widget
  • loadCompletedCallback: provide callback if you need additional functionality after the widget is loaded.
  • optionChangedCallback: callback function should be provided to obtain the user selection data. See the next section for more information about the output data.
  • enableFreeShipping: enable free shipping
  • hasBulkyProducts: defines if shopping basket contains bulky products.

Widget output data

The data is returned in the form of a json object with this format:

"shippingTitle": "Hemlverans",
"shippingId": "postOfficeDelivery",
"carrierServiceCode": "12341",
"deliveryDetails": {
      "typeId": "pickuppostoffice",
      "typeText": "Pickup in post office",
      "name": "ICA Supermarket Fäladstorget",
      “country”: ‘SE’,
      "addressId": "157972",
      "addressText": "Fäladstorget 14",
      "city": "LUND",
      "postcode": "22647",
      "info": " User provided additional information "
},
"price": "150.00",
"currency": "kr."

Data description:

  • shippingTitle: shipping title. Available for all shipping methods.
  • shippingId: shipping type. Available for all shipping methods.
  • deliveryDetails:
    • typeId: delivery type. Available for some shipping methods.
    • typeText: delivery type text. Available for some shipping methods.
    • name: name of the pickup point. Available for pickup shipping methods.
    • country: country code. Available for all shipping methods.
    • addressId: the id of the pickup point. Available for pickup shipping methods.
    • addressText: the address of the pickup point. Available for pickup shipping methods.
    • city: the city of the pickup point. Available for pickup shipping methods.
    • postcode: pickup point postcode. Available for pickup shipping methods.
    • info: additional information filled by the user. Available for some shipping methods.
  • price: delivery price. Available for all shipping methods.
  • currency: currency

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk