Contatti

I contatti consentono al tuo Glassware di ricevere elementi della sequenza temporale che non ha creato. Gli utenti devono condividere esplicitamente un elemento della cronologia con il tuo contatto toccando la voce di menu Condividi di una scheda.

Funzionamento

Una volta creato un contatto di condivisione, le schede della cronologia della condivisione seguono questo flusso generale:

  1. Crea un contatto e definisci i tipi MIME supportati.
  2. Inserisci il contatto nella cronologia dell'utente.
  3. L'utente riceve un elemento della cronologia con la voce di menu Condividi. Il componente aggiuntivo deve consentire esplicitamente agli utenti di condividere i propri elementi con questa voce di menu.
  4. L'utente tocca l'elemento della sequenza temporale, seleziona la voce di menu Condividi e seleziona il tuo contatto.
  5. L'API Mirror crea una copia della scheda della cronologia condivisa, concede al tuo contatto l'accesso alla copia e la inserisce nella cronologia dell'utente. Il tuo Glassware non può accedere all'elemento originale della cronologia.
  6. Se hai attivato l'iscrizione per la condivisione delle notifiche, ricevi un payload contenente le informazioni identificative della scheda della cronologia. Puoi quindi recuperare l'elemento della cronologia con Timeline.get.
  7. Modifichi la scheda della cronologia condivisa e aggiorni la scheda della cronologia esistente con Timeline.update.

Quando utilizzarle

Per impostazione predefinita, i Glassware non possono accedere agli elementi della cronologia che non hanno creato, pertanto i contatti consentono la condivisione dei dati tra Glassware con il consenso dell'utente.

Esistono due modi principali in cui il tuo Glassware può utilizzare i contatti:

  • Consenti agli utenti di condividere gli elementi della cronologia con altri contatti: aggiungi la voce di menu integrata SHARE a una scheda della cronologia. Quando gli utenti toccano la voce di menu Condividi, Glass mostra un elenco di possibili contatti con cui condividere.

  • Consenti agli utenti di condividere elementi della cronologia con il tuo Glassware: crea un contatto che rappresenti il tuo Glassware. Quando gli utenti vogliono condividere una scheda della cronologia, il tuo contatto viene visualizzato come opzione. Puoi anche dichiarare un elenco di tipi MIME accettabili in modo che il tuo contatto venga visualizzato solo per le schede che ti interessano. Per ricevere una notifica quando gli utenti condividono una scheda della cronologia con il tuo contatto, puoi iscriverti alle notifiche della cronologia.

Creare un contatto

Per consentire agli utenti di condividere elementi della cronologia con il tuo Glassware, inserisci un contatto pubblicando una rappresentazione JSON di un contatto nell' endpoint REST di inserimento.

Tutti i contatti devono specificare un id, che identifica il contatto per il Glassware che riceve le notifiche. Devi anche specificare un displayName e almeno un imageUrls, che Glass utilizza per mostrare all'utente i dati di contatto.

HTTP non elaborato

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
}

Iscrizione alle notifiche di condivisione

L'API Mirror ti consente di iscriverti alle notifiche che vengono inviate quando l'utente esegue azioni specifiche su un elemento della cronologia o quando la posizione dell'utente è stata aggiornata. Quando ti abboni a una notifica, fornisci un URL di callback che elabora la notifica.

Una notifica dell'API Mirror viene inviata come richiesta POST all'endpoint a cui è stato eseguito l'abbonamento e contiene un corpo della richiesta JSON.

HTTP non elaborato

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

L'attributo itemId è l'ID dell'elemento della cronologia condivisa, che puoi utilizzare con Timeline.get per ottenere l'elemento della cronologia. L'esempio seguente mostra un tipico elemento della cronologia con una foto allegata:

{
  "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>"
          ]
      }
  ]
}

Se non si è verificato alcun errore, il servizio deve rispondere all'API con un codice di stato HTTP 200 OK. Se il servizio risponde con un codice di errore, l'API Mirror potrebbe tentare di inviare nuovamente la notifica al servizio.

Ricezione della trascrizione vocale

Gli utenti possono condividere il discorso trascritto con il contatto tramite il menu vocale principale. Al momento, il tuo contatto può utilizzare due comandi vocali:

  • "Scrivi una nota"
  • "pubblicare un aggiornamento"

Ad esempio, un utente può comunicarci il compleanno imminente di Chipotle con la frase: "Ok Glass… pubblica un aggiornamento su… Cat Stream... Domani è il compleanno di Chipotle."

Per utilizzare i comandi vocali:

  1. Specifica la proprietà acceptCommands con il valore type appropriato:

    {
  ...

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

  2. Iscriviti alle notifiche della cronologia per ricevere una notifica quando è disponibile la trascrizione del discorso. Il tuo Glassware riceve una notifica quando si verifica quanto segue:

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

  3. Utilizza itemId per recuperare l'elemento della sequenza temporale:

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

  4. Se più Glassware registrano un contatto con lo stesso comando vocale, Glass mostra un menu di secondo livello che mostra il displayName di ogni contatto. Gli utenti possono quindi pronunciare il nome del contatto che preferiscono. Se il displayName del tuo contatto contiene caratteri impronunciabili o non è fonetico, utilizza la proprietà speakableName per dichiarare la pronuncia prevista del tuo contatto di condivisione.

Didascalie per le foto condivise

Gli utenti hanno la possibilità di condividere foto con il tuo Glassware con una didascalia che inseriscono con i comandi vocali. Il flusso utente generale è:

  1. L'utente tocca un elemento della cronologia contenente una foto, seleziona la voce di menu Condividi e seleziona il tuo contatto.
  2. L'utente tocca di nuovo entro un breve periodo di tempo per aggiungere una didascalia alla foto.
  3. L'utente pronuncia una didascalia.
  4. L'elemento della cronologia viene condiviso con il tuo Glassware come descritto in precedenza nella sezione Come funzionano. Inoltre, la proprietà text dell'elemento della cronologia è impostata con la didascalia trascritta dell'utente.