Freeboard Plugin

An dashboard created using the Sign In App Freeboard plugin

Freeboard is a service which lets you build and display customisable dashboards through its intuitive drag and drop interface. The new Sign In App Freeboard plugin allows users to integrate Sign In App data into their Freeboard dashboards, giving them access to real-time information such as recent sign in activity, members' statuses and graphical breakdowns among many other things. With the Sign In App Freeboard plugin, it's never been easier to see exactly what's going on at a glance.

Setup

When it comes to the setup process, there are 2 different approaches to take; the first is the 'online' approach in which the majority of the setup is done for you, and the second is the 'local' approach which requires a bit of downloading and configuring.

Subscription Fee

If you decide to take the online approach please note there is a subscription fee of $12/month that Freeboard charge (beyond the 30-day free trial). If you take the local approach, however, there is no fee but it does require a few extra setup steps and copy/pasting a line of code. Click here to skip online setup and jump to local setup.

Online setup

Start by visiting the Freeboard website. If you do not have a Freeboard account, then click Start Now to create a new account. If you already have an account with Freeboard, then click Login in the top right hand corner of the screen.

Now that you have logged in, you are ready to create a new dashboard. To do this, enter a name for your dashboard and click Create New in the top right hand corner. Once you have done this, you should be greeted by a blank dashboard with no widgets present.

The Freeboard landing page after logging in

The final step before we start building the dashboard itself is to add the Sign In App plugin to the board. To do this, click developer console in the upper left corner. To add a new plugin, please click add and then copy and paste the link below into the resulting box.

https://my.signinapp.com/freeboard-plugin/signinapp.js

Your developer console should now look like the one shown below. To return to the dashboard, click OK.

The Freeboard developer console popup

The Freeboard setup process is now finished, meaning you're ready to create a Sign In App client API. This is the final step before you can add datasources and widgets to your dashboard. Please click here to skip the local setup and learn how to create a client API.

Local setup

Start by visiting Freeboard's GitHub repository and downloading a ZIP of the files. To do this, click the green Code button in the top right hand corner, followed by Download ZIP.

Freeboard's GitHub repository

The next step differs slightly depending if you are using a Windows computer or a Mac computer. If you are using a Mac please see the instructions below, but if you are using a Windows machine click here to skip to the Windows instructions.

For Mac users

Once the file has downloaded, unzip it by double-clicking on it; within the newly extracted folder you should see an HTML file named index as shown below:

The directory containing the files within freeboard-master.zip

Before adding the code, you first need to alter your TextEdit preferences; open the TextEdit application (built in to Mac computers) and go to Preferences. Click on the Open and Save tab and check the Display HTML files as HTML code... checkbox at the very top. This will allow you to edit HTML code using the TextEdit application.

Now that you've updated TextEdit's preferences you are ready to add the line of code. Right click on the index.html file seen earlier, choose Open With then select TextEdit from the list of suggested applications. On the 14th line you should see // *** Load more plugins here ***. Add a new line underneath this one and paste the following:

"https://my.signinapp.com/freeboard-plugin/signinapp.js",

Once you have done this the file should look as follows:

The index.html code with the new line added

Finally, save your changes (File->Save) and quit TextEdit; the local setup is now complete. To run Freeboard locally, simply right click index.html, select Open With and pick a web browser of your choice.

To skip the Windows setup and jump to the next section, click here.

For Windows users

Once the file has downloaded, you must unzip it. To do this, right-click on the ZIP file, select Extract All... and finally click Extract in the following window. Once the extraction has finished you should see an HTML file named index within the freeboard-master folder, as shown below:

The directory containing the files within freeboard-master.zip

Right click on the index.html file seen earlier, choose Open with and look for Notepad from the list of suggested applications. (If Notepad is not there, click Choose another app and click on Notepad in the resulting window). On the 14th line you should see // *** Load more plugins here ***. Add a new line underneath this one and paste the following:

"https://my.signinapp.com/freeboard-plugin/signinapp.js",

Once you have done this the file should look as follows:

The index.html code with the new line added

Finally, save your changes (File->Save) and quit Notepad; the local setup is now complete. To run Freeboard locally, simply right click index.html, select Open with and pick a web browser of your choice.

Creating a client API

The Sign In App client API allows external services to communicate with our servers in a secure and controlled manner. This means that in order to allow Freeboard access to your Sign In App information you'll need to create a new client API. From the Sign In App portal, click Manage in the top right-hand corner, followed by Client API (found under the Sign In App+ Extensions section).

The manage tab of the Sign In App portal

To create a new client API click the green Add new button, enter a name of your choosing in the resulting popup window and then click Save. You should be greeted with a similar screen to the one shown below.

Popup with client API details

Secret key

Make sure to make a note of your secret key as you will not be able to view this again once the popup is closed.

Now that the client API has been created successfully, you're ready to start adding datasources and widgets to your dashboard. You'll need to use your Client Key and Secret Key in the next section so make sure you've got them to hand!

Adding a datasource

Freeboard dashboards are composed of 2 types of component; datasources and widgets. Datasources fetch information from external sources (like Sign In App's servers, for example), whereas widgets display the information provided by datasources in a simple and organised format. To add a Sign In App datasource to your dashboard click the add button in the top right hand corner, then select Sign In App in the resulting dropdown. You should be greeted with a similar screen to the one shown below.

Freeboard popup showing datasource configuration options

For the Name section, enter a name of your choosing (we recommend the name of the site you wish to monitor). For the Site ID section please enter the ID of the site you wish to monitor. To find this, go to sites in the portal, click on the site you wish to monitor, then look at the URL shown in the URL bar. It should look something as follows:

https://my.signinapp.com/manage/site/19625/details

Your site ID is the number inbetween site and details in the URL. In the example above, the site ID would be 19625. For the Client Key, enter the client key associated with the client API you just created and for the Secret Key enter the key that you noted down earlier. For Region, please select the region in which your sign in data is stored, and finally, for the Site Occupancy Limit section, enter a number of your choosing to represent the maximum number of people allowed on site; don't worry - this number is strictly limited to Freeboard and won't affect your real site. Once you've filled out all the fields simply press Save to close the datasource configuration window.

SIA Datasource Structure

The data that the Sign In App datasource returns is structured as follows:

  • recentActivity - the 5 most recent events that occurred at your site
  • monthlySignInData - a 28-day overview of the number of sign ins at your site
  • groups - a list of all the groups registered at your site
  • occupancy - the current occupancy of your site (as a percentage)


Each group in groups also has its own structure, which looks as follows:

  • visitorCount - number of members currently signed in to your site
  • isReturning - true/false value to represent whether the group is a returning-visitor group or not
  • membersStatus - a list of group members and their corresponding in/out status (returning visitor groups only)

Widgets and panes

Widgets are used to display information on your dashboard in a smart and organised fashion. Widgets cannot be placed on the dashboard directly, but must instead live in panes, which can be rearranged on the dashboard by dragging and dropping. Panes can have multiple widgets in them, and the widget order is adjusted by clicking the ^ and icons.

Adding panes

To add a new pane, click + Add Pane in the upper left corner. You should now see an empty pane with 3 icons in the top right as shown below. The leftmost icon is for adding new widgets to the pane, the middle icon is for adjusting the pane's settings and the right icon is for deleting the pane.

An emtpy freeboard pane

To add a widget to a pane, click the + icon in the top right corner of the pane and select the desired widget type from the resulting dropdown. After selecting a widget type you'll see a few more settings appear - fill these out accordingly and press Save to add the widget to the dashboard. For the remainder of this tutorial we will be placing each widget in its own individual pane to allow maximum flexibility with respect to layout.

Tip

To add/edit panes, you must be in edit mode. To check if you are in edit mode, look at the top of the Freeboard dashboard. If you can see your datasources then you are in edit mode. If not, then you are in display mode. To enter edit mode, simply click the 🔧 icon in the centre at the top of the dashboard.

The SIA big number widget

Big number widget

The SIA Big Number Widget is designed to display important pieces of data in a large, easy-to-read format. This widget has 2 configurable settings; the value setting controls what will be displayed in green and the text setting controls what the accompanying message will say. In the below example, value is 15 and text is "Staff at the office".

The SIA big number widget

To link this widget with your SIA datasource, simply click + Datasource in the widget's settings, select your site from the available datasources, click groups followed by the group of your choosing (in this case Staff) and finally select visitorCount. To save your changes simply click Save in the bottom right-hand corner.

Occupancy widget

The SIA Occupancy Widget is designed for displaying your site's current occupancy level as a percentage. This widget only has 1 configurable setting, value, which controls the percentage displayed in the centre of the doughnut chart. In the example shown, value is 60.

The SIA doughnut widget

To link this widget with your SIA datasource, simply click + Datasource in the widget's settings, select your site from the available datasources and finally select occupancy. To save your changes simply click Save in the bottom right-hand corner.

Tip

Remember that the occupancy limit setting for your site is set within the Sign In App datasource, not the occupancy widget. Click here for more info.

Recent activity widget

The SIA Recent Activity Widget is designed for displaying your site's 5 most recent sign in/out events. This widget only has 1 configurable setting, Activity Source, which controls the activity that the widget will display.

The SIA recent activity widget

To link this widget with your SIA datasource, simply click + Datasource in the widget's settings, select your site from the available datasources and finally select recentActivity (do not click any further!). To save your changes simply click Save in the bottom right-hand corner.

Members' status widget

The SIA Members' Status Widget is designed for displaying a returning visitor group's members and their corresponding status (in/out). With built-in autoscrolling behaviour, this widget ensures you can see all members, regardless of the size of the widget itself. This widget has 2 configurable settings; the source setting controls the members to display and the height setting controls the height of the widget (in blocks, not pixels).

If you are unsure which value to use for height, we recommend starting with 5, then tweaking accordingly.

The SIA members' status widget

To link this widget with your SIA datasource, simply click + Datasource in the widget's settings, select your site from the available datasources, click groups followed by the group of your choosing and finally select membersStatus (do not click any further!). To save your changes simply click Save in the bottom right-hand corner.

Graph widget

The SIA Graph Widget is designed for displaying a 28-day breakdown of the sign in activity on your site. This widget has only 1 configurable setting, source, which controls the graph data to display.

The SIA graph widget

Tip

We recommend placing the graph widget inside a pane with a width of at least 2 for better readability.

To link this widget with your SIA datasource, simply click + Datasource in the widget's settings, select your site from the available datasources and finally select monthlySignInData (do not click any further!). To save your changes simply click Save in the bottom right-hand corner.

Saving and sharing

The process of saving and sharing of dashboards is very straightforward, regardless of which setup method you chose (online/local). To learn how to save and share online dashboards simply continue reading the instructions below. To learn how to save and share local dashboards, however, click here to jump to the local instructions.

Online saving and sharing

If you are using the online version of Freeboard (i.e: you go to freeboard.io in your web browser to access your dashboard), then your boards are auto-saved by Freeboard. Next time you want to load your dashboard, simply select your dashboard from the available list shown on the account page.

The Freeboard account page

When it comes to sharing an online dashboard, the process differs slightly depending on whether you are sharing a public or private dashboard. If your board is public, then simply share the URL with whoever you'd like to view the board. The URL should look something like the following:

https://freeboard.io/board/abcd1

Visibility

An advantage of having a public board is that the anyone can view it; the recepient doesn't need an account. Please note, however, this means that you cannot limit who has access - if someone has the board's URL they can see everything.

If your board is private, on the other hand, you can decide the specific people who are allowed to view/edit it. To share a board, firstly, click the Share button in the bottom right-hand corner of the dashboard. In the resulting popup window enter the email address of your desired recepient, then click the + Share button. Finally, click Save to save your changes.

Please note that the desired recepient must also have a Freeboard account.

Tip

You can also set the recepient's access level in this share popup. Read-only allows the user to view the dashboard but not edit the content, whereas edit allows the user to view the dashboard and also make changes to it.

Local saving and sharing

If you are using the local version of Freeboard (i.e: you run freeboard by double-clicking index.html), then you need to remember to manually save your boards every time you make changes. To do this, click Save Freeboard in the upper left-hand corner, then click [Minified] to download a save-file of your board; this will be called Dashboard.json. Next time you want to load your dashboard, simply click Load Freeboard in the upper left-hand corner and select your Dashboard.json file in the resulting window.

To share a local dashboard with someone else, simply send them the Dashboard.json file. All they have to do is load the dashboard in the same way you do. Remember though, they will need to have added the Sign In App plugin too otherwise the datasources and widgets won't load properly.

`

© 2021 Sign In App Ltd