Sign In App Documentation

Freeboard is a service which lets you build and display customisable dashboards through its intuitive drag and drop interface. The 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.

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 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-v2.js

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

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.

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:

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-v2.js",

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

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:

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-v2.js",

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

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).

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.

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.

For the Name section, enter a name of your choosing (in this example, we will name it "SIA datasource"). For the Site IDs section please enter the IDs (separated by commas) of the sites you wish to monitor. To find the ID of a site, go to sites in the portal, click on the desired site, then look at the URL shown in the URL bar. It should look something as follows:

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

The site ID is the number inbetween site and details in the URL. In the example above, the site ID would be 19625. For the Group IDs section please enter the IDs (again, separated by commas) of the groups you wish to monitor. To find the ID of a group, go to groups in the portal, click on the desired group, then look at the URL shown in the URL bar. Similarly to above, the group ID is the number inbetween group and members in the URL. For the Client Key, enter the client key associated with the client API you just created, for the Secret Key enter the key that you noted down earlier and finally, for Region, please select the region in which your sign in data is stored.

SIA Datasource Structure

The data that the Sign In App datasource returns is split into 2 categories; sites and groups. Each group simply contains a list of its members, whereas, each site has the following structure:

• group_visitor_counts - the number of people currently on site for each group
• total_visitor_count - the total number of people currently on site
• recent_activity - the 5 most recent events that occurred at your site
• history_data - a 28-day overview of how many people were on-site

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.

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.

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 caption setting controls what the accompanying message will say. In the below example, value is 15 and caption is "Staff at the office".

To link this widget with your SIA datasource in the same way as the above example, simply click + Datasource in the widget's settings, select your Sign In App datasource, then click sites followed by the site of your choosing (in this case UK Office). Next, click group_visitor_counts and finally select the name of the desired group (in this case we select Staff). To save your changes simply click Save in the bottom right-hand corner.

Occupancy widget

The SIA Occupancy Widget is designed for neatly displaying an occupancy in the form of a doughnut chart. This widget has 3 configurable settings; the title setting controls an optional title at the top of the widget and value/max together control the percentage of the doughnut chart itself. In the example shown below, value is 8 and max is 10.

To link this widget with your SIA datasource, simply click + Datasource in the widget's settings, select a site from the available sites and finally select the desired value (in the above example, we selected total_visitor_count). To save your changes simply click Save in the bottom right-hand corner.

Activity widget

The SIA Activity Widget is designed for displaying your site's 5 most recent sign in/out events. This widget only has 2 configurable settings; title, which controls an optional title at the top of the widget and activity source, which controls the activity that the widget will display.

To link this widget with your SIA datasource, simply click + Datasource in the widget's settings, select your desired site from the available sites and finally select recent_activity (but click no 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 6 configurable settings; title controls an optional title at the top of the widget, group controls which group to display, height controls the height of the widget (in blocks, not pixels), site id controls whether the widget is scoped to a specific site, show site names controls whether or not a site name is shown under each member and finally show signed out controls whether or not signed out members are shown.

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

To link this widget with your SIA datasource, simply click + Datasource in the widget's settings and select your desired group from the available groups (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 how many people have been on your site. This widget has only 2 configurable settings, the title setting controls an optional title at the top of the widget and the source setting controls the graph data to display.

To link this widget with your SIA datasource, simply click + Datasource in the widget's settings, select your site from the available sites and finally select history_data (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.

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

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.

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.