iBeacon Starter Guide - Getting Started with Mobile Apps for iBeacon

In this guide, we have collected everything you need to get started with creating mobile apps in JavaScript/HTML for iBeacon compatible proximity beacons.

What you need to get started

Here are the things you need to start creating iBeacon apps in JavaScript:

Run the iBeacon Scan example app

The easiest way to get started is to explore the iBeacon Scan example app that comes with the Evothings Studio download:

  • Launch Evothings Workbench on your computer and get a connect key under the "Connect" tab.
  • Launch Evothings Viewer on your mobile phone, enter the connect code and tap the CONNECT button.
  • Go to the Workbench Examples screen and locate the app iBeacon Scan.
  • Click RUN.
  • The app will start scanning for beacons automatically and display data for found beacons.

How to create your own iBeacon app

A quick way to create your own app is to copy the example app:

  • Click COPY on the iBeacon Scan app.
  • Fill in the name of the app folder and the parent folder where you want the app folder to be created.
  • Click CREATE and the new app appears under "My Apps".
  • Click RUN to launch the app. This will make it the currently active app and it is now watched for live reload on file save.

Experiment by making some changes to the code:

  • Click CODE - this opens a file browser with the source code of the app
  • Open a code file in a text editor and make some changes, for example, open index.html and change the h1 header tag text.
  • Save the file.
  • The app now reloads on the connected device(s) and displays your updates.
  • If the app does not reload, click RUN to make sure it is the active app.

To change the label that appears in the "My Apps" listing, alter the title tag in index.html.

Explore the iBeacon JavaScript library

The iBeacon JavaScript library is packaged as a Cordova plugin. Cordova is a build tool that enables creating native apps you can publish on Apple App Store and Google Play.

If you visit the GitHub repository for the iBeacon Cordova/PhoneGap plugin you will find documentation about the iBeacon JavaScript API.

In addition, the tutorial Quick guide to writing mobile iBeacon applications in JavaScript introduces the library and provides background information about iBeacon.

Create your own iBeacon app from scratch

Your beacon app can be used to add information to public places, like shopping malls and restaurants.

An Evothings app is just a folder with HTML/JavaScript files (and other content such as CSS files and images). The minimal project is just one HTML file.

A project should have one main HTML file, which is the file launched when the app starts. This file is typically named "index.html". Just drag and drop your main HTML file into the Workbench window and then click RUN.

Here is a summary of the steps to create an app for use with Evothings Studio:

  • Create a folder for the app
  • Create content files (HTML, JavaScript, CSS, etc)
  • Add any JavaScript libraries needed
  • Drag the main HTML file into the Workbench window
  • Click RUN

A quick way to create a custom app is to just copy an example app and modify it. You can use iBeacon Scan as a starting point.

Note that the JavaScript library files for Cordova iBeacon plugin are bundled with Evothings Viewer, so these should not be added. Including the link to "cordova.js" will in turn include the JavaScript files for all installed plugins.

Pro tip: When you add an app using drag and drop, a file called evothings.json will be created (if not already present). This file contains a UUID for the app and and optional icon image that is displayed in app listing the Workbench window. When you copy an app, keep in mind to change the UUID in the copied file (or just delete the evothings.json file in the copy, a new file with a unique UUID will be created when you press RUN).

Useful links