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 a clients WordPress site, but are loaded into Oliver POS. As part of extensions Oliver POS has developed a messaging framework to allow 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 to sign up a customer to a newsletter. It works completely independent from Oliver POS
2) One-way
A one-way extension consumes data from Oliver POS. It can use the data to perform a certain task. For example: a web page that get the list of cart products from Oliver POS and allows the Oliver POS cashier to tag if they are bough by a tourist or a local. Where this information gets saved is the responsibility of the extension.
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. The extension then sends the new tax 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 in WooCommerce it will trigger an event (using the 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.
Extension Setup
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:
- Email of the logged in OliverPOS user
- URl parameter: userEmail
- Name of the Oliver POS register
- URl parameter: register
- Location of the Oliver POS register
- URl parameter: location
- Total amount of the order in Oliver POS
- URl parameter: total
postMessage()
Communication between the extension and Oliver POS is done using the JavaScript method postMessage() and JSON objects
Code Sample
let sendMessageToOliverPOS = function(jsonObject) {
var jsonMessage = JSON.stringify(jsonObject);
window.parent.postMessage(jsonMessage, 'https://yourdomain.com');
};JSON Example
extensionReady
Message sent by the extension to inform OliverPOS that it has finished loading
Code Sample
JSON Example
{
"oliverpos":
{
"event": "extensionReady"
}
}
registerExtension
Message sent by Oliver POS in response to the extensionReady message. Sends data such as products in the cart to the extension
Code Sample
JSON Example
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
Code Sample
let sendMessageToOliverPOS = function(jsonObject) {
var jsonMessage = JSON.stringify(jsonObject);
window.parent.postMessage(jsonMessage, '*');
};
let addData = function(extensionData)
{
let message = {
"oliverpos":
{
"event": "addData"
},
"data": extensionData
};
sendMessageToOliverPOS(message);
}
JSON Example
{
"oliverpos": {
"event": "addData"
},
"data": {
"customTags": {
"TagOne": "Tag One Value",
"TagTwo": "Tag Two Value"
}
}
}
updateProductTaxes
Allows the extension to change the applied tax of each item in the Oliver POS cart
Code Sample
JSON Example
togglePaymentButtons
Allows the extension to enable or disable the payment buttons on the Oliver POS checkout view
Code Sample
JSON Example
extensionFinished
Informs Oliver POS that the extension is finished.
