Kartu Statis

Anda dapat menyisipkan, memperbarui, membaca, dan menghapus kartu statis menggunakan REST API sederhana. Selain itu, Anda dapat melampirkan objek ke kartu statis, seperti lokasi atau media.

Cara kerjanya

Kartu statis berada di sebelah kanan jam Glass dan secara default menampilkan informasi yang relevan bagi pengguna pada saat pengiriman. Namun, metode ini tidak memerlukan fokus langsung seperti kartu live dan pengguna dapat memilih untuk membaca atau menindaklanjuti kartu tersebut di waktu senggang.

Saat Glassware menyisipkan kartu statis ke linimasa, Glass dapat memutar suara notifikasi untuk memberi tahu pengguna. Semua kartu statis sebelumnya juga akan bergeser ke kanan dan menghilang dari linimasa setelah 7 hari atau saat 200 kartu lebih baru.

Kapan menggunakannya

Kartu statis sangat bagus untuk mengirimkan notifikasi berkala kepada pengguna saat hal penting terjadi. Misalnya, layanan pengiriman berita yang mengirim berita utama saat itu terjadi. Kartu statis Mirror API juga dapat memulai kartu live atau immers melalui item menu OPEN_URI. Hal ini memungkinkan Anda membuat interaksi campuran yang menggunakan kartu statis sebagai notifikasi dan kartu live atau imersif untuk pengalaman yang lebih interaktif.

Catatan: Karena kartu linimasa merupakan pusat pengalaman pengguna, pahami praktik terbaik sebelum membuat item linimasa.

Untuk mengetahui daftar lengkap operasi yang dapat dilakukan untuk item linimasa, lihat dokumentasi referensi.

Memasukkan kartu statis

Untuk menyisipkan kartu statis (item linimasa), POSTING representasi JSON item linimasa ke endpoint REST.

Catatan: Item linimasa bertahan selama tujuh hari di Glass pengguna dan dihapus dari server Google jika tidak diperbarui selama sepuluh hari.

Sebagian besar kolom dalam item linimasa bersifat opsional. Dalam bentuk yang paling sederhana, item linimasa hanya berisi pesan teks singkat, seperti dalam contoh ini:

HTTP Mentah

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

{ "text": "Hello world" }

Java

TimelineItem timelineItem = new TimelineItem();
timelineItem.setText("Hello world");
service.timeline().insert(timelineItem).execute();

Python

timeline_item = {'text': 'Hello world'}
service.timeline().insert(body=timeline_item).execute()

Setelah berhasil, Anda akan menerima kode respons 201 Created dengan salinan lengkap item yang dibuat. Untuk contoh sebelumnya, respons yang berhasil mungkin terlihat seperti ini:

HTTP Mentah

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

Item yang disisipkan yang akan muncul di linimasa pengguna akan terlihat seperti ini:

Menyisipkan item linimasa dengan lampiran

Sebuah gambar bernilai ribuan kata, yang jauh lebih banyak daripada yang dapat Anda masukkan ke dalam item linimasa. Untuk itu, Anda juga dapat melampirkan gambar dan video ke item linimasa. Berikut adalah contoh cara menyisipkan item linimasa dengan lampiran foto:

HTTP Mentah

POST /upload/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--

Java

TimelineItem timelineItem = new TimelineItem();
timelineItem.setText("Hello world");
InputStreamContent mediaContent = new InputStreamContent(contentType, attachment);
service.timeline().insert(timelineItem, mediaContent).execute();

Python

timeline_item = {'text': 'Hello world'}
media_body = MediaIoBaseUpload(
    io.BytesIO(attachment), mimetype=content_type, resumable=True)
service.timeline().insert(body=timeline_item, media_body=media_body).execute()

Item linimasa dengan gambar terlampir terlihat seperti ini di Glass:

Catatan: Pada level rendah, lampiran diupload menggunakan HTTP Multipart. Library klien Google API memudahkan hal ini menggunakan upload media.

Melampirkan video

Jika Anda melampirkan file video ke item linimasa, sebaiknya lakukan streaming video, bukan mengupload seluruh payload sekaligus. Google Mirror API mendukung streaming dengan live streaming HTTP, download progresif, dan protokol streaming real-time (RTSP). RTSP sering diblokir oleh firewall, jadi gunakan opsi lainnya jika memungkinkan.

Untuk melakukan streaming video, gunakan item menu bawaan PLAY_VIDEO dan tentukan URL video menjadi payload item menu. Lihat Menambahkan item menu bawaan dan format media yang didukung untuk informasi selengkapnya.

Catatan: Melampirkan URL video streaming dengan content-type video/vnd.google-glass.stream-url tidak digunakan lagi. Gunakan item menu bawaan PLAY_VIDEO sebagai gantinya.

Penomoran halaman

Anda dapat memberi nomor item linimasa yang tidak muat dalam satu kartu linimasa, tetapi seharusnya dikaitkan dengan kartu yang sama. Semua item yang dipaginasi memiliki timeline.id yang sama, sehingga memiliki kumpulan item menu yang sama. Saat pengguna mengetuk item linimasa yang diberi nomor halaman, item menu Baca selengkapnya akan muncul.

Glass secara otomatis memberi nomor halaman pada item linimasa yang menampilkan text. Agar Glass membagi halaman secara otomatis html, gunakan tag article dengan properti class-nya yang ditetapkan ke auto-paginate seperti dalam contoh berikut:

<article class="auto-paginate">
 <h3>Very long list</h3>
 <ul>
   <li>First item</li>
   <li>Second item</li>
   <li>Third item</li>
   <li>Fourth item</li>
   <li>Fifth item</li>
   <li>Sixth item</li>
   <li>...</li>
 </ul>
<article>

Catatan: Tag section saat ini tidak didukung saat menggunakan class auto-paginate.

Untuk melakukan penomoran halaman secara manual, gunakan tag article untuk konten yang ingin Anda tampilkan di setiap kartu. Glass menampilkan konten setiap tag article dalam kartu sub-linimasa terpisah. Misalnya, Anda dapat membuat item linimasa yang dipaginasi dengan HTML berikut:

<article>
 <section>
   <p>First page</p>
 </section>
</article>

<article>
 <section>
   <p>Second page</p>
 </section>
</article>

<article>
 <section>
   <p>Third page</p>
 </section>
</article>

Secara default, kartu pertama item linimasa yang diberi nomor halaman ditampilkan sebagai kartu sampul dan ditampilkan lagi saat pengguna memilih item menu Baca selengkapnya. Agar kartu pertama tidak muncul lagi setelah mengetuk Baca selengkapnya, Anda dapat menentukan class CSS cover-only untuk tag <article> pertama:

<article class="cover-only">
...

Class cover-only juga mendukung item linimasa yang dipaginasi otomatis:

<article class="auto-paginate cover-only">
...

Pemaketan

Dengan pengelompokan, Anda dapat mengelompokkan item yang terkait, tetapi yang berbeda, seperti untuk setiap pesan dalam rangkaian email. Paket memiliki kartu sampul utama yang diketuk pengguna untuk menampilkan sub-linimasa yang berisi kartu lain dalam paket. Paket dibedakan dari kartu linimasa normal dengan lipatan sudut di sudut kanan atas kartu sampul paket.

Untuk memaketkan item linimasa, buat item dengan nilai yang sama untuk bundleId. Item yang terakhir ditambahkan adalah kartu sampul paket.

Catatan: Untuk menetapkan item linimasa tertentu sebagai kartu sampul paket, tetapkan properti isBundleCover ke true.

Gambar berikut menampilkan kartu sampul paket dengan lipatan sudut di sudut kanan atas dan dua kartu paket di bawahnya.

Membaca item linimasa

Layanan Anda dapat mengakses semua item linimasa yang dibuatnya, dan semua item linimasa yang dibagikan dengannya. Berikut cara mencantumkan item linimasa yang terlihat oleh layanan Anda.

HTTP Mentah

GET /mirror/v1/timeline HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer {auth token}

Java

TimelineItem timelineItem = new TimelineItem();
service.timeline().list().execute();

Python

service.timeline().list().execute()

Anda dapat menggunakan operasi REST lain untuk mendapatkan, memperbarui, dan menghapus item linimasa.

Mengakses lampiran

Anda dapat mengakses lampiran ke item linimasa melalui properti array bernama attachments. Kemudian, Anda dapat memperoleh data biner lampiran melalui properti contentUrl lampiran atau dengan endpoint lampiran.

Catatan: Konten lampiran dilindungi oleh OAuth 2.0, seperti panggilan lain ke endpoint API. Library klien Google API menyediakan akses ke konten biner lampiran menggunakan fitur download media.

HTTP Mentah

GET /mirror/v1/timeline/{itemId}/attachments/{attachmentId} HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer {auth token}

Java

TimelineItem item = service.timeline().get(itemId).execute();
String attachmentId = item.getAttachments().get(0).getId();
service.attachments().get(itemId, attachmentId).executeAsInputStream();

Membuat item menu

Item menu memungkinkan pengguna meminta tindakan yang terkait dengan kartu linimasa, dan tersedia dalam dua jenis: item menu bawaan dan item menu kustom.

Item menu bawaan memberikan akses ke fungsi khusus yang disediakan oleh Glass, seperti membaca kartu linimasa, menavigasi ke lokasi, berbagi gambar, atau membalas pesan:

Item menu kustom memungkinkan aplikasi mengekspos perilaku spesifik untuk Glassware, dan Anda juga dapat menyediakan ikon item menu agar sesuai dengan branding.

Menambahkan item menu bawaan

Anda dapat menambahkan item menu bawaan ke item linimasa dengan mengisi menuItems array saat Anda menyisipkannya. Untuk menggunakan item menu bawaan, Anda hanya perlu mengisi action dari setiap menuItem.

Catatan: Saat menggunakan item menu bawaan REPLY atau REPLY_ALL, jangan haruskan pengguna untuk mengucapkan kumpulan opsi terbatas, seperti kemungkinan gerakan dalam game atau perintah untuk layanan. Item menu ini dimaksudkan untuk menangkap input suara format bebas.

HTTP Mentah

HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303

{
  "text": "Hello world",
  "menuItems": [
    {
      "action": "REPLY"
    }
  ]
}

Catatan: Dokumentasi referensi berisi deskripsi mendetail tentang tindakan bawaan yang tersedia.

Menentukan item menu kustom

Jika item menu bawaan tidak berfungsi, Anda dapat membuat item menu kustom dengan tindakan Anda sendiri dengan melakukan hal berikut saat menyisipkan atau memperbarui item linimasa:

• Tentukan CUSTOM untuk menuItem.action.
• Tentukan menuItem.id. Saat pengguna mengetuk item menu kustom, Glassware akan menerima notifikasi yang berisi menuItem.id yang terisi. Ini memungkinkan Anda menentukan sumber notifikasi.
• Tentukan menuItem.values untuk menambahkan iconUrl dan displayName yang muncul di Glass. Arahkan kursor ke gambar PNG 50 x 50 yang berwarna putih dengan latar belakang transparan untuk iconUrl.

• Tentukan displayTime. Jika Anda tidak menentukan displayTime, item linimasa akan berpindah ke bagian depan linimasa setiap kali pengguna mengetuk item menu kustom.

HTTP Mentah

HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303

{
  "text": "Hello world",
  "displayTime": "2013-08-08T22:47:31-07:00",
  "menuItems": [
    {
      "action": "CUSTOM",
      "id": "complete"
      "values": [{
        "displayName": "Complete",
        "iconUrl": "http://example.com/icons/complete.png"
      }]
    }
  ]
}

Mengizinkan pengguna menyematkan kartu linimasa Anda

Anda dapat membuat item menu yang memungkinkan pengguna menyematkan kartu linimasa, yang menampilkan kartu linimasa secara permanen di sebelah kiri kartu jam utama. Pengguna juga dapat melepaskan kartu, dengan menggunakan item menu yang sama.

Item menu penyematan adalah item menu bawaan, sehingga Anda hanya perlu menyediakan TOGGLE_PINNED action untuk menuItem.

HTTP Mentah

HTTP/1.1 201 Created
Date: Tue, 25 Sep 2012 23:30:11 GMT
Content-Type: application/json
Content-Length: 303

{
  "text": "You can pin or unpin this card.",
 "menuItems": [
    {
      "action": "TOGGLE_PINNED"
    }
  ...
 ]
}

Subscription

Dengan Mirror API, Anda dapat berlangganan notifikasi yang dikirim saat pengguna mengambil tindakan tertentu pada Item Linimasa atau saat lokasi pengguna telah diperbarui. Saat berlangganan notifikasi, Anda memberikan URL callback yang memproses notifikasi tersebut.

Catatan: Dalam produksi, URL callback Anda harus mendukung SSL. Untuk tujuan pengembangan, kami menyediakan server proxy langganan yang dapat meneruskan notifikasi ke server pengembangan non-SSL Anda.

Menerima notifikasi

Notifikasi dari Mirror API dikirim sebagai permintaan POST ke endpoint langganan yang berisi isi permintaan JSON.

HTTP Mentah

{
  "collection": "timeline",
  "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "operation": "UPDATE",
  "userToken": "harold_penguin",
  "verifyToken": "random_hash_to_verify_referer",
  "userActions": [
    {
      "type": "<TYPE>",
      "payload": "<PAYLOAD>"
    }
  ]
}

Java

import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.mirror.model.Notification;

import java.io.IOException;
import java.io.InputStream;
// ...

public class MyClass {
  // ...

  /**
    * Parse a request body into a Notification object.
    *
    * @param requestBody The notification payload sent by the Mirror API.
    * @return Parsed notification payload if successful, {@code null} otherwise.
    */
  static Notification parseNotification(InputStream requestBody) {
    try {
      JsonFactory jsonFactory = new JacksonFactory();

      return jsonFactory.fromInputStream(requetBody, Notification.class);
    } catch (IOException e) {
      System.out.println("An error occurred: " + e);
      return null;
    }
  }

  // ...
}

Python

import json

def parse_notification(request_body):
  """Parse a request body into a notification dict.

  Params:
    request_body: The notification payload sent by the Mirror API as a string.
  Returns:
    Dict representing the notification payload.
  """
  return json.load(request_body)

Layanan Anda harus merespons API dengan kode status HTTP 200 OK jika tidak terjadi error. Jika layanan Anda merespons dengan kode error, Mirror API mungkin akan mencoba mengirim ulang notifikasi ke layanan Anda.

Catatan: Waktu sambungan akan habis setelah 10 detik. Jika proses yang panjang diperlukan, segera respons dan lakukan proses tersebut di thread lain.

Jenis notifikasi

Mirror API mengirim payload notifikasi yang berbeda untuk peristiwa yang berbeda.

Balas

Pengguna telah membalas item linimasa Anda menggunakan item menu REPLY bawaan:

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

Atribut itemId disetel ke ID item yang berisi:

• Atribut inReplyTo yang ditetapkan ke ID item linimasa yang dibalas.
• Atribut text ditetapkan ke transkripsi teks.
• Atribut recipients yang disetel ke creator item linimasa yang dibalasnya, jika ada.

Contoh:

{
  "kind": "glass#timelineItem",
  "id": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "inReplyTo": "3236e5b0-b282-4e00-9d7b-6b80e2f47f3d",
  "text": "This is a text reply",
  "recipients": [
    {
      "id": "CREATOR_ID",
      "displayName": "CREATOR_DISPLAY_NAME",
      "imageUrls": [
        "CREATOR_IMAGE_URL"
      ]
    }
  ]
}

Hapus

Pengguna telah menghapus item linimasa:

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

Atribut itemId disetel ke ID item yang dihapus. Item tidak lagi berisi metadata selain ID-nya dan properti isDeleted.

Catatan: Jika pengguna menghapus item dari linimasa, sebaiknya Anda juga menghapus konten ini dari sistem.

Item menu kustom dipilih

Pengguna telah memilih item menu kustom yang ditetapkan oleh layanan Anda:

{
  "collection": "timeline",
  "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg",
  "operation": "UPDATE",
  "userToken": "harold_penguin",
  "userActions": [
    {
      "type": "CUSTOM",
      "payload": "PING"
    }
  ]
}

Atribut itemId disetel ke ID item menu yang dipilih pengguna.

Array userActions berisi daftar tindakan kustom yang dilakukan pengguna pada item ini. Layanan Anda harus menangani tindakan tersebut sebagaimana mestinya.

Pembaruan lokasi

Lokasi baru tersedia untuk pengguna saat ini:

{
  "collection": "locations",
  "itemId": "latest",
  "operation": "UPDATE",
  "userToken": "harold_penguin",
  "verifyToken": "random_hash_to_verify_referer"
}

Saat Glassware menerima pembaruan lokasi, kirim permintaan ke endpoint glass.locations.get untuk mengambil lokasi terbaru yang diketahui. Glassware akan menerima pembaruan lokasi setiap sepuluh menit.

Catatan: Pengambilan informasi lokasi memerlukan cakupan https://www.googleapis.com/auth/glass.location.

Perintah suara

Pengguna Anda telah mengaktifkan perintah suara, misalnya: "Ok Glass, catat, Cat Stream, ulang tahun Chipotle adalah besok". Notifikasi berikut dikirim ke Glassware:

{
  "collection": "timeline",
  "operation": "INSERT",
  "userToken": "chipotle's_owner",
  "verifyToken": "mew mew mew",
  "itemId": "<ITEM_ID>",
  "userActions": [
    {“type”: "LAUNCH"}
  ]
}

Notifikasi ini berbeda dari notifikasi lain berdasarkan nilai LAUNCH di properti userActions.

Selanjutnya, Anda dapat menggunakan nilai di itemId untuk mengambil item linimasa:

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

Properti recipients berisi id kontak yang mewakili perintah suara yang digunakan.