Menu

Welcome to Oliver POS Docs

Welcome to Oliver POS technical documentation. This page is primarily target at developers that want to use a feature of Oliver POS that we have named Oliver POS Extensions.

Extensions are a mechanism that allows developers to build custom functionality that run within Oliver POS. Extensions can be simple or complex web pages that run on a clients WordPress site, but are loaded into Oliver POS. As part of extensions Oliver POS has developed a messaging framework to allows communication between Oliver POS and the extension.

Oliver POS Extensions 101

Oliver POS Extensions can be broken into four different categories:

1) Basic

A basic extension is a web page that is loaded directly into Oliver POS. There is no interaction between the extension and Oliver POS. For example: a web page that allows the Oliver POS cashier fill in a quick questionnaire about their customer – for example if the customer is a tourist or not. It works completely independent from Oliver POS

 

2) One-way

A one-way extension consumes data from Oliver POS. For example: a web page that gets the email address of the customer from Oliver POS and populates it into the signup form for a newsletter. If the customer wants to sign up the cashier has to simply click a confirm button.

 

3) Two-way

A two-way extension both consumes data from Oliver POS and also sends data back to Oliver POS. For example: a web page that allows the Oliver POS cashier to apply a different tax based on where the customer lives. Oliver POS sends the details about the customer and the items in the cart to the extension. The extension then sends the new taxes back to Oliver POS where it is applied.

 

4) Complex

A complex extension has an additional feature – it sends a dataset & event name to Oliver POS. The dataset is saved in temp storage in Oliver POS. When Oliver POS has finished creating the order back in WooCommerce it will trigger an event (using the event name provided from the extension) and pass the dataset as an argument. The extension can listens for the triggered event and consume the dataset – and implement any special code it wants to apply using the dataset.

 

 

How Oliver POS loads your Extension

Oliver POS loads extension using an iframe. The iframe is sandboxed with the following attributes applied:

  • allow-scripts
  • allow-same-origin
  • allow-forms

Oliver POS passes data to the iframe by appending parameters to the URL. The data is url encoded and consists of the following:

  • userEmail
Email of the logged in OliverPOS user

  • register
Name of the Oliver POS register
 
  • location
Location  of the Oliver POS register
 
  • total 
Total amount of the order in Oliver POS

 

iframe 
sandbox="allow-scripts allow-same-origin allow-forms"
src="https://yourdomain.com/yourExtension?
userEmail=cashier1@yourdomain.com
&location=oliverPOSLocationName
&register=oliverPOSRegisterName
&total=19.13"

How communication is implemented between Oliver POS and your Extension

Communication between an extension and Oliver POS is achieved using:

  • Javascript postMessage()
  • JSON

postMessage is use by both Oliver POS and the extension to send JSON messages to each other. The JSON message  has a strict format and corresponds to an event supported by Oliver POS.

 

The extension will both consume messages from Oliver POS and also send messages to Oliver POS.

Code Sample

let sendMessageToOliverPOS = function(jsonObject) {
    var jsonMessage = JSON.stringify(jsonObject);

    window.parent.postMessage(jsonMessage, 'https://yourdomain.com');    
};

JSON Example

{
  "oliverpos": {
    "event": "event name"
  },
  "data": {
    Any valid JSON here
  }
}

extensionReady

Message sent by the extension to inform OliverPOS that it has finished loading

Code Sample

let sendMessageToOliverPOS = function(jsonObject) {
    var jsonMessage = JSON.stringify(jsonObject);

    window.parent.postMessage(jsonMessage, 'https://yourdomain.com');    
};

JSON Example


{
        "oliverpos":
        {
            "event": "extensionReady"
        }
}

shareCheckoutData

Message sent by Oliver POS in response to the extensionReady message. Oliver POS will share data with the extension such as:

  • Products in the cart
  • Customer address 

Code Sample

let sendMessageToExtension = function(jsonObject) {
    var jsonMessage = JSON.stringify(jsonObject);

    window.parent.postMessage(jsonMessage, 'https://oliverpos.com/');    
};

JSON Example

{
  "oliverpos": {
    "event": "shareCheckoutData"
  },
  "data": {
    "checkoutData": {
      "totalTax": 5.39,
      "cartProducts": [
        {
          "amount": 28.99,
          "productId": 356,
          "variationId": 0,
          "tax": 2.89,
          "discountAmount": 0,
          "quantity": 1,
          "title": "Product 1"
        },
        {
          "amount": 24.9,
          "productId": 550,
          "variationId": 0,
          "tax": 2.49,
          "discountAmount": 0,
          "quantity": 1,
          "title": "Product 2"
        }
      ],
      "addressLine1": "70 Main Street",
      "addressLine2": "",
      "city": "Sun Prairie",
      "zip": "123456",
      "countryCode": "US",
      "country": "USA",
      "stateCode": "WI",
      "state": "Wisconsin"
    }
  }
}

addData

Allows the extension to add data to Oliver POS. When Oliver POS has finished creating the order in WooCommerce it will trigger an event  and pass the dataset as an argument

JSON Example


{
  "oliverpos": {
    "event": "addData"
  },
  "data": {
    "customTags": {
      "TagOne": "Tag One Value",
      "TagTwo": "Tag Two Value"
    }
  }
}

saveCustomFee

Allows the extension to add custom fees to the Oliver POS cart

 

Only positive numbers are supported. Negative numbers will be transposed to positive numbers.

JSON Example

{
  "oliverpos": {
    "event": "saveCustomFee"
  },
  "data": {
    "customFee": {
      "key": "uniqueKey",
      "amount": 7
    }
  }
}

saveDiscount

Allows the extension to add a discount to the Oliver POS cart

 

Only positive numbers are supported. Negative numbers will be transposed to positive numbers.

JSON Example

{
  "oliverpos": {
    "event": "saveDiscount"
  },
  "data": {
    "customFee": {
      "key": "uniqueKey",
      "amount": 10
    }
  }
}

updateProductTaxes

Allows the extension to change the applied tax of each item in the Oliver POS cart

JSON Example


{
  "oliverpos": {
    "event": "updateProductTaxes"
  },
  "data": {
    "products": [
      {
        "amount": 28.99,
        "productId": 356,
        "variationId": 0,
        "tax": "3.1",
        "discountAmount": 0,
        "quantity": 1,
        "title": "Product 1"
      },
      {
        "amount": 24.9,
        "productId": 550,
        "variationId": 0,
        "tax": "2.95",
        "discountAmount": 0,
        "quantity": 1,
        "title": "Product 2"
      }
    ]
  }
}

togglePaymentButtons

Allows the extension to enable or disable the payment buttons on the Oliver POS checkout view

JSON Example


{
  "oliverpos": {
    "event": "togglePaymentButtons"
  },
  "data": {
    "togglePayment": {
      "flag": false
    }
  }
}

extensionFinished

Informs Oliver POS that the extension is finished. Here is where you can also pass the WordPress event you would like to be fired after the order is created back in WooCommerce

JSON Example


{
  "oliverpos": {
    "event": "extensionFinished",
    "wordpressAction": "Your Event Name"
  }
}

Below is an example of sending a custom fee to Oliver POS

Code Sample



		

			
Client Extension

			

				
Custom Fee Key:

				
				
Custom Fee Amount: