การ์ดคงที่

คุณแทรก อัปเดต อ่าน และลบบัตรแบบคงที่ได้โดยใช้ REST API แบบง่าย นอกจากนี้ คุณยังแนบออบเจ็กต์กับการ์ดแบบคงที่ เช่น ตําแหน่งหรือสื่อได้

วิธีการทำงาน

การ์ดคงที่จะอยู่ทางด้านขวาของนาฬิกา Glass โดยค่าเริ่มต้นและแสดงข้อมูลที่เกี่ยวข้องกับผู้ใช้ ณ เวลาที่นําส่ง แต่ไม่จําเป็นต้องดําเนินการโดยทันที อย่างเช่นการ์ดสด และผู้ใช้จะอ่านหรือดําเนินการกับการ์ดได้ตามสะดวก

เมื่อ Glassware ใส่การ์ดแบบคงที่ลงในไทม์ไลน์ Glass อาจเล่นเสียงการแจ้งเตือนเพื่อแจ้งเตือนผู้ใช้ การ์ดคงที่ก่อนหน้านี้ทั้งหมดจะเปลี่ยนเป็นทางด้านขวา และจะหายไปจากไทม์ไลน์หลังจากผ่านไป 7 วันหรือเมื่อการ์ด 200 ใบที่ใหม่กว่านั้น

ใช้เมื่อใด

การ์ดแบบคงที่เหมาะอย่างยิ่งสําหรับการแสดงการแจ้งเตือนเป็นระยะๆ แก่ผู้ใช้เมื่อมีเหตุการณ์สําคัญเกิดขึ้น เช่น บริการส่งข่าวที่ส่งเรื่องราวข่าวเด่นทันเหตุการณ์ มิเรอร์การ์ด API มิเรอร์ ยังสามารถเริ่มการ์ดสด หรือดื่มด่ํากับรายการในเมนู OPEN_URI ได้ วิธีนี้จะช่วยให้คุณสร้างการโต้ตอบแบบผสมผสานที่ใช้การ์ดแบบคงที่เป็นการแจ้งเตือนและการ์ดแบบสดหรือดื่มด่ํากับประสบการณ์แบบอินเทอร์แอกทีฟมากขึ้น

ดูรายการการดําเนินการที่เป็นไปได้ทั้งหมดสําหรับรายการไทม์ไลน์ได้ที่เอกสารอ้างอิง

การใส่การ์ดคงที่

หากต้องการแทรกการ์ดแบบคงที่ (รายการไทม์ไลน์) ให้โพสต์การนําเสนอ JSON ของรายการไทม์ไลน์ไปยังปลายทาง REST

ช่องส่วนใหญ่ในรายการไทม์ไลน์เป็นตัวเลือกที่ไม่บังคับ ในรูปแบบที่เรียบง่ายที่สุด รายการไทม์ไลน์จะมีเพียงข้อความสั้นๆ ดังตัวอย่างต่อไปนี้

HTTP ไฟล์ข้อมูล

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()

เมื่อดําเนินการสําเร็จ คุณจะได้รับรหัสตอบกลับ 201 Created พร้อมสําเนาฉบับเต็มของรายการที่สร้าง สําหรับตัวอย่างก่อนหน้านี้ การตอบกลับที่สําเร็จอาจมีลักษณะเช่นนี้

HTTP ไฟล์ข้อมูล

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

รายการที่แทรกซึ่งจะปรากฏในไทม์ไลน์ของผู้ใช้จะมีลักษณะดังนี้

การแทรกรายการไทม์ไลน์ที่มีไฟล์แนบ

รูปภาพหนึ่งภาพแทนคํานับพัน ในกรณีนี้ คุณยังแนบรูปภาพและวิดีโอไว้ในรายการไทม์ไลน์ได้ด้วย ตัวอย่างวิธีแทรกรายการในไทม์ไลน์ที่มีไฟล์แนบเป็นรูปภาพมีดังนี้

HTTP ไฟล์ข้อมูล

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()

รายการไทม์ไลน์ที่มีรูปภาพที่แนบมามีลักษณะดังนี้ใน Glass

การแนบวิดีโอ

หากคุณแนบไฟล์วิดีโอไปยังรายการในไทม์ไลน์ เราขอแนะนําให้สตรีมวิดีโอแทนเพย์โหลดทั้งหมดพร้อมกัน Google Mirror API รองรับสตรีมมิงด้วยสตรีมมิงแบบสด HTTP, การดาวน์โหลดแบบโปรเกรสซีฟ และโปรโตคอลสตรีมมิงแบบเรียลไทม์ (RTSP) RTSP มักจะถูกบล็อกโดยไฟร์วอลล์ ดังนั้นโปรดใช้ตัวเลือกอื่นๆ เมื่อเป็นไปได้

หากต้องการสตรีมวิดีโอ ให้ใช้รายการเมนู PLAY_VIDEO ในตัวและระบุ URL ของวิดีโอเป็นรายการเมนู payload ดูข้อมูลเพิ่มเติมที่การเพิ่มรายการเมนูในตัวและรูปแบบสื่อที่รองรับ

การใส่เลขหน้า

คุณสามารถใส่เลขหน้าในไทม์ไลน์ที่ไม่ตรงกับการ์ดไทม์ไลน์การ์ดเดียวได้ แต่ควรเชื่อมโยงกับการ์ดเดียวกัน รายการที่ใส่เลขหน้าจะใช้ timeline.id เดียวกันและมีชุดเมนูเดียวกัน เมื่อผู้ใช้แตะรายการไทม์ไลน์ที่ใส่เลขหน้า รายการในเมนูอ่านเพิ่มเติมจะปรากฏขึ้น

Glass ใส่เลขหน้าในรายการไทม์ไลน์ที่แสดง text โดยอัตโนมัติ หากต้องการให้ Glass ใส่เลขหน้า html โดยอัตโนมัติ ให้ใช้แท็ก article ที่มีการตั้งค่าพร็อพเพอร์ตี้ของชั้นเรียนเป็น auto-paginate เช่นในตัวอย่างต่อไปนี้

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

หากต้องการใส่เลขหน้าด้วยตนเอง ให้ใช้แท็ก article สําหรับเนื้อหาที่คุณต้องการแสดงในแต่ละการ์ด Glass แสดงเนื้อหาของแท็ก article แต่ละรายการในการ์ดไทม์ไลน์ย่อยแยกกัน ตัวอย่างเช่น คุณสามารถสร้างรายการไทม์ไลน์ที่ใส่เลขหน้าด้วย HTML ต่อไปนี้

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

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

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

โดยค่าเริ่มต้น การ์ดรายการแรกของรายการที่ใส่เลขหน้าจะแสดงเป็นการ์ดหน้าปก และจะแสดงอีกครั้งเมื่อผู้ใช้เลือกรายการเมนูอ่านเพิ่มเติม หากต้องการป้องกันไม่ให้การ์ดใบแรกปรากฏขึ้นอีกครั้งหลังจากที่แตะอ่านเพิ่มเติม คุณสามารถระบุคลาส CSS ของ cover-only สําหรับแท็ก <article> รายการแรกได้

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

คลาส cover-only รองรับรายการไทม์ไลน์ที่ใส่เลขหน้าโดยอัตโนมัติด้วย ดังนี้

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

การรวมกลุ่มอีเมล

การจัดแพ็กเกจช่วยให้คุณจัดกลุ่มรายการที่เกี่ยวข้องแต่ไม่ซ้ํากันเข้าด้วยกันได้ เช่น สําหรับข้อความแต่ละรายการในชุดข้อความอีเมล แพ็กเกจจะมีการ์ดหน้าปกหลักที่ผู้ใช้แตะเพื่อแสดงไทม์ไลน์ย่อยที่มีการ์ดอื่นๆ ในแพ็กเกจนั้น แพ็กเกจจะแยกออกจากการ์ดไทม์ไลน์แบบปกติ โดยพับมุมที่มุมขวาบนของการ์ดหน้าปก

หากต้องการจัดกลุ่มรายการไทม์ไลน์ ให้สร้างโดยใช้ค่าเดียวกันสําหรับ bundleId รายการที่เพิ่มล่าสุดคือการ์ดหน้าปกของแพ็กเกจ

รูปภาพต่อไปนี้แสดงการ์ดปกที่มีมุมพับที่มุมบนขวา และการ์ด 2 ใบที่แสดงอยู่ด้านล่าง

การอ่านรายการไทม์ไลน์

บริการของคุณจะเข้าถึงรายการไทม์ไลน์ทั้งหมดที่สร้างรายการ รวมทั้งรายการไทม์ไลน์ทั้งหมดที่แชร์กับบริการดังกล่าวได้ ต่อไปนี้เป็นวิธีระบุรายการลําดับเวลาที่บริการมองเห็นได้

HTTP ไฟล์ข้อมูล

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()

คุณใช้การดําเนินการ REST อื่นๆ เพื่อรับ อัปเดต และลบรายการไทม์ไลน์ได้

การเข้าถึงไฟล์แนบ

คุณเข้าถึงไฟล์แนบไปยังรายการในไทม์ไลน์ได้ผ่านพร็อพเพอร์ตี้อาร์เรย์ชื่อ attachments จากนั้นคุณจะได้รับข้อมูลไบนารีของไฟล์แนบผ่านพร็อพเพอร์ตี้ contentUrl ของไฟล์แนบหรือด้วยปลายทางไฟล์แนบ

HTTP ไฟล์ข้อมูล

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();

กําลังสร้างรายการเมนู

รายการในเมนูช่วยให้ผู้ใช้ขอการดําเนินการที่เกี่ยวข้องกับการ์ดไทม์ไลน์ได้ และมี 2 ประเภท ได้แก่ รายการในเมนูในตัวและรายการในเมนูที่กําหนดเอง

รายการเมนูในตัวช่วยให้คุณเข้าถึงฟังก์ชันการทํางานพิเศษที่ Glass มีให้ เช่น การอ่านออกเสียงการ์ดไทม์ไลน์ การนําทางไปยังสถานที่ การแชร์รูปภาพ หรือการตอบกลับข้อความ ดังนี้

รายการในเมนูที่กําหนดเองช่วยให้แอปพลิเคชันเปิดเผยลักษณะการทํางานที่เฉพาะเจาะจงสําหรับ Glassware ได้ และคุณยังสามารถใช้ไอคอนรายการเมนูเพื่อจับคู่การสร้างแบรนด์ได้ด้วย

การเพิ่มรายการในเมนูในตัว

คุณเพิ่มรายการในเมนูในตัวลงในไทม์ไลน์ได้ โดยป้อนข้อมูลใน menuItems array เมื่อแทรกรายการดังกล่าว หากต้องการใช้รายการในเมนูในตัว คุณจะต้องป้อน action ของ menuItem แต่ละรายการเท่านั้น

HTTP ไฟล์ข้อมูล

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

การกําหนดรายการเมนูที่กําหนดเอง

หากรายการในเมนูในตัวใช้ไม่ได้กับคุณ คุณสามารถสร้างรายการเมนูที่กําหนดเองด้วยการดําเนินการของคุณเอง โดยทําตามขั้นตอนต่อไปนี้เมื่อแทรกหรืออัปเดตรายการบนไทม์ไลน์

  • ระบุ CUSTOM สําหรับ menuItem.action
  • ระบุ menuItem.id เมื่อผู้ใช้แตะรายการในเมนูที่กําหนดเอง Glassware จะได้รับการแจ้งเตือนที่มีการป้อนข้อมูล menuItem.id ซึ่งจะช่วยให้คุณระบุแหล่งที่มาของการแจ้งเตือนได้
  • ระบุ menuItem.values เพื่อเพิ่ม iconUrl และ displayName ที่ปรากฏใน Glass ชี้ไปยังรูปภาพ PNG ขนาด 50 x 50 ที่มีสีขาว และมีพื้นหลังโปร่งใสสําหรับ iconUrl

  • ระบุ displayTime หากไม่ระบุ displayTime รายการไทม์ไลน์จะย้ายไปอยู่หน้าไทม์ไลน์ทุกครั้งที่ผู้ใช้แตะรายการในเมนูที่กําหนดเอง

HTTP ไฟล์ข้อมูล

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

การอนุญาตให้ผู้ใช้ปักหมุดการ์ดไทม์ไลน์ของคุณ

คุณสามารถสร้างรายการในเมนูที่อนุญาตให้ผู้ใช้ปักหมุดการ์ดไทม์ไลน์ได้ ซึ่งจะแสดงการ์ดไทม์ไลน์ไว้ทางด้านซ้ายของการ์ดนาฬิกาหลักอย่างถาวร ผู้ใช้สามารถเลิกปักหมุดการ์ดได้เช่นกัน โดยใช้รายการในเมนูเดียวกัน

รายการในเมนูที่ปักหมุดคือรายการในเมนูในตัว ดังนั้นสิ่งที่คุณต้องทําก็แค่ระบุ TOGGLE_PINNED action สําหรับ menuItem

HTTP ไฟล์ข้อมูล

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

การสมัครใช้บริการ

Mirror API ช่วยให้คุณสมัครรับการแจ้งเตือนที่ส่งเมื่อผู้ใช้ดําเนินการบางอย่างในรายการไทม์ไลน์หรือเมื่อมีการอัปเดตตําแหน่งของผู้ใช้ได้ เมื่อติดตามการแจ้งเตือน คุณจะต้องระบุ URL เรียกกลับที่ประมวลผลการแจ้งเตือน

การรับการแจ้งเตือน

ระบบจะส่งการแจ้งเตือนจาก Mirror API เป็นคําขอ POST ไปยังปลายทางที่ติดตามซึ่งมีเนื้อหาคําขอ JSON

HTTP ไฟล์ข้อมูล

{
  "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)

บริการของคุณต้องตอบกลับ API ด้วยรหัสสถานะ HTTP 200 OK หากไม่มีข้อผิดพลาดเกิดขึ้น หากบริการของคุณตอบกลับด้วยรหัสข้อผิดพลาด Mirror API อาจพยายามส่งการแจ้งเตือนไปยังบริการของคุณอีกครั้ง

ประเภทการแจ้งเตือน

Mirror API จะส่งเพย์โหลดการแจ้งเตือนที่แตกต่างกันสําหรับเหตุการณ์ต่างๆ

ตอบ

ผู้ใช้ตอบกลับรายการไทม์ไลน์โดยใช้รายการในเมนู REPLY ในตัว:

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

แอตทริบิวต์ itemId ตั้งค่าเป็น ID ของรายการที่ประกอบด้วยรายการต่อไปนี้

  • ตั้งค่าแอตทริบิวต์ inReplyTo เป็น ID ของรายการไทม์ไลน์ที่ตอบกลับ
  • ตั้งค่าแอตทริบิวต์ text เป็นการถอดเสียงเป็นคําแล้ว
  • แอตทริบิวต์ recipients ตั้งค่าเป็น creator ของรายการไทม์ไลน์ที่แอตทริบิวต์เป็นการตอบกลับ หากมี

เช่น

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

ลบ

ผู้ใช้ลบรายการไทม์ไลน์แล้ว

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

แอตทริบิวต์ itemId ตั้งค่าเป็นรหัสของรายการที่ถูกลบ รายการไม่มีข้อมูลเมตาอื่นที่ไม่ใช่รหัสและพร็อพเพอร์ตี้ isDeleted

เลือกรายการในเมนูที่กําหนดเองแล้ว

ผู้ใช้เลือกรายการเมนูที่กําหนดเองที่กําหนดโดยบริการของคุณ

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

แอตทริบิวต์ itemId ตั้งค่าเป็นรหัสของรายการเมนูที่ผู้ใช้เลือก

อาร์เรย์ userActions มีรายการการกระทําที่กําหนดเองที่ผู้ใช้ทํากับรายการนี้ บริการของคุณควรจัดการกับ การดําเนินการเหล่านั้นให้สอดคล้องกัน

การอัปเดตตําแหน่ง

มีตําแหน่งใหม่สําหรับผู้ใช้ปัจจุบัน

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

เมื่อ Glassware ได้รับการอัปเดตตําแหน่ง ให้ส่งคําขอไปยังปลายทาง glass.locations.get เพื่อเรียกข้อมูลตําแหน่งล่าสุดที่ทราบ Glassware ของคุณจะได้รับการอัปเดตตําแหน่งทุกๆ 10 นาที

คำสั่งเสียง

ผู้ใช้เปิดใช้งานคําสั่งเสียง เช่น "Ok Glass จดโน้ต สตรีมแมว วันเกิด Chipotle คือ พรุ่งนี้" ระบบจะส่งการแจ้งเตือนต่อไปนี้ไปยัง Glassware ของคุณ

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

การแจ้งเตือนนี้แตกต่างจากการแจ้งเตือนอื่นๆ ตามค่า LAUNCH ในพร็อพเพอร์ตี้ userActions

จากนั้นคุณสามารถใช้ค่าใน itemId เพื่อดึงรายการในไทม์ไลน์ได้

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

พร็อพเพอร์ตี้ recipients มี id ของรายชื่อติดต่อที่แสดงถึงคําสั่งเสียงที่ใช้