Kontakty

Kontakty umożliwiają Twojemu oprogramowaniu Glassware otrzymywanie elementów osi czasu, których nie utworzyło. Użytkownicy muszą wyraźnie udostępnić element osi czasu Twojemu kontaktowi, klikając element menu Udostępnij na karcie.

Jak działają

Gdy utworzysz kontakt do udostępniania, udostępnianie kart osi czasu będzie przebiegać w ten sposób:

1. Utwórz kontakt i określ typy MIME, które obsługuje.
2. Wstaw kontakt na osi czasu użytkownika.
3. Użytkownik otrzymuje element osi czasu z elementem menu Udostępnij. Oprogramowanie Glassware musi wyraźnie zezwalać użytkownikom na udostępnianie elementów za pomocą tego elementu menu.
4. Użytkownik klika element osi czasu, wybiera element menu Udostępnij i wybiera Twój kontakt.
5. Mirror API tworzy kopię udostępnionej karty osi czasu, przyznaje Twojemu kontaktowi dostęp do tej kopii i wstawia ją na osi czasu użytkownika. Twoje oprogramowanie Glassware nie ma dostępu do oryginalnego elementu osi czasu.
6. Jeśli subskrybujesz powiadomienia o udostępnianiu, otrzymasz ładunek zawierający informacje umożliwiające identyfikację karty osi czasu. Następnie możesz pobrać element osi czasu za pomocą Timeline.get.
7. Zmodyfikuj udostępnioną kartę osi czasu i zaktualizuj istniejącą kartę osi czasu za pomocą Timeline.update.

Kiedy ich używać

Domyślnie oprogramowanie Glassware nie ma dostępu do elementów osi czasu, których nie utworzyło, więc kontakty umożliwiają udostępnianie danych między oprogramowaniem Glassware za zgodą użytkownika.

Oprogramowanie Glassware może korzystać z kontaktów na 2 główne sposoby:

• Zezwalaj użytkownikom na udostępnianie elementów osi czasu innym kontaktom: dodaj SHARE wbudowany element menu do karty osi czasu. Gdy użytkownicy klikną element menu udostępniania, Glass wyświetli listę możliwych kontaktów, którym można udostępnić element.

• Zezwalaj użytkownikom na udostępnianie elementów osi czasu Twojemu oprogramowaniu Glassware: utwórz kontakt reprezentujący Twoje oprogramowanie Glassware. Gdy użytkownicy będą chcieli udostępnić kartę osi czasu, Twój kontakt pojawi się jako opcja. Możesz też zadeklarować listę akceptowanych typów MIME , aby Twój kontakt pojawiał się tylko w przypadku kart, które Cię interesują. Aby otrzymywać powiadomienia, gdy użytkownicy udostępnią kartę osi czasu Twojemu kontaktowi, możesz zasubskrybować powiadomienia o osi czasu.

Tworzenie kontaktu

Aby zezwolić użytkownikom na udostępnianie elementów osi czasu Twojemu oprogramowaniu Glassware, wstaw kontakt, wysyłając reprezentację JSON kontaktu do punktu końcowego REST insert.

Wszystkie kontakty muszą mieć określony parametr id, który identyfikuje kontakt w oprogramowaniu Glassware otrzymującym powiadomienia. Musisz też określić parametr displayName i co najmniej 1 parametr imageUrls, które Glass wykorzystuje do wyświetlania użytkownikowi informacji o kontakcie.

Uwaga:aby uzyskać najlepsze wyniki, użyj ikony PNG o wymiarach 640 × 360 pikseli z przezroczystym tłem w przypadku parametru imageUrls.

Nieprzetworzony protokół 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
}

Subskrybowanie powiadomień o udostępnianiu

Mirror API umożliwia subskrybowanie powiadomień wysyłanych, gdy użytkownik wykonuje określone działania na elemencie osi czasu lub gdy zaktualizowano lokalizację użytkownika. Gdy subskrybujesz powiadomienie, podajesz adres URL wywołania zwrotnego, który przetwarza powiadomienie.

Uwaga: w środowisku produkcyjnym adres URL wywołania zwrotnego musi obsługiwać protokół SSL. Na potrzeby programowania udostępniamy serwer proxy subskrypcji, który może przekazywać powiadomienia do serwera programistycznego bez protokołu SSL.

Powiadomienie z Mirror API jest wysyłane jako żądanie POST do zasubskrybowanego punktu końcowego zawierającego treść żądania JSON.

Nieprzetworzony protokół HTTP

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

Atrybut itemId to ID udostępnionego elementu osi czasu, którego możesz użyć z Timeline.get, aby uzyskać element osi czasu. Poniższy przykład przedstawia typowy element osi czasu z załącznikiem w postaci zdjęcia:

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

Jeśli nie wystąpił żaden błąd, usługa musi odpowiedzieć interfejsowi API kodem stanu HTTP 200 OK. Jeśli usługa odpowie kodem błędu, Mirror API może spróbować ponownie wysłać powiadomienie do Twojej usługi.

Uwaga: połączenie przekroczy limit czasu po 10 sekundach. Jeśli wymagany jest długi proces, odpowiedz od razu i wykonaj proces w innym wątku.

Otrzymywanie transkrypcji mowy

Użytkownicy mogą udostępniać transkrypcję mowy Twojemu kontaktowi za pomocą głównego menu głosowego. Obecnie dostępne są 2 polecenia głosowe, których może używać Twój kontakt:

• Zanotuj.
• „Opublikuj aktualizację”.

Użytkownik może na przykład poinformować nas o zbliżających się urodzinach Chipotle, mówiąc: „Ok Glass... opublikuj aktualizację... Cat Stream... Jutro są urodziny Chipotle!”.

Aby używać poleceń głosowych:

1. Określ właściwość acceptCommands z odpowiednim parametrem type:

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

2. Zasubskrybuj powiadomienia o osi czasu, aby otrzymywać powiadomienia o dostępności transkrypcji mowy. Gdy to nastąpi, Twoje oprogramowanie Glassware otrzyma powiadomienie:

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

3. Użyj parametru itemId, aby pobrać element osi czasu:

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

   Uwaga: gdy otrzymasz udostępniony element osi czasu, zaktualizuj istniejącą kartę osi czasu za pomocą Timeline.update zamiast tworzyć nową, jeśli modyfikujesz element.

4. Jeśli więcej niż 1 oprogramowanie Glassware zarejestruje kontakt z tym samym poleceniem głosowym, Glass wyświetli menu drugiego poziomu z parametrem displayName każdego kontaktu. Użytkownicy mogą wtedy wypowiedzieć nazwę wybranego kontaktu. Jeśli parametr displayName Twojego kontaktu zawiera znaki, których nie można wymówić, lub nie jest fonetyczny, użyj właściwości speakableName, aby zadeklarować oczekiwaną wymowę Twojego kontaktu do udostępniania.

Podpisy udostępnionych zdjęć

Użytkownicy mogą udostępniać zdjęcia Twojemu oprogramowaniu Glassware wraz z podpisem, który wprowadzają za pomocą mowy. Ogólny proces użytkownika wygląda tak:

1. Użytkownik klika element osi czasu zawierający zdjęcie, wybiera element menu Udostępnij i wybiera Twój kontakt.
2. Użytkownik klika ponownie w krótkim czasie, aby dodać podpis do zdjęcia.
3. Użytkownik wypowiada podpis.
4. Element osi czasu jest udostępniany Twojemu oprogramowaniu Glassware w sposób opisany wcześniej w sekcji Jak działają. Dodatkowo właściwość text elementu osi czasu jest ustawiana na transkrybowany podpis użytkownika.