Stunning experiences with iBeacon and Tumult Hype

Posted by in iBeacon in Education

Today we’re going to learn how you can master the HTML card type with an easy editing program like Tumult Hype 3. Hype allows you to design HTML5 pages, components and experiences in a manner that you’re more used to with programs such as Keynote and PowerPoint. We’re going to set our Hype document up to utilise the screen real estate we have in Locly then create some scenes and hook them into beacons. Once we’re done we’ll have a new card that will provide a unique experience in a real world place.

This article won’t teach you how to use Hype, so if you’re new to it you may want to follow some tutorials aimed at getting you on the road. You can find these on the hype website at http://tumult.com/hype/tutorials/. If you don’t have Tumult Hype 3 it’s available from the Mac App Store.

Layout

Sidenote : Here’s a follow on tutorial explaining how to use Hype without responsive layout

Launch Hype and if it doesn’t automatically, create a new document. By default Hype assumes that you have a fixed size screen which isn’t true for Locly as we support every device from the iPhone 4s all the way up to the iPad. This isn’t a problem though because we can make our Hype document responsive. The first step is to open the “Scene” inspector panel and ensure the scale boxes are checked. This ensures that the Hype scene will scale and change size to fit our screen.

1

Next up we want to add some content to our scene. We’re going to add some hills and animals. Each time we add an element we need to ensure we update it’s constraints in the flexible layout panel. This indicates how the element will be anchored to the screen when it changes size. Add a hill image and click on the “Metrics” inspector.

2

As it stands our hill will keep a fixed distance to the top left of the screen. If you hover your mouse over the Preview pane you’ll notice as the screen increases and decreases with size the blue box remains in the top left. Not so good for our hill! We want our hill to sit in the bottom left of the screen, then grow and shrink along with the screen. To do this you will need to un-check the top pin, check the bottom pin and check the flexible width and height arrows so your layout constraints look more like this…

3

You should now see in the Preview pane that when the window stretches the blue box does too. You’ll notice that if you preview the scene in your browser it does as you would expect too.

I’m going to add another two hills to complete my landscape and also a couple of animals using similar rules to ensure they stretch and fill the screen as desired. With the animals you may want their scaling behaviour to be slightly different so they don’t distort. You can change this by using the “Scaling Behaviour” selector in the layout pane. Here’s my setup for my Monkey.

4

Download the tutorial up to this point

 

Running in Locly

To run this hype in Locly we’re going to run it as an inline widget. This requires a little side loading on the device but your users wont notice! The first thing we need to do is stub a call to make sure Hype will work. To do this click on the “Document” inspector and then click on the “Edit Head HTML” button.

8

You’ll need to paste the following line of code between the head tags

<script type="text/javascript"> window.widget = { notifyContentIsReady:function() { } };</script>

4a

Next go to the File menu > Export as HTML5 > Dashboard/iBooks Author Widget, when asked to give your hype a name make sure you name it “hype”. This will allow our side loading script to work automatically. Finally compress your hype export by right clicking on it and pressing “Compress hype.wdgt”.

Log in to the Locly website and create a new HTML card in your project. Upload your “hype.wdgt.zip” file along with the following “index_en.html(you may need to right click on the link and save as to download) file. By visiting the card on your device you should now see your Hype document.

 

Timelines

Now that we’ve sorted our layout and created some animals it’s time add some animations. We want the animals to appear separately when we trigger them. The first step is to click on each of the animals and in the “Element” inspector set their opacity to be 0.

5

Next we need to setup two separate timelines that we can trigger from a snippet of code. To do this we need to create a new timeline. Click on the “Scene” inspector and look for the “Animation Timelines” panel. Here we can press add to create a new timeline. You’ll need to give it a meaningful name as we’re going to use this later.

6

I named my timeline “elephant” so I know exactly what it’s going to trigger. To edit the timeline select it from the “Animation” inspector at the bottom of the screen (it may have selected it automatically if you just created the new timeline). Next click on the elephant (which is invisible because we set the opacity to zero) and then change its properties at the bottom. At time 0 we’ll re-set the opacity to 0, then at time 1 set it to be 1. This will mean the elephant will fade in over a second. You can test the timeline by pressing play to see your elephant fade in.

7

I’m going to do the same for my monkey and name the timeline “monkey”. Now we have two timelines that we can trigger depending on different events.

Download the tutorial up to this point

Beacons

Hype doesn’t support beacons out of the box, but the Locly app provides some useful tools to make supporting beacons super simple. The first thing we’re going to do is include the Locly library. To do this click on the “Document” inspector and then click on the “Edit Head HTML” button. You’ll need to paste the following bit of code in between the head tags…

<script type="text/javascript" src=“/LoclyClasses/LoclyCard.js”></script>

9

Now that we have access to the Locly libraries we can trigger some events based on which beacons we see. Go back to your scene and open the “Scene” inspector. We want to set it so that on scene load we run some JavaScript. Expand the “On Scene Load” accordion, click on the Action dropdown and then choose “Run JavaScript”. Another dropdown will appear, you’ll need to choose “New Function”. This will take you to the code editor. The first thing to do is change the name of the function by clicking on “untitledFunction” and entering “showAnimals”. Next you’ll need to paste the following code…


var elephantUUID = 'ACAC0102-03AA-47C8-9437-43030201ACAC';
var elephantMajor = 64187;
var elephantMinor = 8568;
var elephantTriggered = false;

var monkeyUUID = '16EAE908-F20C-4CB3-9CFC-1462805509BA';
var monkeyMajor = 15776;
var monkeyMinor = 10573;
var monkeyTriggered = false;

var check = function() {
	if (elephantTriggered && monkeyTriggered) { return; }
	locly.beacon.visible(function(beacons) {
		beacons.sort(function(a,b){ return b.averagedRSSI - a.averagedRSSI });
		var beacon = beacons[0];
		if (beacon) {
			if (!elephantTriggered && beacon.uuid === elephantUUID && beacon.major === elephantMajor && beacon.minor === elephantMinor) {
				hypeDocument.startTimelineNamed('elephant', hypeDocument.kDirectionForward);
				elephantTriggered = true;
			}
			if (!monkeyTriggered && beacon.uuid === monkeyUUID && beacon.major === monkeyMajor && beacon.minor === monkeyMinor) {
				hypeDocument.startTimelineNamed('monkey', hypeDocument.kDirectionForward);
				monkeyTriggered = true;
			}
		}

		setTimeout(check, 1000);
	});
};
check();

 

This checks for the visible beacons and if the closest one is the elephant or monkey it runs their respective timelines. You may need to change the UUID’s, Majors and Minors so that you can use the beacons you have.

10

Now if you re-export your Hype document and load it onto your device you will see the two animals appear depending on which beacon is nearest.

Download the tutorial up to this point

Advanced

To complete our Hype project we’re going to use beacons to change scenes and we’re also going to load a widget from Bookry.

Create a new scene in hype and then add an image to the scene. Select your image and open the “Actions” inspector. In here under the “On Mouse Click” section, click on the “action” dropdown and choose “Go to URL…”. Enter “widget://widget.wdgt.zip” into the URL box. This will launch a widget when we upload it to Locly. (I’ve provided a Bookry widget that we’ll use here at the end of the post).

 

11

 

To move to the next scene when you see a beacon in close proximity you will need to add another script to the “On Scene Load” action of the first scene. You can add the following code into that function to make the hype document change scene when the beacon is nearby.


var changeUUID = 'B9407F30-F5F8-466E-AFF9-25556B57FE6D';
var changeMajor = 60847;
var changeMinor = 34576;
var changeTriggered = false;

var check = function() {
	if (changeTriggered) { return; }
	locly.beacon.visible(function(beacons) {
		for (var i = 0; i < beacons.length; i++) { 			if (beacons[i].uuid === changeUUID && beacons[i].major === changeMajor && beacons[i].minor === changeMinor) { 				if (beacons[i].averagedRSSI > -50) {
					hypeDocument.showNextScene(hypeDocument.kSceneTransitionCrossfade, 1.1);
					changeTriggered = true;
				}
				break;
			}
		}

		setTimeout(check, 1000);
	});
};
check();

This checks the list of beacons and looks to see if the chosen one is close. (To test this you may need to change the UUID, major and minor to be that of one of your beacons). It checks to see if the RSSI is more than -50. RSSI on a simple level is received level of signal strength at the device. The higher the number, the closer the beacon. -50 normally indicates that the beacon is within a few centimeters of your iOS device. You may want to change this depending on your setup.

Download the source code and Assets

Download the exported files to upload to your own Locly Project

To find more information about the Locly API used in this tutorial you may find the documentation on GitHub helpful.

Have fun creating some engaging experiences with Locly!