lunedì 10 agosto 2015

Microsoft Band SDK su Channel9

Se siete interessati allo sviluppo per il Microsoft BAND vi segnalo la mia “serie” su Channel9 Microsoft Band SDK.
Al momento ci sono due webcast relativi all’SDK su Windows e alle Web Tiles.

venerdì 31 luglio 2015

Microsoft Band SDK – Web Tile : REST

In questo post, ultimo di questa mini serie dedicata alle Web Tile, vedremo come sia possibile realizzare una tile che visualizza dei dati presi da un servizio REST.
Il servizio che utilizzeremo è un semplicissimo servizio REST, hostato su Azure, che permette di eseguire il ping verso un indirizzo web.
Il servizio risponde all’url

http://webtileapi.azurewebsites.net/api/Ping?urlToPing=<url da verificare>

e lo fa con un JSON del tipo

{
  "UrlPinged": "<url da verificare>",
  "Result": 0,
  "ResultString": "Ok",
  "PingDurationInMilliseconds": 100,
  "PingDateTime": "2015-07-27T18:02:57.1500904Z"
}

in cui troviamo il risultato del ping (OK o ERROR), il tempo di attesa e il timestamp di esecuzione dell’operazione.
Quello che vogliamo fare è creare una Web Tile in grado di mostrare le statistiche per due siti e i dettagli per ogni sito, quindi un totale di 3 pagine.
In questo caso, tralasciando la parte del file manifest.json relativa ai metadati, i punti cruciali del file stesso sono la definizione delle risorse (con le relative variabili da utilizzare) e la definizione delle pagine.
Partiamo con la definizione delle risorse:

"resources": [
    {
      "url": "http://webtileapi.azurewebsites.net/api/Ping?urlToPing=http://www.dotnetpodcast.com",
      "style": "Simple",
      "content": {
        "DNPpingdatetime": "PingDateTime",
        "DNPresultstring": "ResultString"
      }
    },
    {
      "url": "http://webtileapi.azurewebsites.net/api/Ping?urlToPing=http://www.domusdotnet.org",
      "style": "Simple",
      "content": {
        "DDNpingdatetime": "PingDateTime",
        "DDNresultstring": "ResultString"
      }
    }
  ]

Il tipo di entrambe le risorse è “Simple”, il che comunica all’infrastruttura delle Web Tile (gestita dall’app mobile Microsoft Health), che si avrà a che fare con una risposta composta da una struttura JSON e non da una collezione di item, come avviene nel caso del tipo “Feed”.
Nella parte di content definiamo i dati che ci interessa mostrare e, in particolare, XXXpingdatetime e XXXresultstring che conterranno i valori delle proprietà PingDateTime e ResultString della struttura JSON restituita del servizio.
Le due chiamate ai servizi verranno eseguite nell’ordine impostato.
Nella definizione delle pagine troviamo:

"pages": [
    {
      "layout": "MSBand_MetricsWithIcons",
      "condition": "true",
      "iconBindings": [
        {
          "elementId": "11",
          "conditions": [
            {
              "condition": "true",
              "icon": "dotnetpodcasticon"
            }
          ]
        },
        {
          "elementId": "21",
          "conditions": [
            {
              "condition": "true",
              "icon": "domusdotneticon"
            }
          ]
        }
      ],
      "textBindings": [
        {
          "elementId": "12",
          "value": "dotNETpodcast {{DNPresultstring}}"
        },
        {
          "elementId": "22",
          "value": "DomusDotNet {{DDNresultstring}}"
        }
      ]
    },
    {
      "layout": "MSBand_NoScrollingText",
      "condition": "true",
      "textBindings": [
        {
          "elementId": "1",
          "value": "dotNET{podcast}"
        },
        {
          "elementId": "2",
          "value": "{{DNPresultstring}}"
        },
        {
          "elementId": "3",
          "value": "{{DNPpingdatetime}}"
        }
      ]
    },
    {
      "layout": "MSBand_NoScrollingText",
      "condition": "true",
      "textBindings": [
        {
          "elementId": "1",
          "value": "DomusDotNet"
        },
        {
          "elementId": "2",
          "value": "{{DDNresultstring}}"
        },
        {
          "elementId": "3",
          "value": "{{DDNpingdatetime}}"
        }
      ]
    }
  ]

Abbiamo, quindi, tre pagine.
Il layout della prima di queste è di tipo MSBand_MetricsWithIcons:

SNAGHTMLab8921b

che mostrerà il riepilogo dell’ultima invocazione:

image

Nel JSON che definisce il binding degli elementi visuali della pagina possiamo osservare la sezione iconBindings all’interno della quale assegniamo delle icone agli elementi visuali in grado di contenerle.
Le icone in questione sono contenute nella cartella icons del package e definite nella sezione JSON icons:

"icons": {
  "dotnetpodcasticon": "icons/dotnetpodcast.png",
  "domusdotneticon": "icons/domusdotnet.png"
},

Nella parte del binding degli elementi visuali che contengono il testo, invece, assegniamo delle scritte a cui concateniamo uno dei valori prelevati dal servizio.
Le altre due pagine sono uguali tra loro e usano il layout MSBand_NoScrollingText:

SNAGHTMLab98ecb

Le tre righe sono messe in binding, rispettivamente, con una stringa costante (il nome del sito) e con i due valori ottenuti dal servizio, ottenendo, ad esempio:

image

In questo modo, ogni volta che Microsoft Health aggiornerà la Web Tile (l’intervallo in minuti è contenuto nella proprietà refreshIntervalMinutes, come visto nei precedenti post), verrà invocato due volte il servizio ed effettuato il binding dei dati sulle pagine.
Le pagine così create non hanno, al momento, interazione con l’utente.
Il file manifest completo è il seguente:

{
  "manifestVersion": 1,
  "name": "PingBand",
  "description": "Tieni sotto controllo i tuoi siti con PingBand",
  "version": 1,
  "versionString": "1.0",
  "author": "Massimo Bonanni",
  "contactEmail": "massimo.bonanni@tiscali.it",
  "tileIcon": {
    "46": "icons/largeicon.png"
  },
  "badgeIcon": {
    "24": "icons/smallIcon.png"
  },
  "icons": {
    "dotnetpodcasticon": "icons/dotnetpodcast.png",
    "domusdotneticon": "icons/domusdotnet.png"
  },
  "refreshIntervalMinutes": 15,
  "resources": [
    {
      "url": "http://webtileapi.azurewebsites.net/api/Ping?urlToPing=http://www.dotnetpodcast.com",
      "style": "Simple",
      "content": {
        "DNPpingdatetime": "PingDateTime",
        "DNPresultstring": "ResultString"
      }
    },
    {
      "url": "http://webtileapi.azurewebsites.net/api/Ping?urlToPing=http://www.domusdotnet.org",
      "style": "Simple",
      "content": {
        "DDNpingdatetime": "PingDateTime",
        "DDNresultstring": "ResultString"
      }
    }
  ],
  "pages": [
    {
      "layout": "MSBand_MetricsWithIcons",
      "condition": "true",
      "iconBindings": [
        {
          "elementId": "11",
          "conditions": [
            {
              "condition": "true",
              "icon": "dotnetpodcasticon"
            }
          ]
        },
        {
          "elementId": "21",
          "conditions": [
            {
              "condition": "true",
              "icon": "domusdotneticon"
            }
          ]
        }
      ],
      "textBindings": [
        {
          "elementId": "12",
          "value": "dotNETpodcast {{DNPresultstring}}"
        },
        {
          "elementId": "22",
          "value": "DomusDotNet {{DDNresultstring}}"
        }
      ]
    },
    {
      "layout": "MSBand_NoScrollingText",
      "condition": "true",
      "textBindings": [
        {
          "elementId": "1",
          "value": "dotNET{podcast}"
        },
        {
          "elementId": "2",
          "value": "{{DNPresultstring}}"
        },
        {
          "elementId": "3",
          "value": "{{DNPpingdatetime}}"
        }
      ]
    },
    {
      "layout": "MSBand_NoScrollingText",
      "condition": "true",
      "textBindings": [
        {
          "elementId": "1",
          "value": "DomusDotNet"
        },
        {
          "elementId": "2",
          "value": "{{DDNresultstring}}"
        },
        {
          "elementId": "3",
          "value": "{{DDNpingdatetime}}"
        }
      ]
    }
  ]
}

Con questo è tutto per quanto riguarda la mini serie dedicata alla preview delle Web Tile.

mercoledì 29 luglio 2015

Microsoft Band SDK – Web Tile : Feed RSS

In questo post vorrei prendere in esame come sia possibile creare una Web Tile prendendo i dati da un feed RSS.
Abbiamo visto nel precedente post dedicato alle Web Tile quale è la struttura del file manifest.json, in questo post vedremo come configurare la parte relativa alle risorse e alle pagine per poter visualizzare il contenuto di un feed RSS.
Cominciamo con il prendere un feed RSS: nell’esempio riportato utilizzerò il feed di dotNET{podcast} (così faccio anche pubblicita’ occulta al sito  Smile).
Il feed completo si trova al seguente link.
Prima cosa che andiamo a configurare è la sezione resources e, precisamente:

"resources": [
  {
    "url": "http://www.dotnetpodcast.com/feed/RSS",
    "style": "Feed",
    "content": {
      "title": "title",
      "pubdate": "pubDate",
      "itunesduration": "itunes:duration"
    }
  }
],

Osserviamo che:
  • lo style è Feed il che dice all’infrastruttura delle web tile che stiamo recuperando un feed e che quando apriremo la tile sul Band, avremo un numero di pagine, tutte uguali e fino ad un massimo di 8, che conterranno i dati secondo il layout che sceglieremo nella parte delle pages;
  • l’url del feed è nella proprietà url;
  • l’estrazione dei dati che ci interessano è definita nell’oggetto content ed in particolare definiamo tre variabili “title”, “pubdate” e “itunesduration” (i nomi sono quelli che ci fanno più comodo) che contengono, rispettivamente i campi “title”, “pubDate” e “itunes:duration” del tag <item> contenuto nell’XML del feed;
In questo modo, di fatto costruiamo una sorta di DTO che mappa il contenuto del feed in opportune variabili.
Il secondo step consiste nel definire come vogliamo appaiano i dati al’interno della tile che metteremo nella strip del Band.
Per fare ciò, dovremo agire sulla collezione pages del file di manifest.
In questo caso, poichè stiamo trattando un feed, avremo una pagina sola che verrà ripetuta per ogni item presente nel feed (fino ad un massimo di 8).

"pages": [
  {
    "layout": "MSBand_NoScrollingText",
    "condition": "true",
    "textBindings": [
      {
        "elementId": "1",
        "value": "{{title}}"
      },
      {
        "elementId": "2",
        "value": "{{pubdate}}"
      },
      {
        "elementId": "3",
        "value": "durata: {{itunesduration}}"
      }
    ]
  }
]

In questo caso abbiamo scelto il layout MSBand_NoScrolingText impostando opportunamente la proprietà layout.
SNAGHTML407c5aa
La proprietà condition in questa versione delle Web Tile deve essere posta obbligatoriamente a true.
L’oggetto textBindings, infine, contiene l’associazione tra i controlli presenti nel layout e le variabili definite nella sezione resources.
Nel nostro caso specifico abbiamo:
  • nell’elementid 1 (quello che nell’immagine del template è Header)mettiamo il contenuto della variabile title;
  • nell’elementid 2 (Body lines 1) mettiamo il contenuto della variabile pubdate;
  • nell’elementid 3 (Secondary Content) mettiamo la concatenazione tra il testo “durata: “ e il contenuto della variabile itunesduration.
Possiamo osservare che si utilizza la sintassi {{nomevariabile}} per definire il binding.
E’ possibile combinare, in uno degli elementi del layout, più variabili o anche concatenare stringhe e variabili.
Infine, per personalizzare ulteriormente la visualizzazione del feed, possiamo cambiare il tema utilizzato all’interno della tile utilizzando l’oggetto JSON tileTheme:

  "tileTheme": {
      "base": "ffaf00",
      "highlight": "ffaf00",
      "lowlight": "f99a03",
      "secondary": "9e9678",
      "highContrast": "ffa500",
      "muted": "bc8b00"
},

La seguente figura mostra il significato delle singole proprieta’ dell’oggetto tileTheme:

image

Quello che otteniamo, una volta installata la Web Tile attraverso l’applicazione Microsoft Health, e’ mostrato nella seguente figura:

Pagina-del-feed

Il file manifest completo e’ il seguente:

{
    "manifestVersion" : 1,
    "name" : "dotNET{podcast}",
    "description" : "Il feed di dotNET{podcast}, il primo podcast italiano su tecnologie Microsoft.",
    "version" : 1,
    "versionString" : "1.0",
    "author" : "Massimo Bonanni",
    "contactEmail" : "massimo.bonanni@dotnetpodcast.com",
    "organization" : "dotNET{podcast}",
    "tileIcon" : {
        "46" : "icons/largeicon.png"
    },
    "badgeIcon" : {
        "24" : "icons/smallIcon.png"
    },
    "refreshIntervalMinutes" : 15,
    "tileTheme": {
        "base": "ffaf00",
        "highlight": "ffaf00",
        "lowlight": "f99a03",
        "secondary": "9e9678",
        "highContrast": "ffa500",
        "muted": "bc8b00"
  },
  "resources": [
    {
      "url": "http://www.dotnetpodcast.com/feed/RSS",
      "style": "Feed",
      "content": {
        "title": "title",
        "pubdate": "pubDate",
        "itunesduration": "itunes:duration"
      }
    }
  ],
  "pages": [
    {
      "layout": "MSBand_NoScrollingText",
      "condition": "true",
      "textBindings": [
        {
          "elementId": "1",
          "value": "{{title}}"
        },
        {
          "elementId": "2",
          "value": "{{pubdate}}"
        },
        {
          "elementId": "3",
          "value": "durata: {{itunesduration}}"
        }
      ]
    }
  ]
}

Nel prossimo post vedremo come creare una tile che mostri delle pagine i cui contenuti sono recuperati da un nostro servizio REST custom.

Rimanete connessi!!!

lunedì 27 luglio 2015

Microsoft Band SDK : WebTile

Qualche giorno fa è stata rilasciata una nuova versione dell’SDK del Microsoft Band (la 1.3.10702 per la precisione) che ha portato con se, di fatto, solo alcune fix. Contestualmente, però, è stato rilasciato il supporto per le WebTile e le API di Microsoft Health Cloud.
In questo post (e in un paio di altri che seguiranno) prenderemo in esame le WebTile.
Il meccanismo delle Web Tile è in preview, maggiori informazioni, sample e documentazione è disponibile all’indirizzo http://developer.microsoftband.com/WebTile

Cosa sono le WebTile

Le WebTile sono dei file zip la cui estensione è .webtile (detto “Web Tile Package”) e la cui strutura interna è la seguente:
image
Il loro scopo è quello di veicolare informazioni al Band prendendole direttamente da qualsiasi sorgente dati accessibile via web che restituisca dati in formato XML o JSON.
Una volta creata la Web Tile, l’installazione e la gestione della stessa è a carico dell’app Microsoft Health installata nel nostro smartphone e che utiliziamo come bridge per poter scaricare i dati dal Band.
In particolare Microsoft Health registra il file activation protocol sull’estensione .webtile e l’URI activation protocol con il protocollo mshealth-webtile:// il che significa che ci basta aprire un file .webtile o accedere ad un link del tipo mshealth://www.miosito/generatile per ottenere che la stessa Microsoft Health prenda in carico l’installazione della tile all’interno del nostro Band e gestisca il suo ciclo di vita.
La tile così installata comparirà tra le tile di terze parti nell’app Health e sarà compito di Health stessa provvedere ad aggiornare i dati delle pagine in essa contenute.
Nel momento in cui apriamo un link ad una webtile (o apriamo un file che ci è stato inviato), quello che accade è che Microsoft Health viene attivata e ci chiede l’autorizzazione ad installare la nuova tile nel Band (sempre che ci sia ancora spazio nella strip).
SNAGHTML141480
Se accettiamo, la tile viene “installata” nel Band e i dati cominciano a fluire a carico dell’app Microsoft Band.
Possiamo rimuovere la tile agendo nella finestra di gestione delle tile di Health.
SNAGHTML1694f1
Attenzione perchè, in questa versione, non viene eseguito un controllo sull’esistenza della Web Tile all’interno della strip. Il che significa che se installiamo due volte la stessa Web Tile, ci ritroviamo due tile uguali nella strip del Band.

Il file di Manifest

Il file manifest.json è un file in formato JSON che contiene tutte le informazioni necessarie a Microsoft Health per poter generare la tile, le pagine, recuperare i dati ed eseguire il binding dei dati stessi all’interno delle pagine.
Il manifest.json può essere diviso in tre sezioni distinte:
  • metadati della tile (come nome, versione, descrizione, autore e icone della tile);
  • definizione delle sorgenti dati
  • definizione delle pagine e del binding dei dati.
Un esempio di file manifest.json è il seguente:

{
    "manifestVersion" : 1,
    "name" : "dotNET{podcast}",
    "description" : "Il feed di dotNET{podcast}, il primo podcast italiano su tecnologie Microsoft.",
    "version" : 1,
    "versionString" : "1.0",
    "author" : "Massimo Bonanni",
    "contactEmail" : "massimo.bonanni@dotnetpodcast.com",
    "organization" : "dotNET{podcast}",
    "tileIcon" : {
        "46" : "icons/largeicon.png"
    },
    "badgeIcon" : {
        "24" : "icons/smallIcon.png"
    },
    "refreshIntervalMinutes" : 15,
    "resources": [
        {
            "url": "http://www.dotnetpodcast.com/feed/RSS",
            "style": "Feed",
            "content": {
                "title": "title"
            }
        }
    ],
    "pages": [
        {
            "layout": "MSBand_ScrollingText",
            "condition": "true",
            "textBindings": [
                {
                    "elementId": "1",
                    "value": "dotNET{podcast}"
                },
                {
                    "elementId": "2",
                    "value": "{{title}}"
                }
            ]
        }
    ]
}

Nella prima parte troviamo tutti i metadati della tile:
  • manifestVersion : è un numero che indica la versione ad uso e consumo di Microsoft Health grazie alla quale Health riesce a comprendere quale versione del manifest si sta utilizzando. E’ obbligatorio e per la preview deve essere utilizato il valore 1;
  • name : si tratta di una stringa che definisce il nome della tile. E’ il nome che compare all’interno di Microsoft Health nel momento in cui installiamo o nella lista delle tile di terze parti. E’ obbligatorio;
  • description : è una stringa che descrive la tile. Non è obbligatoria;
  • version : è un numero che indica la versione della tile. Non è obbligatoria e non è mostrata all’utente. Se non indicato viene preso il numero 1;
  • versionString : è una stringa che contiene il numero di versione della tile che verrà mostrata all’utente. Non è obbligatoria e, se non presente, viene mostrato il valore presente nel campo version;
  • author : stringa non obbligatoria contenente il nome dell’autore;
  • organization : stringa non obbligatoria contenente il nome dell’azienda;
  • contactEmail : stringa non obbligatoria contenente la mail di contatto utilizzabile dal team di Microsoft Band per fini analitici;
  • tileIcon : oggeto obbligatorio contenente i dati dell’icona da utilizzare nella strip del Band in termini di posizione e grandezza in pixel;
  • badgeIcon: oggetto non obbligatorio contenente i dati dell’icona da utilizzare quando deve essere visualizzato il numero di nuove pagine presenti nell’icona;
  • refreshIntervalMinutes : numero non obbligatorio che indica l’intervallo di aggiornamento (in minuti) della tile. Non sono ammessi valori minori di 15. Se non presente, viene utilizato il valore 30.
Nella sezione dei metadati, possono anche essere presenti i seguenti oggetti JSON che permettono di impostare il tema dell’icona ed eventuali immagini accessorie da utilizzare nel binding dei dati provenienti dalle sorgenti dati all’interno delle pagine della tile.

"tileTheme": {
  "base": "d94c66",
  "highlight": "ea5475",
  "lowlight": "c64763",
  "secondary": "a3919c",
  "highContrast": "bf455f",
  "muted": "993344"
},
"icons": {
  "Icon1": "icons/icon1.png",
  "Icon2": "icons/icon2.png"
},

Se la sezione del tema non viene impostata, la tile prenderà il tema di default del Band.
Per quanto riguarda le icone accessorie, queste vengono trasferite al Band nel momento in cui la tile viene installata, il che significa che sono fisse e non possono essere scaricate, ad esempio, da internet in un secondo tempo. Inoltre sono ammesse fino a 10 icone, comprese le eventuali tileIcon e badgeIcon.

Le sorgenti dati

La sezione resources del file manifest.json contiene le informazioni relative alle risorse web da utilizzare per prelevare i dati.
Possono essere presenti più risorse e queste verranno elaborate nell’ordine in cui sono riportate all’interno del file manifest.json.
Ogni risorsa ha tre proprieta’ che possono essere impostate:
  • url : contiene l’indirizzo della risorsa da utilizzare per prelevare i dati. Può essere, ad esempio, un feed rss o un servizio REST;
  • style : specifica il tipo di risorsa web che si sta utilizzando. Al momento sono ammessi solo i valori “simple” e “feed”. Il primo valore si utilizza quando la risorsa è un generico servizio REST mentre il secondo quando abbiamo a che fare con un feed rss;
  • content : questa sezione definisce come estrarre i dati dalla risorsa. Ogni oggetto presente nella sezione definisce una sorta di variabile che potremo utilizzare nelle pagine per eseguire il binding dei dati ed è formato dal nome della variabile stessa e dal “percorso” in cui ricavare il valore da associare. Nel caso di una risorsa JSON, tale percorso altro non è che una Javascript objecte xpression. Nel caso di XML dobbiamo utilizzare un formato xpath.
La parte di definizione delle risorse verrà analizzata meglio nei prossimi post.

Le pagine della tile

La sezione Pages, infine, contiene le informazioni relative alle pagine che abbiamo intenzione di utilizzare all’interno della nostra tile.
Questa sezione definisce quante pagine utilizzeremo, quale sarà il loro layout e, soprattutto, come andremo amostrare i dati recuperati dalle risorse definite nella sezione resources.
In questa sezione troviamo le seguenti proprietà:
  • layout : imposta il nome del layout della pagina. Sono disponibili 6 possibili layout per le pagine (mostrati in seguito);
  • condition : se presente, in questa versione, deve essere impostato a true. Probabilmente in futuro potrà essere utilizzato per dare una condizione di visibilità alla pagina basata su dati provenienti dalle sorgenti dati;
  • textBindings : definisce l’associazione tra gli elementi testuali della pagina e dei valori costanti o i valori contenuti nelle variabili definite all’interno della sezione resources vista in precedenza;
  • iconBindings : permette di eseguire il binding tra elementi della pagina che possono contenere immagini e le immagini definite nella sezione icons. Ogni elemento all’interno di questa sezione contiene l’id dell’elemento grafico della pagina in cui posizionare l’immagine e degli oggetti conditions. In questa versione, la collezione dei conditions può essere formata da un solo elemento e tale elemento deve avere la proprietà condition impostata a true. Probabilmente in futuro potrà servire per poter visualizzare o meno una immagine in base a delle condizioni recuperate dalle sorgenti dati.

"iconBindings": [
  {
    "elementId": "21",
    "conditions": [
      {
        "condition": "true",
        "icon": "Icon1"
      }
    ]
  }
]

I possibili layout per le pagine sono i seguenti
SNAGHTML5450e6
Nei prossimi post vedremo come costruire le tile per un feed e per un nostro servizio REST.
Restate collegati!!!