Mirror API – La timeline e le card

Di - 24 April 2013 - in
Post image for Mirror API – La timeline e le card

Come vi abbiamo annunciato, alcuni giorni fa sono uscite le Mirror API, utili a creare software per i nuovi Google Glass. In questa serie di articoli analizzeremo meglio l’architettura delle applicazioni per Glass, molto diversa da quella a cui ci ha abituati Android, e le funzioni offerte dalle API. In particolare in questo articolo si vedrà il concetto e l’implementazione della timeline.

L’architettura di sviluppo per Glass deriva in larga parte dal modello di interazione con l’utente, che è necessariamente molto diverso da qualunque cosa si sia vista sul mercato finora. Parliamo infatti di un dispositivo che cerca di inserirsi in maniera naturale nell’esperienza quotidiana del suo utente, e che richiede quindi un’interazione meno invasiva possibile.

L’interfaccia utente di Glass è formata da card, ovvero semplici tessere rettangolari che possono essere fatte scorrere, e possono essere aperte. Ogni applicazione può generare una o piú card, che andranno ad aggiungersi, cronologicamente, al flusso di sistema detto timeline. Le card possono essere anche raggruppate tra loro, formando cosí una pila.

Una card può contenere elementi di vario genere: testo, immagini, html, video, ed elementi di menu per compiere azioni. Alcune card possono essere “bloccate”, rimanendo cosí sempre nella stessa posizione senza scorrere con il flusso: esempi ovvi sono le card di sistema, come l’orologio o il menu delle applicazioni, ma l’utente ha la facoltà di bloccare qualunque card lo consenta.

Un’altra particolarità di Glass è il fatto che le applicazioni non girano in locale sul dispositivo, ma risiedono e vengono eseguite su cloud o comunque online, come servizi web ai quali l’utente si iscrive. L’unico modo che le applicazioni hanno per creare elementi nella timeline è dunque quello di interagire con un servizio web fornito da Google, dal quale poi Glass riceve ciò che deve mostrare all’utente.

Le API di Glass consistono dunque proprio nell’interfaccia di comunicazione tra i servizi applicazione e il servizio di Google. Tali API sono RESTful, e sono già ben documentate.

Chiarite le premesse, vediamo come creare oggetti in timeline.

Come ci si aspetta da un’interfaccia RESTful, ogni card della timeline è rappresentabile come JSON. Per i dettagli di tale rappresentazione, rimando alla documentazione delle card. Un dettaglio è però importante. Ogni card, assieme all’ID, ha un bundleId. Mentre il primo viene generato automaticamente e non è specificabile, il secondo può essere specificato in fase di creazione. Piú card con il medesimo bundleId verranno mostrate impilate fra loro. Si può anche creare una singola card suddivisa come una pila, specificando i contenuti dei vari elementi della pila, in html, nell’array htmlPages[].

La creazione di una nuova card è quanto di piú semplice si possa immaginare: basterà infatti inviare all’endpoint /mirror/v1/timeline una richiesta contenente la rappresentazione JSON della card stessa:

POST /mirror/v1/timeline HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer {token di autorizzazione}
Content-Type: application/json
Content-Length: 26

{ "text": "Hello world" }

Se la creazione ha successo, la risposta conterrà un codice 201 Created, assieme alla rappresentazione, completa dei dati generati automaticamente, della card.

HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-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"
}

La richiesta può contenere un’immagine, inviata attraverso la normale tecnica HTTP multipart, specificando un bonduary che separi la richiesta JSON dall’immagine e inviando l’immagine codificata. L’immagine sarà poi mostrata come sfondo della card:

POST /mirror/v1/timeline HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer {auth token}
Content-Type: multipart/related; boundary="mymultipartboundary"
Content-Length: {length}

--mymultipartboundary
Content-Type: application/json; charset=UTF-8

{ "text": "A solar eclipse of Saturn. Earth is also in this photo. Can you find it?" }
--mymultipartboundary
Content-Type: image/jpeg
Content-Transfer-Encoding: binary

[binary image data]
--mymultipartboundary--

Allo stesso modo, è possibile allegare altri tipi di contenuti. La lista degli allegati sarà contenuta nell’array attachments del JSON di risposta. Conoscendo l’ID di un allegato e l’ID della card, si può ottenere l’allegato attraverso una richiesta all’endpoint /mirror/v1/timeline/ID_CARD/attachments/ID_ALLEGATO.

Analizzato come si creano le card, è ora di permettere agli utenti di interagire con esse.
Le API definiscono una serie di azioni con relativi elementi di menu che possono venir creati:

  • REPLY – Dà la possibilità di rispondere attraverso l’interfaccia di riconoscimento vocale a una card condivisa da qualcuno. Per funzionare, ha bisogno della presenza dell’attributo creator che contiene il mittente della card.
  • REPLY_ALL – Identico al precedente, ma necessita anche dell’attributo recipients, in modo da inviare la card di risposta anche a tutti i destinatari della card originale
  • DELETE – Cancella la card
  • SHARE – Condivide la card con uno o piú contatti
  • READ_ALOUD – Attiva la sintesi vocale di ciò che è contenuto nell’attributo speakableText se settato, altrimenti di ciò che è in text. Se entrambi sono vuoti, non fa nulla.
  • VOICE_CALL – In presenza dell’attributo creator.phone_number, avvia una chiamata vocale col mittente della card
  • NAVIGATE – In presenza dell’attributo location, avvia il navigatore verso la posizione lí specificata
  • TOGGLE_PINNED – Modifica l’attributo isPinned, che specifica se la card è o no bloccata in evidenza

Basterà specificare uno di questi nell’attributo menuItems.action per creare il pulsante corrispondente. I pulsanti predefiniti esistenti evidenziano come si voglia, attraverso Glass, creare una sorta di rete sociale, di concezione innovativa, tra i suoi utenti.

Google+, con il suo sistema di condivisione a cerchie e con l’idea che inviare un messaggio privato sia, come azione, del tutto equivalente all’inviare un messaggio ad un’intera cerchia o al pubblico, sembra non essere altro che la prova generale della rete di Glass.

I video dimostrativi visti finora assumono un aspetto diverso e piú chiaro. Non avvieremo una videochiamata con un nostro contatto, ma condivideremo con lui la card della videocamera. Non mostreremo la nostra posizione ad un nostro amico, ma condivideremo con lui la card della mappa. Un modello di comunicazione nuovo a livello di interazioni, ma piú che familiare a chiunque usi il social hub di Google. Anche semplicemente a livello semantico, condividere, ad esempio, ciò che la nostra fotocamera vede, è qualcosa di molto piú naturale che telefonare mostrando un video.

Ovviamente, è possibile definire elementi di menu personalizzati specificando CUSTOM nel campo action ed impostando un ID, un testo e un’icona. Il sistema di notifica, se il pulsante verrà creato, genererà una notifica con l’ID, e l’app potrà reagire di conseguenza. Il sistema di notifica è piuttosto potente, ed introduce un altro aspetto proprio dell’esperienza utente di Google Glass, cosa che esploreremo nel prossimo articolo.

Infine, è possibile:

  • ottenere una lista delle card accessibili all’applicazione (ovvero quelle create dall’applicazione o quelle, vedremo come, condivise con l’applicazione) attraverso una richiesta GET vuota a /mirror/v1/timeline;
  • ottenere il JSON di una singola card attraverso una richiesta GET vuota a /mirror/v1/timeline/ID_DELLA_CARD;
  • aggiornare una card mandando i campi JSON aggiornati con una richiesta PUT a /mirror/v1/timeline/ID_DELLA_CARD ed eliminare una card attraverso una richiesta DELETE vuota a /mirror/v1/timeline/ID_DELLA_CARD.

Leave a Reply

Lorenzo Breda Articolo scritto da

Studente di Informatica a Roma, si occupa di programmazione web sopratutto lato server, e di accessibilità del web. Utilizza e ama Debian GNU/Linux, e si interessa di fisica, fumetto, trekking e fotografia (gli ultimi due possibilmente abbinati). Collabora con Googlab da aprile 2012.

Contatta l'autore

Previous post:

Next post: