#mirror api

Since Photos Are Boring Without Filters, Glassagram Will Spice Up Your Google Glass Pics

Thanks to Instagram, we rarely see photos taken from camera phones without some type of filter on it. Even Twitter’s photo service uses Aviary to drop an earthy overlay or black-and-white treatment onto your digital masterpiece. Google crystal users aren’t going to be left out of this craze thanks to an app aptly called Glassagram.

Again, this is the type of app that we’re seeing early on,…

At this point, you should have either the Java or the Python Mirror API Quick Start up and running. If you do not, please [check out this post](http://www.recursiverobot.com/post/82000012312/a-high-level-look-at-the-mirror-api), and [this post](http://www.recursiverobot.com/post/82000172161/google-glass-mirror-api-java-quick-start) (apologies that I don't have one for Python, just Java). This post is going to discuss how to use the quick start projects to begin making progress on your product. I'm going to talk about this in the context of a service that I'm working on building up, Hearty.io. I think that it's important to understand the product, and the goals of the product when approaching development. I also think that it is especially important with wearables to understand your product, and how that's going to work with wearables. ## Hearty.io

Let's get started by taking a look at what we have for a service, understanding it, and thinking about how we can use the Mirror API to extend it and offer something useful to our users. One note, Hearty.io is currently very rough and is missing quite a bit. What we will do here, is to define a current, fictional set of functionality, things that we can assume are already working. Again, to be clear, the following is a fictionalized description fo the service, that we will use for our purposes. Hearty.io is a fitness service with several components. There is an Android component, an Android Wear component, and Glassware. There is also a backend service that keeps all of the data synchronized. ### Android The Android app does automatic activity recognition, and tracking. It uses Google Play Services to determine what the user's current activity is, and then automatically tracks times when the user is active. The Android app posts a notification during times that it is tracking with the current activity, and the length of time tracked. The Android app also syncs with the server, and displays data from all three sources. ### Android Wear The Wear app does step counting, and syncs directly to Android using the Android Wear Data APIs. The Android notifications for Activity tracking show up on the watch, and there is a Wearable action that would allow the user to 'ignore' the current activity. ### Glass The Hearty.io Glassware uses the GDK and talks to a Bluetooth Heart Rate Monitor. The user launches the Glassware by saying 'Ok Glass, show my heart rate'. When Hearty launches, if there is no device paired, it redirects into a pairing UI. Once paired, Hearty.io inserts a LiveCard that displays the users's current heart rate. The Glassware syncs the user's heart rate directly with the server. ### Server The server just keeps track of three things for each user, each day's step count, number of active minutes, and average heart rate. ### New Mirror functionality The most obvious thing that I can think to do with Mirror here is to send the daily summary to the user on a daily basis. We also want to display that data in a dashboard for the user. There are a few things to consider here, beyond simply what we want to build. The primary consideration should be if it's something that makes sense, and would be a good experience on Glass. Mirror can be used to do things that don't result in a good experience. For example, news content is tricky to consume on Glass. Reading lots of text on a screen, or spending up to a minute listening is not ideal. WinkFeed does a great job of providing a good experience for news, mainly because of its Pocket integration. Sometimes, a clever feature can help your Glassware to go from a mediocre experience to a great one. Take a look at the [Glass Design Principles](https://developers.google.com/glass/design/principles) and think about whether what you're doing is in line with those principles. ### What we are going to build Let's build the following, a web service that uses a fake database, displays the dummy data to the user on a web app, and then allows the user to send that data to Glass. Wiring this up to our real service should be something that we know how to do, so we are not going to cover that here. We are also not going to do the work of automating this to run on a daily basis, that should be fairly straightforward. I'll cover Java first, if you're more interested in Python, feel free to skip down to that section. ## Java I'm going to assume that you've already been introduced to the quick start code, and so I'm going to skip the overview here. What we need to know is where we need to go in and what to modify. ### JSP The `index.jsp` file is what is used to generate the main web view. We are going to start by adding a section at the top with some dummy, hardcoded data. Place this above where the timeline cards are shown.

Heart Rate 77 Steps 17,311 Active Minutes 89

That will give us a table, without any actual data. Let's add a button at the top that uses the same sort of paradigm that all of the other buttons do on this page.

<form action="<%=%20WebUtil.buildUrl(request,%20">" method="post"> <input type="hidden" name="operation" value="insertHeartyData"><button class="btn btn-block" type="submit"> Insert a bundle with Hearty Data</button> </form>

Pretty easy, right? Notice that the value of the input is insertHeartyData, that's going to be important when we go to the servlet.

Now, let's make a quick side-trip, and add our dummy database.

FakeDatabase:

public class FakeDatabase { private static final ConcurrentHashMap<string heartydata> heartyData = new ConcurrentHashMap<string heartydata>(); private static Random rand = new Random(System.currentTimeMillis()); public static void generateFakeUserData(String userId) { HeartyData data = new HeartyData(); data.activeMinutes = rand.nextInt(110); data.stepCount = rand.nextInt(25000); data.heartRate = rand.nextInt(50) + 50; heartyData.put(userId, data); } public static HeartyData getUserData(String userId) { return heartyData.get(userId); } private FakeDatabase(){ // not allowed to instantiate } }

Ok, now that we have our database, we have to get data in there, so what we'll do for that is to add the following to the NewUserBootstrap:

public static void bootstrapNewUser(HttpServletRequest req, String userId) throws IOException { // snip ... FakeDatabase.generateFakeUserData(userId); // snip ... }

Back to the jsp, let's use our "real" data there:

<div class="span4"> <form action="<%=%20WebUtil.buildUrl(request,%20">" method="post"> <input type="hidden" name="operation" value="insertHeartyData"><button class="btn btn-block" type="submit"> Insert a bundle with Hearty Data</button> </form> <br><table class="table"><tbody><tr><th>Heart Rate</th> <td> </td> <th>Steps</th> <td> </td> <th>Active Minutes</th> <td> </td> <td> </td> </tr></tbody></table></div>

That about does it for the viewing side, let's try to make this do something.

Servlets

The quick start uses a Servlet for handling all of the POST requests from the web page, as well as all of the subsequent Mirror requests. We can copy one of the other insert methods, and modify it a bit for our purposes.

if (req.getParameter("operation").equals("insertHeartyData")) { LOG.fine("Inserting Hearty Timeline Item"); String bundleId = String.valueOf(System.currentTimeMillis()); TimelineItem timelineItem = new TimelineItem(); Attachment bundleCover = new Attachment(); String imgLoc = WebUtil.buildUrl(req, "/static/images/hearty_640x360.png"); URL url = new URL(imgLoc); bundleCover.setContentType("image/png"); timelineItem.setText("Hearty.io"); timelineItem.setBundleId(bundleId); timelineItem.setIsBundleCover(true); TimelineItem timelineItemHeart = new TimelineItem(); timelineItemHeart.setText("Heart Rate: " + FakeDatabase.getUserData(userId).heartRate); timelineItemHeart.setBundleId(bundleId); TimelineItem timelineItemSteps = new TimelineItem(); timelineItemSteps.setText("Steps: " + FakeDatabase.getUserData(userId).stepCount); timelineItemSteps.setBundleId(bundleId); TimelineItem timelineItemActivity = new TimelineItem(); timelineItemActivity.setText("Active minutes: " + FakeDatabase.getUserData(userId).activeMinutes); timelineItemActivity.setBundleId(bundleId); // Triggers an audible tone when the timeline item is received timelineItem.setNotification(new NotificationConfig().setLevel("DEFAULT")); MirrorClient.insertTimelineItem(credential, timelineItem, "image/png", url.openStream()); MirrorClient.insertTimelineItem(credential, timelineItemHeart); MirrorClient.insertTimelineItem(credential, timelineItemSteps); MirrorClient.insertTimelineItem(credential, timelineItemActivity); message = "A timeline item has been inserted."; }

That's a big chunk of code, but there are lots of repeated bits in there. Let's break it apart and look at it piece by piece.

There is a repeated pattern, that I'm going to show here:

TimelineItem timelineItemHeart = new TimelineItem(); timelineItemHeart.setText("Heart Rate: " + FakeDatabase.getUserData(userId).heartRate); timelineItemHeart.setBundleId(bundleId); MirrorClient.insertTimelineItem(credential, timelineItemHeart);

The above is the basics for inserting an item into the timeline. Notice that the bundleId is set as well, that allows this Card to be bundled with other Cards with the same bundleId.

You'll notice that the full block of code that was posted just repeats that pattern a few times to create four cards, a cover and three children.

Wrapping up with Java

From here, what I did was to move the Hearty.io pieces out of MainServlet and into both its own Servlet, and its own jsp file. When you do this, you'll need to modify web.xml to map the new path to the correct servlet. You can see the final version of the code here.

Python

As with Java, I'm going to assume that you've already been introduced to the quick start code, and so I'm going to skip the overview here. What we need to know is where we need to go in and what to modify.

As a note, this is going to be very similar to the Java portion. Partly because it does the same thing, partly because the quick start code structures are fairly similar, and mostly because I'm lazy.

HTML Template

The index.html file is what is used to generate the main web view. We are going to start by adding a section at the top with some dummy, hardcoded data. Place this above where the timeline cards are shown.

<div class="span4"> <br><table class="table"><tbody><tr><th>Heart Rate</th> <td> 77 </td> <th>Steps</th> <td> 17,311 </td> <th>Active Minutes</th> <td> 89 </td> <td> </td> </tr></tbody></table></div>

That will give us a table, without any actual data. Let's add a button at the top that uses the same sort of paradigm that all of the other buttons do on this page.

<form action="/hearty" method="post"> <input type="hidden" name="operation" value="insertHeartyData"><input type="hidden" name="heart_rate" value="77"><input type="hidden" name="step_count" value="17,311"><input type="hidden" name="active_minutes" value="89"><button class="btn btn-block" type="submit"> Insert a bundle with Hearty Data</button> </form>

Pretty easy, right? Notice that the value of the input is insertHeartyData, that's going to be important when we go to the handler. Also notice that I've got several input values, these are for passing values from the web frontend to the backend. There's probably a way to attach this to a session, but I don't know Python that well, and again, lazy.

Now, let's make a quick side-trip, and add some sort of data generator.

Hearty:

class Hearty(object): def __init__(self): self.heart_rate = random.randrange(40,135,1) self.step_count = random.randrange(2000,28000,1) self.active_minutes = random.randrange(17,132,1)

Ok, now that we have our data, we have to get data in there, so what we'll do for that is to add the following in the get method:

@util.auth_required def get(self): # snip ... self.hearty = Hearty() self._render_template(message)

And our render template method:

def _render_template(self, message=None): """Render the main page template.""" template_values = {'userId': self.userid, 'hearty': self.hearty } # snip ...

This means that every time we refresh the page, we will see new values.

Back to the template, let's use our "real" data there:

<div class="span4"> <form action="/hearty" method="post"> <input type="hidden" name="operation" value="insertHeartyData"><input type="hidden" name="heart_rate" value="{{ hearty.heart_rate }}"><input type="hidden" name="step_count" value="{{ hearty.step_count }}"><input type="hidden" name="active_minutes" value="{{ hearty.active_minutes }}"><button class="btn btn-block" type="submit"> Insert a bundle with Hearty Data</button> </form> <br><table class="table"><tbody><tr><th>Heart Rate</th> <td> {{ hearty.heart_rate }} </td> <th>Steps</th> <td> {{ hearty.step_count }} </td> <th>Active Minutes</th> <td> {{ hearty.active_minutes }} </td> <td> </td> </tr></tbody></table></div>

That about does it for the viewing side, let's try to make this do something.

Handlers

The quick start uses a handler for handling all of the POST requests from the web page, as well as all of the subsequent Mirror requests. We can copy one of the other insert methods, and modify it a bit for our purposes.

def _insert_hearty_item(self): """Insert a Hearty.io timeline item.""" logging.info('Inserting hearty timeline item') bundle_id = `random.random()` body = { 'notification': {'level': 'DEFAULT'}, 'text': 'Hearty.io python', 'isBundleCover': True, 'bundleId': bundle_id } heart_rate = self.request.get('heart_rate') step_count = self.request.get('step_count') active_minutes = self.request.get('active_minutes') body_a = { 'text': 'Heart Rate: ' + heart_rate, 'bundleId': bundle_id } body_b = { 'text': 'Steps: ' + step_count, 'bundleId': bundle_id } body_c = { 'text': 'Active Minutes: ' + active_minutes, 'bundleId': bundle_id } media_link = util.get_full_url(self, "/static/images/hearty_640x360.png") resp = urlfetch.fetch(media_link, deadline=20) media = MediaIoBaseUpload( io.BytesIO(resp.content), mimetype='image/png', resumable=True) # self.mirror_service is initialized in util.auth_required. self.mirror_service.timeline().insert(body=body, media_body=media).execute() self.mirror_service.timeline().insert(body=body_a).execute() self.mirror_service.timeline().insert(body=body_b).execute() self.mirror_service.timeline().insert(body=body_c).execute() return 'A timeline item has been inserted.'

That's a big chunk of code, but there are lots of repeated bits in there. Let's break it apart and look at it piece by piece.

There is a repeated pattern, that I'm going to show here:

heart_rate = self.request.get('heart_rate') body_a = { 'text': 'Heart Rate: ' + heart_rate, 'bundleId': bundle_id } self.mirror_service.timeline().insert(body=body_a).execute()

The above is the basics for inserting an item into the timeline. Notice that the bundleId is set as well, that allows this Card to be bundled with other Cards with the same bundleId.

You'll notice that the full block of code that was posted just repeats that pattern a few times to create four cards, a cover and three children.

The only other thing going on here is adding the image to the bundle cover:

media_link = util.get_full_url(self, "/static/images/hearty_640x360.png") resp = urlfetch.fetch(media_link, deadline=20) media = MediaIoBaseUpload( io.BytesIO(resp.content), mimetype='image/png', resumable=True) # insert the cover body with the media into the timeline self.mirror_service.timeline().insert(body=body, media_body=media).execute()

Wrapping up with Python

From here, what I did was to move the Hearty.io pieces out of main_handler and into both its own handler, and its own template html file. When you do this, you'll need to modify main to map the new routes to the correct handler. You can see the final version of the code here.

Moving forward

This is the eighth of a series of posts discussing how to get Google Glass Mirror (Java) and GDK projects set up in various IDEs.

One of the most common questions that I get from people during workshops is how to get set up either the Mirror quick start, or the GDK project into Eclipse, Android Studio or IntelliJ.

This post will cover importing the Java Mirror Quick Start project into Eclipse.

0. Clone from GitHub

See previous post.

1. Install m2e plugin in Eclipse

Visit the m2e project site

Go to the Downloads section

Copy the latest m2e release URL

In Eclipse, go to Help -> Install Software

Paste the m2e link into the bar, hit 'enter' and give it a name, like m2e

Select the packages that come up when it loads

Install the m2e packages

Accept the license

Restart Eclipse

2. Import Project

File -> Import Project -> Maven -> Existing Maven Project

3. Hit 'Next' a few times

Then 'Finish' and you'll be done with that.

4. Update the oauth.properties file

I previously made a video with instructions on this. Google has also posted instructions for getting OAuth set up.

5. Fire up a terminal

Run the following from the root of the project:

$ mvn install $ mvn jetty:run

6. Finished!

This is the sixth of a series of posts discussing how to get Google Glass Mirror (Java) and GDK projects set up in various IDEs.

One of the most common questions that I get from people during workshops is how to get set up either the Mirror quick start, or the GDK project into Eclipse, Android Studio or IntelliJ.

This post will cover importing the Java Mirror Quick Start project into Android Studio.

0. Clone from GitHub

See previous post.

1. Import Project

In Android Studio, select Import Project.

2. Import project from existing model

Select Maven

3. Hit 'Next' a few times

Then 'Finish' and you'll be done with that.

4. Update the oauth.properties file

I previously made a video with instructions on this. Google has also posted instructions for getting OAuth set up.

5. Fire up a terminal

Run the following from the root of the project:

$ mvn install $ mvn jetty:run

6. Finished!

I recently ran a workshop at Andreessen Horowitz, which was an introduction to Google Glass. It was a lot of fun, so I figured that I would create a screencast out of the content. This is the second of two posts on the subject. This one is discussing the Mirror API Java Quick Start. Part 1 may be found here.

Related Material:

All slides: http://goo.gl/IvzY0P­

Code: http://goo.gl/1w5XpR­

MenuBuilder: http://goo.gl/lJe2cF­

I recently ran a workshop at Andreessen Horowitz, which was an introduction to Google Glass. It was a lot of fun, so I figured that I would create a screencast out of the content. This is the first of two posts on the subject. This one is discussing the Mirror API at a high level. Part 2 may be found here.

Related Material:

All slides: http://goo.gl/IvzY0P­

Code: http://goo.gl/1w5XpR­

MenuBuilder: http://goo.gl/lJe2cF­

Blog: http://goo.gl/AOGVc8­

I'm giving a few talks on the Mirror API for Google Glass, and I needed to organize some thoughts on it. I figured that writing a blog post would a good way to do that.

Here is the slide deck for the shared content of my Mirror talks:

Since I don't want to miss anything, I'm going to follow the structure of the slides in this post. What I am not going to do, is be consistent with languages. I'll be bouncing between Java and JavaScript, with bits of Android flavored Java thrown in for good measure. It really just comes down to what I have code for right now in which language. The goal here is to discuss the concepts, and to get a good high-level view.

What is the Mirror API?

What is it?

The Mirror API is one API available for creating Glassware. The main other option is the GDK. Mirror is REST based, mostly done server-side; it pushes content to Glass, and may listen for Glass to respond. The GDK is client-side, and is similar to programming for Android. The general rule of thumb, is that if you can do what you need to do with Mirror, that's the right choice. Mirror is a bit more constrained, and is likely to deliver a good user experience, without a lot of effort. It also allows Glass to manage execution in a battery friendly way.

What does it do?

Mirror handles push messages from servers, and responds as necessary to them. The basic case is that your server pushes a message to Glass, then the message displayed on Glass as a Timeline Card.

How does it work?

If you're coming from the Android world then you might be familiar with GCM, and push messages. Mirror works using GCM, similar to how Android uses GCM.

You can send messages to Glass, and receive messages from Glass. Sending messages is much easier than receiving messages. On the sending side, all you need is a network connection, and the ability to do the OAuth dance. If you want to receive data from Glass, you'll also need some way for Glass to reach you, via a callback URL.

What’s the flow?

Glass registers with Google's servers, and then your server sends requests to Google's servers, and Google's servers communicate with Glass. You can send messages to Google's servers, and you can receive messages back from Glass via callback URLs that you provide. With that, you can get a back and forth going.

SO MANY QUESTIONS?!?!?!

I know, there's a lot here. We'll try to step through as much as possible in this post.

Setting up

Before you do anything else, you'll need to head over to the Google Developer Console, and register your app. Create a new app, turn on 'Mirror API', and turn off everything else. Then, go into the Credentials section, so that you can get your Client Id and Client Secret. This is outlined pretty clearly in the Glass Quick Start documentation.

OAuth

To communicate with Glass, you'll first need to do do the OAuth dance. The user visits your website, and clicks a link that will ask them to authenticate with one of their Google accounts. It then asks for permission to update their Mirror Timeline. After that's done, you'll receive a request at the callback URL, with a code. The code needs to be exchanged for a token. Once you have the token, you can begin making authenticated requests. The token will expire, so you'll need to be able to re-request it when it does.

Further reading in the Quick Start.

Timeline

The timeline is the collection of Cards that you have on Glass, starting from the latest, and going back into the past. It also includes pinned cards, and things happening 'in the future', provided by Google Now.

Here's a video explanation from the Glass Team:

Why a Timeline?

Well, you'd have to ask the Glass team, why exactly a Timeline, but I could venture a guess. One of Glass's issues is that it is more difficult to navigate with. You can't dive into apps like you can on your phone, at least not quickly and easily. There's no 'Recent Apps' section, no home screen and no launcher (well, except from the voice commands).

Launching apps with voice commands allows you to do things, as opposed to going to an app and poking around. For example, saying OK Glass, start a bike ride launches Strava into a mode where it immediately begins tracking me with GPS and giving me feedback on that tracking. It does not let me look at my history there.

Glass tends to operate on push rather than pull. Glassware surfaces information to you, as it becomes relevant. This ability allows Glass to become incredibly contextual, though we have only seen bits of this so far with Google Now. Imagine a contextual Glassware that keeps a todo list of all of your tasks, both work and home. It could surface a Card when you get to your office with the highest priority work tasks that you have for that day. On the weekend, after you're awake, it could tell you that you need to get your car into the shop to get your smog check.

A typical category of Glassware today is news, which all work well with a push approach. Now, this is not terribly useful on Glass, as it's difficult to consume, but there are some good ones that have figured out how to deliver the content in a way that is pleasant to consume on Glass (Unamo, and CNN), or to allow you to save it off to Pocket for picking up later (Winkfeed).

The timeline is semi-ephemeral. Your cards will stick around for 7 days, and will be lost after that. Before you get all clingy and nostalgic, consider that that information is 7 days old, and will not only be stale, but difficult to even scroll to at that point. I have rarely gone back more than a day in my history to dig for something that I saw, and that was usually for a photo. Cards are usually a view into a service, so the information is rarely lost to the ether. Instead of scrolling for a solid minute trying to find something, you can pull out your phone and go to the app on your phone. Like G+ Photos, Gmail or Hangouts. Apps like Strava don't even put your recent rides in your timeline, you have to either go to the app or their website for history.

What are Cards?

Cards are the individual items in the timeline. Messages that you send from your server to Glass users typically end up as timeline cards on the user's Glass. There are a number of basic actions, as well as custom actions, that users can take on cards, depending on what the card supports. How this works will become apparent once we look at the code.

How do I insert Cards into the Timeline?

Using the API, of course! Let's look at how to do this in a couple of languages.

Java:

TimelineItem timelineItem = new TimelineItem(); timelineItem.setText("Hello World"); Mirror service = new Mirror.Builder(new NetHttpTransport(), new JsonFactory(), null).setApplicationName(appName).build(); service.timeline().insert(timelineItem).setOauthToken(token).execute();

JavaScript:

client .mirror.timeline.insert( { "text": "Hello world", "menuItems": [ {"action": "DELETE"} ] } ) .withAuthClient(oauth2Client) .execute(function (err, data) { if (!!err) errorCallback(err); else successCallback(data); });

Further reading in the Developer Guides, and Reference.

Locations

Location with Glass can mean one of two things, either you're pushing a location to Glass, so that the user can use it to navigate somewhere. Or, you're requesting the user's location from Glass. The Field Trip Glassware subscribes to the user's location so that it can let the user know about interesting things in the area.

Sending Locations to Glass

Sending locations is very simple. Basically, you send a timeline card with a location parameter, and add the NAVIGATION menu item.

JavaScript:

client .mirror.timeline.insert( { "text": "Let's meet at the Hacker Dojo!", "location": { "kind": "mirror#location", "latitude": 37.4028344, "longitude": -122.0496017, "displayName": "Hacker Dojo", "address": "599 Fairchild Dr, Mountain View, CA" }, "menuItems": [ {"action":"NAVIGATE"}, {"action": "REPLY"}, {"action": "DELETE"} ] } ) .withAuthClient(oauth2Client) .execute(function (err, data) { if (!!err) errorCallback(err); else successCallback(data); });

I'm using this right now for something very simple. In a Mirror/Android app that I'm working on, I can share locations from Maps to Glass, and then use Glass for navigation. Nothing is more annoying than having Glass on and then using your phone for navigation because the street is impossible to pronounce correctly.

Getting Locations from Glass

This is a little more tricky. First, you need to add a permission to your scope, https://www.googleapis.com/auth/glass.location. Getting locations back from Glass is going to require you to have a real server that is publicly accessible. It should also support SSL requests if you're in production.

Here's some code from the Java Quick Start that deals with handling location updates:

LOG.info("Notification of updated location"); Location location = MirrorClient.getMirror(credential).locations().get(notification.getItemId()).execute(); LOG.info("New location is " + location.getLatitude() + ", " + location.getLongitude()); MirrorClient.insertTimelineItem( credential, new TimelineItem().setText("Java Quick Start says you are now at " + location.getLatitude() + " by " + location.getLongitude()) .setNotification(new NotificationConfig().setLevel("DEFAULT")) .setLocation(location).setMenuItems(Lists.newArrayList(new MenuItem().setAction("NAVIGATE"))));

This will really help enable contextual Glassware. You could imagine Starbucks Glassware that offers you a discounted coffee when you get near a Starbucks. Or a Dumb Starbucks Glassware that does the same thing, but claims to be an art installation.

Further reading in the Developer Guides, and Reference.

Menus

Menus are the actions that a user can take on a card. They make cards interactive. The most basic one is DELETE, which, obviously, allows the user to delete a card. Other useful actions are REPLY, READ_ALOUD, and NAVIGATE.

You can see menu items added to cards in previous examples. I will repeat the JavaScript navigation example here:

JavaScript:

client .mirror.timeline.insert( { "text": "Let's meet at the Hacker Dojo!", "location": { "kind": "mirror#location", "latitude": 37.4028344, "longitude": -122.0496017, "displayName": "Hacker Dojo", "address": "599 Fairchild Dr, Mountain View, CA" }, "menuItems": [ {"action":"NAVIGATE"}, {"action": "REPLY"}, {"action": "DELETE"} ] }) .withAuthClient(oauth2Client) .execute(function (err, data) { if (!!err) errorCallback(err); else successCallback(data); });

The Card generated from the example should allow you to get directions to the Hacker Dojo. You can also add custom menus, like Winkfeed's incredibly useful Save to Pocket menu item.

Further reading in the Developer Guides, and Reference.

Subscriptions

Subscriptions allow you to get data back from the user. This can happen automatically, if you're subscribed to the user's locations, or when the user takes some action on a card that is going to interact with your service. E.g., you can subscribe to INSERT, UPDATE, and DELETE notifications. You will also get notifications if you support the user replying to a card with REPLY.

In Java:

// Subscribe to timeline updates MirrorClient.insertSubscription(credential, WebUtil.buildUrl(req, "/notify"), userId, "timeline");

Subscriptions require a server, and cannot be done with localhost. However, tools like ngrok may be used to get a publicly routable address for your localhost. I have heard that ngrok does not play nice with Java, but you might be able to find another tool that does.

Among other things, you can learn from these sorts of subscriptions. You can learn which types of Cards get deleted the most, for example. Subscriptions can also listen for custom menus, voice commands and locations. With Evernote, you can say, take a note and it will send the text of your note to the Evernote Glassware.

Further reading in the Developer Guides, and Reference.

Contacts

Another important type of subscription is subscribing for SHARE notifications. The SHARE action also involves Contacts.

Contacts are endpoints for content. They can be Glassware or people, though if they're people, they are probably still really some sort of Glassware that maps to people. Sharing to Contacts allow your Glassware to receive content from other Glassware. You can insert a Contact into a user's time like so (in JavaScript):

client .mirror.contacts.insert( { "id": "emil10001", "displayName": "emil10001", "iconUrl": "https://secure.gravatar.com/avatar/bc6e3312f288a4d00ba25500a2c8f6d9.png", "priority": 7, "acceptCommands": [ {"type": "POST_AN_UPDATE"}, {"type": "TAKE_A_NOTE"} ] }) .withAuthClient(oauth2Client) .execute(function (err, data) { if (!!err) errorCallback(err); else successCallback(data); });

It's obvious what you want people Contacts for, but what about Glassware contacts? Well, imagine sharing an email with Evernote, or a news item with Pocket. Now, consider that as the provider of the email or news item, you don't need to provide the Evernote or Pocket integration yourself, you just need to allow sharing of that content. It's a very powerful idea, analogous to Android's powerful sharing functionality.

Further reading in the Developer Guides, and Reference.

Code Samples

I have three sample projects that I have been pulling code from for this post.

A slightly modified Java Quick Start provided by the Glass Team

My Android Mirror demo

Sometimes you want to access your user's shared Timeline Cards.  You can inspect each of the timeline items that you've created and that your Glass user has shared with you.

Why Grab a Timeline Card?

Sometimes you need to interact with something your user shared with your service, or you may want to revisit some information that was posted before.

How it works

In order to add a fetch timeline content, the user must first authorize you to access their timeline.  You do this by requesting access to this scope:

https://www.googleapis.com/auth/glass.timeline

To fetch a Timeline Card, you'll need to know the ID of the desired Timeline Card, which comes when you Subscribe to Timeline Updates or when you Fetch Glass Timeline Items.

Once the user grants you access to their timeline, you can fetch their timeline by accessing the this URL:

https://www.googleapis.com/mirror/v1/timeline/{id}

If everything was successful, you’ll recieve JSON back from Google describing a timeline card.

The format of that JSON looks like this:

{ "kind":"mirror#timelineItem", "id":"3664d583-f39f-4a15-99dc-d2860c722f78", "selfLink":"https://www.googleapis.com/mirror/v1/timeline/3664d583-f39f-4a15-99dc-d2860c722f78", "created":"2013-12-18T17:27:05.019Z", "updated":"2013-12-18T17:27:08.301Z", "displayTime":"2013-12-18T17:27:05.019Z", "etag":"1387387628301", "recipients":[ { "kind":"mirror#contact", "source":"api:56129176202", "id":"example.com_service", "displayName":"Example Service Name", "imageUrls":[ "https://example.com/glass_content_icon.png" ], "priority":"7" } ], "attachments":[ { "id":"ps:5958782948912901890", "contentType":"image/jpeg", "contentUrl":"https://www.googleapis.com/mirror/v1/timeline/3664d583-f39f-4a15-99dc-d2860c722f78/attachments/ps:5958782948912901890?alt=media" } ], "menuItems":[ { "action":"DELETE" } ] }

An important thing to note is that the only timeline content your service will be able to see is what you have created or your glass user has chosen to share with you.

Notice that there is a section of JSON that defines attachments:

"attachments":[ { "id":"ps:5958782948912901890", "contentType":"image/jpeg", "contentUrl":"https://www.googleapis.com/mirror/v1/timeline/3664d583-f39f-4a15-99dc-d2860c722f78/attachments/ps:5958782948912901890?alt=media" } ],

This attachment tells us what type of attachment we have and how to fetch it. Similar to retrieving the Timeline, we can ask for the content by fetching the "contentURL" after authentication - in this example:

https://www.googleapis.com/mirror/v1/timeline/3664d583-f39f-4a15-99dc-d2860c722f78/attachments/ps:5958782948912901890?alt=media

Implementation

Following the previous tutorials, we will create the following file structure, which will allow us to create the OAuth2 authentication, then fetch a Timeline Card

classes

Google_Contact.class.php

Google_Location.class.php

Google_Menu_Item.class.php

Google_Menu_Item_Value.class.php

Google_OAuth2.class.php

Google_OAuth2_Token.class.php

Google_Timeline_Item.class.php

Google_Timeline_Item_Attachment.class.php

HttpPost.class.php

index.php

oauth2callback

index.php

settings.php

Settings

In order to move forward, we will need to set up our OAuth2 App settings.

See the source code at: https://github.com/backupbrain/glass-fetch-timeline-cards-php/blob/master/settings.php

Classes

If you’ve been following these posts, you already know that we use class classes/HttpPost.class.php, that uses cURL to communicate with the Google Mirror servers. You also know that we have classes classes/Google_OAuth2.class.php and classe/Google_Oauth2_Token.class.php to handle the OAuth2 authentication process.

HttpPost.class.php allows us to execute HTTP requests through PHP and cURL, a critical component of talking to the Google Mirror API. https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/classes/HttpPost.class.php

classes/Google_OAuth2.class.php makes the initial request to begin the user’s authentication process.   https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/classes/Google_OAuth2.class.php

classes/Google_OAuth2_Token.class.php stores the post-authentication token.  We use this to verify that we are speaking on behalf of the user when we talk to the Google Mirror API https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/classes/Google_OAuth2_Token.class.php

If you aren’t familiar with these classes or how they work, you can check out the following tutorials to see how it works:

Fetch Glass Timeline Items

Subscribe to Timeline Updates

Add Your Service as a Contact

Adding Menu Options to Timeline Cards

Determine a User’s Location

Identifying Your Users

Once you’ve set up these classes, you can create the classes that describe how to process and manage Timeline Cards.

Google uses JSON POST to communicate information about Glass Timeline content with the Mirror API.  We can make working with the Timeline easier by building as series of PHP objects that mirror the JSON data structures understood by Google.

The basic Timeline data structure looks like this:

classes/Google_Timeline_Item.class.php lets us process a Timeline Card.  A Timeline_Item also contains Menu_Items, Notifications, and Attachments.

https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/classes/Google_Timeline_Item.class.php

classes/Google_Timeline_Item_Attachment.class.php describes a Timeline Card attachment and how to fetch it from Google.  You'll notice in the JSON example above that an attachment of image/jpeg exists with an image id.  We can later fetch that image separately from Google. https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/classes/Google_Timeline_Item_Attachment.class.php

classes/Google_Menu_Item.class.php describes a menu item for that Timeline Card.  You'll remember from the Menu tutorial that you can insert menu items with the Timeline Card, providing users with options for how to engage with your content https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/classes/Google_Menu_Item.class.php

classes/Google_Menu_Item_Value.class.php describes the text and icons values for a custom menu item. https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/classes/Google_Menu_Item_Value.class.php

classes/Google_Notification.class.php describes the notification level for the Timeline Card. https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/classes/Google_Notification.class.php

classes/Google_Location.class.php describes location that the Timeline Card was shared from https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/classes/Google_Location.class.php

classes/Google_Contact.php describes the recipient of the shared Timeline item. https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/classes/Google_Contact.class.php

Controllers

Besides index.php which performs sets the scope and initiates the OAuth2 authentication request, there are two controllers for this tutorial: one to submit the subscription request, and one callback to handle Mirror notifications of a user’s timeline interaction.

index.php sets the OAuth2 scope and initiates the authorization request: https://github.com/backupbrain/glass-fetch-timeline-cards-php/blob/master/index.php

When you encounters this for the first time, you will see a screen that looks like this:

The oauth2callback/index.php fetches a Timeline Card, then fetches the attachment. https://github.com/backupbrain/glass-fetch-timeline-card-php/blob/master/oauth2callback/index.php

When you log in and gets to the oauth2callback/index.php page, you will see something like this showing the details of the Timeline Card you fetched, and the image attachment that you downloaded.

That's it.  Now you can inspect Timeline Cards and their attachments.

More Information

The source code for this tutorial is available on GitHub:

https://github.com/backupbrain/glass-fetch-timeline-card-php

Fetch Glass Timeline Items http://20missionglass.tumblr.com/post/70635819823/fetch-glass-timeline-items Learn to fetch shared Timeline cards.  This tutorial sets up all the classes used in this tutorial and lets you inspect all your user's shared timeline cards including their IDs.

Subscribe to Timeline Updates http://20missionglass.tumblr.com/post/70422209750/subscribe-to-timeline-updates Learn how to receive notifications when your users interact with your service.

Add Your Service as a Contact http://20missionglass.tumblr.com/post/67676363275/add-your-service-as-a-contact Learn to add your service as a Contact to a user’s Glass. Required reading for this tutorial

Adding Menu Options to Timeline Cards http://20missionglass.tumblr.com/post/70031065981/adding-menu-options-to-timeline-cards Learn to add menu items to Glass Timeline content, empowering users to engage with your service in a variety of ways.

Programming an OAuth2 Client in PHP http://20missionglass.tumblr.com/post/60787835108/programming-an-oauth2-client-app-in-php Learn to use cURL to perform an OAuth2 authentication in PHP

Timeline Reference https://developers.google.com/glass/v1/reference/timeline Google Mirror API Documentation for the properties of a Timeline object