OptiSync allows you to create dynamic digital menus through API integration. Your POS systems can interface directly with OptiSigns to automatically update prices, track inventory, and more.
-
How to Integrate POS Systems Through API Requests
-
How to Build Digital Menu Boards in Designer with OptiSync
- Pushing a Digital Menu Board to a Screen
In this article, we will create a real Digital Menu Board (DMB) integrated with a Clover POS system. The DMB pulls product info from Clover and display it onscreen. When an item is not available, it will display as "SOLD OUT."
NOTE: API Integration is only available with a Pro Plus plan or higher. |
How to Integrate POS Systems Through API Requests
Most POS systems have an API library which OptiSigns can use to get the relevant data from the system programmatically. This API can return menu items, item price, availability, and more.
With OptiSync, we can link APIs to the OptiSigns portal and push the data to screens as a Digital Menu Board (DMB) or any other type of screen you'd like without the need of human intervention.
This article will focus on these POS specific wrinkles, and the process of mapping POS data to assets and pushing them to screens.
IMPORTANT: In order to integrate a POS system, you'll need to first set up an API Gateway request. A complete guide for how to do that can be found here.
Get API Endpoint URL and Set Up API Request DataSource
We have a comprehensive guide on how to set up your API gateway request. We recommend following this guide until your initial request is set up.
Bare minimum, you'll need an API endpoint URL and an API Authentication token.
Additional Information on API Authentication
For most token based authentication, setting up the authentication token with the key store is normally all that's required for an API request. But certain APIs (such as Toast) will require additional calls to get the authentication token for each request, this can be handled through pre-request processing. To see how to handle that, see our article on Toast APIs.
Handling Multiple Stores or POS Locations
Once you've got your basic API Gateway request set up, there are a few additional steps you'll want to perform if you have multiple locations for your screens. These different locations may have different menus, or different specials for that day, or even different pricing depending on various factors.
POS systems normally require separate license for each location. Your POS system API may provide different store ID in the API endpoint or using different authentication token. For larger deployment with multiple stores, you can use substitution parameters to handle that with OptiSigns.
There are two ways to handle multiple POS locations:
- Set up individual API requests for each of your POS locations, changing the value in the URL endpoint each time and mapping them to each of your screens individually. If you only have a few locations where your POS system is used, this will work just fine.
- (Recommended) Configuring each screen to send its storeID to the API call, allowing a single API request to provide data to multiple screens. For anything more than two or three screens, we recommend this method.
Here's how to handle option 2.
To get started, find the screen you wish to edit.
Click Advanced → More → Device Additional Attributes.
Two fields will show up, Key and Value.
- Key - A parameter that will be used during the API call to substitute for your store's value. This will replace part of your API URL endpoint.
- Value - Represents the unique code associated with the store or location you wish to pass through to your API.
In this example, we'll pretend the parameter you are changing is called "merchantID". The value inputted will need to be obtained on your end as it will be unique.
Now, go back to the API request config page. Substitute the merchantID in the API endpoint with the Key name you previously defined.
When the API request is triggered on the device, it will take the value from the device and substitute it at runtime. For each screen, you'll want to perform these same steps, keeping the Key name the same while changing the Value. This will allow you to push different data to different screens off a single API Request.
How to Use Post-Request Processing to Convert API Data
When retrieving data from your POS system, it may not initially show up exactly the way you'd like, or you might want to add some functionality, such as the ability to display SOLD OUT for items out of stock.
For example, prices may display as whole numbers (i.e. 1299 instead of $12.99). That's where the "Post-request" tab comes in - this allows changes to be made to the data after it comes in. This will require some basic coding to use.
Take the example of the price display from earlier. How would we convert a number like 1299 to display as $12.99, and make that piece of code extensible to any similar display errors (e.g. 1899 instead of $18.99)?
For this common example, this piece of JavaScript code should solve your issue.
let {data, headers, status} = os.context.get("response");
temp_data = data.elements
for (let object of temp_data) {
object.price = '$' + (object.price*.01);
if (object.available == true)
{object.soldout=0;}
else {object.soldout=1;}
}
return temp_data
This will fix the returned data, allowing it to display properly. It will also allow for creation of SOLD OUT and strike through for when items are out of stock.
| NOTE: Enabling and configuring a WebHook allows near real-time updating of the data pulled from your API. If you plan to keep track of store inventory using your digital signs, we recommend setting one up. You will need to input the provided WebHook key into your API to set this up. |
How to Build Digital Menu Boards in Designer with OptiSync
In order to create a DMB with data from your POS system, the API Request will need to be registered as a DataSource. This allows data elements to be added to OptiSigns' Designer app, where it can be formatted and incorporated into any visual design you'd like to display.
The Designer app and templates can be used to do the formatting, and mapping the element to the data from the API data source. Any text box or image element can be mapped in Designer. When you map an image element, the URL of the image will be replaced at run time.
Using DataSources and Repeaters
To get started, find your design or create a new one in the Files/Assets tab.
With the design open, click "DataSource" in the left hand column. Then, click "Add DataSource" to add an API data source to the design.
Scroll down to where it says "API Gateway Collection" and click it.
You can also set up a one-time Gateway with the API Gateway command if you need a one-off design with no pre- or post-request processing. In our example, however, we are, so we'll use Gateway Collection.
You should see this screen:
- Name - The name of the DataSource. This is internally facing and will not be shown on your screens.
- Select APIs - Here you'll select from the API Gateways you've already set up in earlier steps. You can select just one, or multiple. If multiple are selected, the API DataSource will automatically aggregate them.
- Update Interval - How often to send requests back to the API for updates. Select from None (never call the API back), 30 minutes, 60 minutes, or every 6 hours. If you Enable WebHook on your API Request and input the provided URL in your API, this Update Interval will change to near real-time.
Hit Save, and the DataSource is created.
It should appear in the left column under "Used in this design". It will definitely appear in the "Other DataSources" section. You may need to refresh the page for it to appear.
Element Mapping
Now that you've got your API DataSource has been created, we're ready to map the data. In this example, we will show you how to make a DMB with the ability to strike through product names and display the phrase "SOLD OUT" when the item is out of stock.
Adding Text Elements to a Digital Menu Board
First, create your design. You can create your menu within our Designer app.
The easiest way to set up a DMB is with a Data Repeater. For a full breakdown of a Repeater's capabilities, see this article. Here, we'll stick to teaching how to add information from your POS system.
To set up a Repeater, click "Repeaters" → Add Blank Repeater.
With the Repeater selected, click Settings.
A new pane will open up on the right. Here, select Connect to DataSource.
Select the DataSource you set up in the last set under "Other DataSources".
You'll be taken back to the last pane with your DataSource now selected. Now, click Edit or double click the selected Repeater to head to the Repeater Editor. This is like a design-within-a-design, specifically for your Repeater (menu) items. With text selected, click the arrow on the left.
That brings up the DataSource tab. Click on the DataSource Used in this Design and you'll see something like this:
In this example, we want to display the name and the price, with the possibility of saying "SOLD OUT"
By creating text and dragging data points to it, we can create a menu item like this:
This was created by finding data points from the API and dragging them into the desired text boxes. In this case, we only wish to display the "name" and "price," so those values were what we dragged into a blank or existing text box.
If your numbers need extra formatting, click on the number, then hit Settings.
Click Advanced Options → "Display Format" and choose "Number," then click "Number Format" and select the formatting you'd like. This will allow you to add dollar signs to your prices, with other options.
Make sure to hit Update to make your new number format display.
The value of a repeater is that it will copy the format of this one cell, then replace the data points with others from your API. Done correctly, your menu should look something like this:
The Repeater will pull as many data points as you have set up on your API. In this example, we've made a menu with 9 items, but with proper design you can put as many items as you'd like, with dynamic descriptions as well. If you have more items than what you've set to show on your screen at any one time, the items on the menu will rotate through them until they have all displayed.
Creating Strike Throughs and Sold Out Warnings
In the above example, we show a Sold Out warning. However, we don't want to display that all the time - only when the item isn't available. With OptiSync, this can be accomplished thanks to the Post-request processing we did earlier. Our code created this "soldout: 0" data. This is tied to our "available" data:
When the "available" data reads "true," the "soldout" data reads 0. When your POS system detects items are unavailable, the "available" data will read "false". This will make the "soldout" data read 1.
We can use this knowledge to set up our Sold Out warnings and strike throughs to only appear when items are not available.
Going back to our Repeater Editor, we can click on a piece of text we want to strike through and hit Settings:
In the Settings tab, hit Advanced Options.
Under Advanced Options, hit Property Mapping.
Two values will show up: Property and Value.
Under Property, choose Linethrough.
Under Value, choose .soldout. Before the "." will be the name of your API Request.
This sets the text to be crossed out when the "soldout" data reads 1.
We can repeat this with the Sold Out reading, except instead of Linethrough, choose Visible.
This will make the Sold Out text only appear when the "visible" data reads 1 - in other words, when your product is sold out.
Your final menu ought to look something like this:
Finally, you're ready to Name and Save your Design.
Pushing Digital Menu Boards to Screens
Getting your new DMB onto a screen is relatively simple. Go back to the screens you set up with substitution parameters earlier. Then, hit Edit Screen.
Under Type, choose asset, then select your DMB asset to play.
That's all!
You should be able to create an Digital Menu Board with dynamic data features.
If you have any additional questions, concerns or any feedback about OptiSigns, feel free to reach out to our support team at support@optisigns.com.