Sign in

nShift Help Center

nShift Checkout widget user interaction

Avatar
Malene Tidemann
Updated

nshift-checkout-label.png

 

Two different types of changes can affect the widget: external and internal. Both need to be handled differently by the web page.

Learn about:

 

Important note: The nShift Checkout widget cannot be used with Delivery Checkout (legacy version). Read more about the legacy widget here. 

 

External changes

An external change happens when parameters change that could affect which shipping options will be shown in the widget. Common parameters would be the postal code of the receiver or the total price of the items being purchased. The main thing with these parameters is that they are external to the widget. When any of them changes, new shipping options data should be requested from the server. Once the data is available, the widget method updateOptions should be called to display the new shipping options. To request shipping options data use the code from Fill the widget with shipping options section.

 

 

Internal changes

An internal change happens when the user interacts with the widget. This includes events like selecting a shipping option or typing text into an input field. Whenever a change happens the resultCallback function from the widgetSettings will be called with a result object. If the valid property inside the result object is true the information in the result object can be used to create a shipment. If valid is false then the information is incomplete and more user interaction is required. The information in the result object can still be used to update the web page to reflect the user’s selection so far. For example, to update the total price based on the current selection in the widget.


Please note that internal changes should not trigger a request for new shipping options. The information entered or selected by the user inside the widget will not change which shipping options are available.

 

The result object

This is the structure of the result object. It is available as either the result argument in the resultCallback or from the result property on the widget instance.

 

{
   "valid":true,
   "sessionId":"00000000-0000-0000-0000-000000000000",
   "checkoutId":"00000000-0000-0000-0000-000000000000",
   "checkoutVersion":1,
   "optionId":"00000000-0000-0000-0000-000000000000",
   "pickupPointId":"12345",
   "timeSlotId":"2345",
   "addons":[
      {
         "addonId":"NOTIFY",
         "price":1.0,
         "originalPrice":0.0,
         "fields":[
            {
               "fieldId":"EMAIL",
               "value":"info@example.com"
            }
         ],
         "additionalValues":{
            "key1":"value1"
         }
      }
   ],
   "fields":[
      {
         "fieldId":"PHONE",
         "value":"1234567890"
      }
   ],
   "totalPrice":1.0,
   "totalOriginalPrice":0.0,
   "taxRate":0.0,
   "additionalValues":{
      "key2":"value2"
   },
   "resultsVersion":"2",
   "widgetVersion":"2"
}

 

  • valid - This property is true if the result is valid and can be used to create a shipment.

  • sessionId - This property is the UUID of the session used to request the shipping options. It is required to create a shipment.

  • checkoutId - This property is the UUID of the checkout configuration used to generate the shipping options.
  • checkoutVersion - This property is the version number of the checkout configuration used to generate the shipping options. This will be the actual version number of the checkout configuration even when the session was created just using the active checkout configuration ID.

  • optionId - This property is the UUID of the shipping option that is selected in the widget. It is required to create a shipment.

  • pickupPointId - This property is the carrier-specific ID of the pickup point selected in the widget. It is required only if the shipping option uses pickup points. Note that the format and length of the ID is carrier specific.

  • timeSlotId - This property is the carrier-specific ID of the time slot selected in the widget. It is required only if the shipping option uses time slots. Note that the format and length of the ID is carrier specific.

  • addons - This property is an array with addons selected under the selected shipping option. Each entry in the array is an object with these properties:
    • addonId - This property is the ID of the addon.
    • price - This property is the price that has been added to the total price because this addon is selected.
    • originalPrice - This property is the original price that has been added to the total original price because this addon is selected.
    • fields - This property is an array of field inputs under the selected addon. Each entry in the array is an object with these properties:
      • fieldId - This property is the field ID.
      • value - This property is the value of the field as a string.
    • additionalValues - This property is an object with key and values defined by the “Additional return values” section of the checkout configuration.
  • fields - This property is an array of field inputs under the selected shipping option. Each entry in the array is an object with these properties:
    • fieldId - This property is the field ID.
    • value - This property is the value of the field as a string.
  • totalPrice - This property is the total price of the selected shipping option and any selected addons.

  • totalOriginalPrice - This property is the total original price of the selected shipping option and any selected addons.

  • taxRate - This property is the tax rate set in the checkout configuration.

  • additionalValues - This property is an object with key and values defined by the “Additional return values” section of the checkout configuration.

  • resultsVersion - This property is the version of the results object. It is currently always the string "2".

  • widgetVersion - This property is the version of the widget that generated the results object. It is currently always the string "2".

 

Restore user selection

In some cases, restoring the selections and inputs that the user has made in the widget might be necessary. For example, if the user navigates away from the web page, the current result of the widget can be stored in some persistent storage. Then when the user returns to the web page the stored result can be read and applied to the widget.

There are two ways of restoring a result to the widget: The setResult method or a second optional argument to updateOptions. No matter which method is used, the widget will try to select the same options, addons, pickup points, or time slots in the result object. If any of the items are missing the first reasonable item will be selected instead.

 

  // If the widget is filled with shipping options
  widget.setResult(result);
  
  // or if new options should be applied along with a result
  widget.updateOptions(options, result);

 

Please note that there is no need to provide the result argument to the updateOptions method unless the result should change. The widget will keep track of the current result internally and apply it to the available shipping options.

 

 

Widget instance

The widget instance returned from nShiftCheckoutWidget.createWidget() have these properties and methods:

{
   enabled: true,
   result: {},
   setResult(result),
   install(),
   uninstall(),
   enable(),
   disable(),
   updateOptions(options, result)
}
  • enabled - This is a property that contains the enabled / disabled status of the widget.

  • result - This is a property that contains the latest widget result. See The result object section for more information.

  • setResult(result) - This method takes a widget result as an argument and updates the widget to reflect the selections made in the result. The main use for this is to restore the user’s selection if the web page containing the widget is reloaded. See The result object section for more information.

  • install() - This method will add the widget to the web page. HTML elements will be created in the container element when this method is called. See Show the widget for more information.

  • uninstall() - This method will remove the widget from the web page. Any HTML DOM elements and event listeners created by the widget will be removed. See Show the widget for more information.

  • enable() - This method enables user interaction with the widget. See Fill the widget with shipping options for more information.

  • disable() - This method disables user interaction with the widget. See Fill the widget with shipping options for more information.

  • updateOptions(options, results) - This method updates the shipping options shown in the widget. It can also update the user selection at the same time if the optional results argument is provided. See Fill the widget with shipping options for more information.

Related articles