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
- location
- total
iframe sandbox="allow-scripts allow-same-origin allow-forms" src="https://yourdomain.com/yourExtension? userEmail=cashier1@yourdomain.com &location=oliverPOSLocationName ®ister=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:
