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

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

איך זה עובד

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

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

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

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

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

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

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

כדי להוסיף כרטיסים סטטיים (פריטים בציר הזמן), צריך לפרסם ייצוג ב-JSON של פריט בציר הזמן עד נקודת הקצה ב-REST.

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

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

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:

הערה: ברמה נמוכה, קבצים מצורפים מועלים באמצעות HTTP מרובה חלקים. ספריות הלקוח של Google APIs מאפשרות לעשות זאת בקלות העלאת מדיה.

צירוף סרטון

אם ברצונך לצרף קובצי וידאו לפריטים בציר הזמן, מומלץ לשדר את הסרטון במקום להעלות את כל המטען הייעודי (payload) בבת אחת. Google Mirror API תומך בסטרימינג באמצעות סטרימינג בשידור חי ב-HTTP, הורדה מתקדמת והפרוטוקול של סטרימינג בזמן אמת (RTSP). RTSP חסום לעיתים קרובות על ידי חומות אש, לכן צריך להשתמש באפשרויות האחרות ככל האפשר.

כדי לצפות בסרטונים בסטרימינג, אפשר להשתמש בPLAY_VIDEO פריט מובנה בתפריט ולציין את כתובת ה-URL של הסרטון כך שתהיה אפשרות payload צפייה הוספת אפשרויות מובנות בתפריט וגם פורמטים נתמכים של מדיה אפשר לקבל מידע נוסף.

הערה: צירוף כתובת URL של וידאו בסטרימינג עם content-type מתוך video/vnd.google-glass.stream-url הוצא משימוש. במקום זאת, אפשר להשתמש באפשרות המובנית בתפריט PLAY_VIDEO.

חלוקה לדפים

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

הערה: התג section לא נתמך כרגע כשמשתמשים ב- כיתה auto-paginate.

כדי לעבור ידנית לדפים, צריך להוסיף את התג 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 הפריטים האחרונים שנוספו הפריט הוא הכרטיס הראשי של החבילה.

הערה: כדי להגדיר פריט ספציפי בציר הזמן ככרטיס השער של החבילה, מגדירים isBundleCover נכס ל-true.

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

הקראת הפריטים בציר הזמן

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

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

הערה: תוכן הקובץ המצורף מוגן באמצעות OAuth 2.0, בדיוק כמו קריאות אחרות ל-API. נקודות קצה (endpoints). ספריות הלקוח של Google API מספקות גישה לתוכן הבינארי של באמצעות תכונת הורדת המדיה.

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

המערכת יוצרת אפשרויות בתפריט

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

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

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

הוספת אפשרויות מובנות בתפריט

אפשר להוסיף אפשרויות מובנות בתפריט לפריטי ציר הזמן על ידי אכלוס של השדות menuItems array כשמוסיפים אותם. כדי להשתמש באפשרות מובנית בתפריט, צריך רק לאכלס action מכל menuItem.

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

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

הערה: בסביבת הייצור, כתובת ה-URL לקריאה חוזרת (callback) חייבת לתמוך ב-SSL. למטרות פיתוח, אנחנו מספקים שרת proxy למנויים שיכול להעביר התראות לשרת הפיתוח ללא SSL.

קבלת התראות

התראה מ-Mirror API נשלחת כבקשת POST אל נקודת קצה (endpoint) רשומה שכוללת גוף בקשה של 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 אפשר לנסות לשלוח שוב את ההתראה לשירות.

הערה: הזמן הקצוב לחיבור יפוג אחרי 10 שניות. אם התהליך ארוך חובה, להשיב מיד ולבצע את התהליך בשרשור אחר.

סוגי התראות

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

הערה: כדי לאחזר פרטי מיקום צריך היקף הרשאות https://www.googleapis.com/auth/glass.location.

פקודה קולית

המשתמש הפעיל פקודה קולית, לדוגמה: "Ok Glass, תרשום הערה, Cat Stream, יום ההולדת של צ'יפוטל הוא מחר". ההתראה הבאה נשלחה אל זכוכית:

{
  "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 של איש הקשר שמייצג את פקודה קולית.