Contacts

Contacts let your Glassware receive timeline items that it did not create. Users must explicitly share a timeline item with your contact by tapping on a card's Share menu item.

How they work

Once you create a sharing contact, sharing timeline cards follows this general flow:

1. Create a contact and define MIME types that your contact supports.
2. Insert the contact to your user's timeline.
3. The user receives a timeline item that has a Share menu item. Glassware must explicitly allow users to share their items with this menu item.
4. The user taps the timeline item, selects the Share menu item, and selects your contact.
5. The Mirror API creates a copy of the shared timeline card, gives your contact access to the copy, and inserts the copy into the user's timeline. Your Glassware cannot access the original timeline item.
6. If you subscribed to share notifications, you receive a payload containing the timeline card's identifying information. You can then retrieve the timeline item with Timeline.get.
7. You modify the shared timeline card and update the existing timeline card with Timeline.update.

When to use them

By default, Glassware cannot access timeline items that it did not create, so contacts allow Glassware to Glassware data sharing with user consent.

There are two main 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.

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

Creating a contact

To allow users to share timeline items with your Glassware, insert a contact by POSTing a JSON representation of a contact to the insert REST endpoint.

All contacts must specify an id, which identifies the contact to the Glassware receiving the notifications. You must also specify a displayName and at least one imageUrls, which Glass uses to display the contact information to the user.

Note: For best results, use a PNG icon image that is 640 by 360 pixels with a transparent background for imageUrls.

Raw HTTP

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

{
  "id": "harold"
  "displayName": "Harold Penguin",
  "iconUrl": "https://developers.google.com/glass/images/harold.jpg"
  "priority": 7
}

Subscribing to sharing notifications

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.

Note: In production, your callback URL must support SSL. For development purposes, we provide an subscription proxy server that can forward notifications to your non-SSL development server.

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

Raw HTTP

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

The itemId attribute is the ID of the shared timeline item, which you can use with Timeline.get to obtain the timeline item. The following example shows a typical timeline item with a photo attachment:

{
  "id": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "attachments": [
      {
          "contentType": "image/jpeg",
          "id": "<ATTACHMENT_ID>"
      }
  ],
  "recipients": [
      {
          "kind": "glass#contact",
          "source": "api:<SERVICE_ID>",
          "id": "<CONTACT_ID>",
          "displayName": "<CONTACT_DISPLAY_NAME>",
          "imageUrls": [
              "<CONTACT_ICON_URL>"
          ]
      }
  ]
}

Your service must respond to the API with a 200 OK HTTP status code if no error occurred. If your service responds with an error code, the Mirror API might try to resend the notification to your service.

Note: The connection will time out after 10 seconds. If a long process is required, respond right away and do the process in another thread.

Receiving speech transcription

Users can share transcribed speech with your contact through the main voice menu. There are currently two voice commands that your contact can use:

• "take a note"
• "post an update"

For example, a user can tell us about Chipotle's upcoming birthday with the phrase: "Ok Glass... post an update to... Cat Stream... Chipotle's birthday is tomorrow!"

To use voice commands:

1. Specify the acceptCommands property with the appropriate type:

   {
     ...
   
     "displayName": "Cat Stream",
     "id": "CAT_STREAM",
     "acceptCommands": [
       {"type": "POST_AN_UPDATE"}
     ]
   }
   

2. Subscribe to timeline notifications to be notified that transcribed speech is available. Your Glassware receives a notification when this occurs:

   {
     "collection": "timeline",
     "operation": "UPDATE",
     "userToken": "<USER_TOKEN>",
     "verifyToken": "<VERIFY_TOKEN>",
     "itemId": "<ITEM_ID>",
     "userActions": [
       {"type": "LAUNCH"}
     ]
   }
   

3. Use the itemId to fetch the timeline item:

   {
     "id": "<ITEM_ID>",
     "text": "Chipotle's birthday is tomorrow",
     "recipients": [
       {"id": "CAT_STREAM"}
     ]
   }
   

   Note: When you receive the shared timeline item, update the existing timeline card with Timeline.update instead of creating a new one if you are modifying the item.

4. If more than one Glassware registers a contact with the same voice command, Glass displays a second-level menu showing the displayName of each contact. Users can then speak the contact of their choosing. If your contact's displayName contains unpronounceable characters or is not phonetic, use the speakableName property to declare the expected pronunciation of your sharing contact.

Captions for shared photos

Users have the ability to share photos with your Glassware with an accompanying caption that they input with speech. The general user flow is:

1. The user taps a timeline item containing a photo, selects the Share menu item, and selects your contact.
2. The user taps again within a short period of time to add a caption to the photo.
3. The user speaks a caption.
4. The timeline item is shared with your Glassware as described previously in How they work. In addition, the timeline item's text property is set with the user's transcribed caption.