כרטיסים סטטיים

אפשר להוסיף, לעדכן, לקרוא ולמחוק כרטיסים סטטיים באמצעות ממשקי REST API פשוטים. בנוסף, אפשר לצרף אובייקטים לכרטיס סטטי, כמו מיקום או מדיה.

איך זה עובד

כרטיסים סטטיים מופיעים כברירת מחדל משמאל לשעון ב-Glass, ומציגים מידע שרלוונטי למשתמש בזמן המסירה. עם זאת, הם לא דורשים טיפול מיידי כמו כרטיסים בזמן אמת, והמשתמשים יכולים לבחור לקרוא את הכרטיס או לפעול לפי ההנחיות שבו בזמן שנוח להם.

כש-Glassware מוסיף כרטיסים סטטיים לציר הזמן, יכול להיות שיושמע צליל התראה ב-Glass כדי לעדכן את המשתמשים. כל הכרטיסים הסטטיים הקודמים גם זזים ימינה ונעלמים מציר הזמן אחרי 7 ימים או כשנוספים 200 כרטיסים חדשים.

מתי כדאי להשתמש בנכסים לחיפוש מפיצים

כרטיסים סטטיים מצוינים לשליחת התראות תקופתיות למשתמשים כשקורים דברים חשובים. לדוגמה, שירות משלוח חדשות ששולח את הכתבות המובילות בזמן שהן מתרחשות. בנוסף, אפשר להשתמש בכרטיסים סטטיים של Mirror API כדי להתחיל כרטיסים פעילים או הפעלת תכונות מתקדמות דרך פריט התפריט OPEN_URI. כך תוכלו ליצור אינטראקציות היברידיות שמשתמשות בכרטיסים סטטיים כהתראות ובכרטיס פעיל או במצב צפייה היקפית כדי ליצור חוויה אינטראקטיבית יותר.

רשימה מלאה של הפעולות האפשריות בפריטים בציר הזמן מופיעה במאמרי העזרה.

הוספת כרטיסים סטטיים

כדי להוסיף כרטיסים סטטיים (פריטים בציר הזמן), שולחים POST של ייצוג 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 בערך כך:

צירוף סרטון

אם אתם מצרפים קובצי וידאו לפריטים בציר הזמן, מומלץ להזרים את הווידאו במקום להעלות את כל המטען הייעודי (payload) בבת אחת. ‫Google Mirror API תומך בסטרימינג באמצעות HTTP Live Streaming, בהורדה מתקדמת ובפרוטוקול סטרימינג בזמן אמת (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>

כברירת מחדל, הכרטיס הראשון של פריט ציר הזמן עם העמודים מוצג ככרטיס השער, ומוצג שוב כשהמשתמש בוחר באפשרות Read more (קריאה נוספת) בתפריט. כדי למנוע את ההופעה של הכרטיס הראשון אחרי הקשה על מידע נוסף, אפשר לציין את מחלקת ה-CSS של התג הראשון cover-only<article>:

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

המחלקות cover-only תומכות גם בפריטים בציר הזמן עם מספור עמודים אוטומטי:

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

קיבוץ

האפשרות 'איגוד' מאפשרת לקבץ פריטים קשורים אבל נפרדים, כמו הודעות בודדות בשרשור אימייל. לחבילות יש כרטיס ראשי של שער, שהמשתמש מקיש עליו כדי להציג ציר זמן משני שמכיל את הכרטיסים האחרים בחבילה. חבילות נבדלות מכרטיסים רגילים בציר הזמן בקיפול בפינה השמאלית העליונה של כרטיס השער של החבילה.

כדי לארוז פריטים בציר הזמן, צריך ליצור אותם עם אותו ערך במאפיין bundleId. הפריט האחרון שנוסף הוא כרטיס השער של החבילה.

בתמונות הבאות מוצג כרטיס של חבילה עם קיפול בפינה השמאלית העליונה ושני כרטיסים של חבילות מתחתיו.

פריטים בטרנדים המוזיקליים שלך השנה

השירות יכול לגשת לכל הפריטים בציר הזמן שהוא יצר ולכל הפריטים בציר הזמן ששותפו איתו. כך מציגים את הפריטים בציר הזמן שגלויים לשירות.

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

יצירת פריטים בתפריט

אפשרויות התפריט מאפשרות למשתמשים לבקש פעולות שקשורות לכרטיס בציר הזמן, ויש שני סוגים של אפשרויות תפריט: אפשרויות תפריט מובנות ואפשרויות תפריט בהתאמה אישית.

אפשרויות התפריט המובנות מספקות גישה לפונקציות מיוחדות ש-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 בגודל 50x50 הוא לבן והרקע שלה שקוף 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 עם קוד סטטוס 200 OK של HTTP. אם השירות שלכם מגיב עם קוד שגיאה, יכול להיות ש-Mirror API ינסה לשלוח מחדש את ההתראה לשירות שלכם.

סוגי התראות

ממשק Mirror API שולח מטען ייעודי (payload) שונה של התראות לאירועים שונים.

כתיבת תגובה

המשתמש השיב לפריט בציר הזמן באמצעות פריט התפריט המובנה 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 מקבל עדכוני מיקום כל עשר דקות.

פקודה קולית

המשתמש הפעיל פקודה קולית, לדוגמה: "Ok Glass, take a note, Cat Stream, Chipotle's birthday is tomorrow". ההתראה הבאה נשלחת ל-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 של איש הקשר שמייצג את הפקודה הקולית שבה נעשה שימוש.