Google Mirror API

Developer Zone

API Usage Stories

The Mirror API provides a set of building blocks that you can use to build services for Glass. Because Glass services are probably different than other software you have developed, it may not be obvious how to fit features of the Mirror API together.

Many services fall into a few categories of API usage. Here are some stories that illustrate how to combine the features of the Mirror API to create Glass services.

Cat Facts

Delivering content to the Glass timeline is a simple yet powerful use of the Google Mirror API. The Cat Facts sample Glassware delivers facts about cats to users and could potentially follow this flow:

Your user visits your web application and subscribes by authenticating with OAuth 2.0.

Every hour, on the hour, your service delivers a new Cat Fact to each of your users' Glass.

Timeline Items

When users interact with their timeline, the main way they receive information is in the form of timeline items, otherwise known as cards.

Timeline cards display content from various Glassware and swiping forward and backward on Glass reveals more cards in the past and future.

You can insert, update, read, and delete timeline cards from a timeline. In addition, you can attach objects to a timeline card, such as a location or media.

Inserting a timeline item

To insert a timeline item, POST a JSON representation of a timeline item to the REST endpoint.

Note: Timeline items last for seven days on a user's Glass and are deleted from Google's servers if not updated for ten days. Most of the fields in a timeline item are optional.

In its simplest form, a timeline item contains only a short text message, like in this example:

TimelineItem timelineItem = new TimelineItem();timelineItem.setText("Hello world");service.timeline().insert(timelineItem).execute();

HTTP/1.1 201 CreatedDate: Tue, 25 Sep 2012 23:30:11 GMTContent-Type: application/jsonContent-Length: 303

{ "kind": "glass#timelineItem", "id": "1234567890", "selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890", "created": "2012-09-25T23:28:43.192Z", "updated": "2012-09-25T23:28:43.192Z", "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"", "text": "Hello world"}

Inserting a timeline item with an attachment

A picture is worth a thousand words, which is a lot more than you can fit into a timeline item. To this end, you can also attach images and video to a timeline item. Here's an example of how to insert a timeline item with a photo attachment:

TimelineItem timelineItem = new TimelineItem();timelineItem.setText("Hello world");InputStreamContent mediaContent = new InputStreamContent(contentType, attachment);service.timeline().insert(timelineItem, mediaContent).execute();

Attaching video

If you are attaching video files to your timeline items, we recommend that you stream the video instead of uploading the entire payload at once.

The Google Mirror API supports streaming with HTTP live streaming, progressive download, and the real time streaming protocol (RTSP). RTSP is frequently blocked by firewalls, so use the other options when possible.

To stream video, use the PLAY_VIDEO built-in menu item and specify the video's URL to be the menu item's payload.

See Adding built-in menu items and supported media formats for more information.

BundlingBundling allows you to group related but distinct items together, like for individual messages in an email thread.

Bundles have a main cover card that a user taps to display a sub-timeline that contains the other cards in the bundle. Bundles are distinguished from normal timeline cards by a page curl in the upper right corner of the bundle's cover card.

Menu Items

Delivering content is only half of the story. Most interesting services also allow users to interact with timeline cards through menu items.

Menu items allow users to request actions that are related to the timeline card, and come in two types: built-in menu items and custom menu items.

Built-in menu items provide access to special functionalities provided by Glass, such as reading a timeline card aloud, navigating to a location, sharing an image, or replying to a message:

Custom menu items allow your application to expose behavior that is specific to your Glassware, and you can also provide a menu item icon to match your branding.

Defining custom menu items

Built-in actions may not always be enough. Many services need to expose their own specific menu items. This is where custom actions come into play.

Create a custom menu item by specifying a menuItem.action of CUSTOM and a menuItem.id.

When your user triggers one of your custom menu items, a notification is sent to your service with the menuItem.id populated. This allows you to determine the source of the notification.

You must also populate menuItem.menuValue to specify an iconUrl and displayName that will appear on the glass device.

HTTP/1.1 201 CreatedDate: Tue, 25 Sep 2012 23:30:11 GMTContent-Type: application/jsonContent-Length: 303

{ "text": "Hello world", "menuItems": [ { "action": "CUSTOM", "id": "complete" "values": [{ "displayName": "Complete", "iconUrl": "http://example.com/icons/complete.png" }] } ]}

Subscriptions

The Mirror API allows you to subscribe to notifications that are sent when the user takes specific actions on a Timeline Item or when the user location has been updated.

When you subscribe to a notification, you provide a callback URL that processes the notification.

Receiving notificationsA notification from the Mirror API is sent as a POST request to the subscribed endpoint containing a JSON request body.

{ "collection": "timeline", "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg", "operation": "UPDATE", "userToken": "harold_penguin", "verifyToken": "random_hash_to_verify_referer", "userActions": [ { "type": "<TYPE>", "payload": "<PAYLOAD>" } ]}

Notification types

The Mirror API sends a different notification payload for different events.

Shared timeline item

The user has shared a timeline item with your Glassware.

{ "collection": "timeline", "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg", "operation": "UPDATE", "userToken": "harold_penguin", "verifyToken": "random_hash_to_verify_referer", "userActions": [ { "type": "SHARE" } ]}

Reply

The user has replied to your timeline item using the built-in REPLY menu item:

{ "collection": "timeline", "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg", "operation": "INSERT", "userToken": "harold_penguin", "verifyToken": "random_hash_to_verify_referer", "userActions": [ { "type": "REPLY" } ]}

Delete

The user has deleted a timeline item:

{ "collection": "timeline", "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg", "operation": "DELETE", "userToken": "harold_penguin", "verifyToken": "random_hash_to_verify_referer", "userActions": [ { "type": "DELETE" } ]}

Custom menu item selected

The user has selected a custom menu item set by your service:

{ "collection": "timeline", "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg", "operation": "UPDATE", "userToken": "harold_penguin", "userActions": [ { "type": "CUSTOM", "payload": "PING" } ]}

Location update

A new location is available for the current user:

{ "collection": "locations", "itemId": "latest", "operation": "UPDATE", "userToken": "harold_penguin", "verifyToken": "random_hash_to_verify_referer"}

Voice command

Your user has activated a voice command, for example: "Ok Glass, take a note, Cat Stream, Chipotle's birthday is tomorrow".

The following notification is sent to your Glassware:

{ "collection": "timeline", "operation": "UPDATE", "userToken": "chipotle's_owner", "verifyToken": "mew mew mew", "itemId": "<ITEM_ID>", "userActions": [ {“type”: "LAUNCH"} ]}

Location

You can use the Google Mirror API to observe the user's location in timeline items, request their last known location directly, and subscribe to periodic location updates.

You can also deliver pre-rendered map images in timeline cards by giving the Mirror API the coordinates to draw.

Note: Retrieving users' location requires the additional https://www.googleapis.com/auth/glass.location scope.

Subscribing to location updates

Similar to subscribing to timeline updates, you can subscribe to location updates by subscribing to the locations collection.

POST /mirror/v1/subscriptions HTTP/1.1Authorization: Bearer {auth token}Content-Type: application/jsonContent-Length: {length}

{ "collection": "locations", "userToken": "harold_penguin", "verifyToken": "random_hash_to_verify_referer", "callbackUrl": "https://example.com/notify/callback"}

<article> <figure> <img src="glass://map?w=240&h=360&marker=0;42.369590, -71.107132&marker=1;42.36254,-71.08726&polyline=;42.36254, -71.08726,42.36297,-71.09364,42.36579,-71.09208,42.3697, -71.102,42.37105,-71.10104,42.37067,-71.1001,42.36561, -71.10406,42.36838,-71.10878,42.36968,-71.10703" height="360" width="240"> </figure> <section> <div class="text-auto-size"> <p class="yellow">12 minutes to home</p><p>Medium traffic on Broadway</p> </div> </section></article>

Contacts

Contacts can be people or Glassware that users can share timeline items with. By default, Glassware cannot access timeline items that it did not create. Sharing to contacts allows users to share a timeline item with Glassware that did not create that timeline item.

There are two ways that your Glassware can use contacts:

Allow users to share your timeline items with other contacts: Add the SHARE built-in menu item to a timeline card. When users tap the share menu item, Glass displays a list of possible contacts to share with. See the menu items developer guide for more information on how to add built-in menu items.

Allow users to share timeline items with your Glassware: Create a contact that represents your Glassware. When users want to share a timeline card, your contact appears as an option. You can also declare a list of acceptable MIME types so that your contact only appears for cards that you are interested in. To get notified of when users share a timeline card with your contact, you can subscribe to timeline notifications.

How sharing works

Declaring voice menu commands

You can let users share timeline items with your Contact by inserting a voice command in the "OK Glass" menu. When triggered, voice commands share a timeline item with your contact that includes a transcription of your user's speech.

You can declare the following voice commands for your contact:"take a note""post an update"

Create a client ID and client secret

First, you need to activate the Google Mirror API for your app. You can do this for your API project in the Google APIs Console.

Create an API project in the Google APIs Console.

Select the Services tab in your API project, and enable the Google Mirror API.

Select the API Access tab in your API project, and click Create an OAuth 2.0 client ID.

In the Branding Information section, provide a name for your application (e.g. "My Glass service"), and click Next. Providing a product logo is optional.In the Client ID Settings section, do the following:

Select Web application for the Application type.Click the more options link next to the heading, Your site or hostname.List your hostname in the Authorized Redirect URIs and JavaScript origins fields.Click Create Client ID.

In the API Access page, locate the section Client ID for Web applications and note the Client ID and Client Secret values.

https://developers.google.com/glass/tools-downloads/playground

Your Google Glass Playground

Let’s Play with Future