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

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

כיצד מילות מפתח שליליות עובדות

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

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

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

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

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

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

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

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

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

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

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 Multipart. ספריות הלקוח של Google APIs מקלות על התהליך באמצעות העלאת מדיה.

צירוף הסרטון מתבצע

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

יצירת אפשרויות בתפריט

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

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

פריטים בתפריט בהתאמה אישית מאפשרים לאפליקציה לחשוף התנהגות ספציפית ל-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. כשמשתמשים מקישים על האפשרות בתפריט בהתאמה אישית, Glassware מקבלת התראה עם menuItem.id מאוכלס. כך ניתן לקבוע את מקור ההתראה.
• מציינים menuItem.values כדי להוסיף iconUrl ו-displayName שמופיעים ב-Glass. מציבים את התמונה בגודל 50 x 50 PNG, לבן עם רקע שקוף ב-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"
    }
  ...
 ]
}

מינויים

ה-שיקוף API מאפשר להירשם לקבלת התראות שנשלחות כשהמשתמש מבצע פעולות ספציפיות לגבי ציר הזמן, או כשמיקום המשתמש מתעדכן. כשאתם נרשמים להתראה, אתם מספקים כתובת URL לקריאה חוזרת (callback) שמעבדת את ההתראה.

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

קבלת התראות

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

הערה: החיבור יכבה לאחר 10 שניות. אם נדרש תהליך ארוך, תוכלו להשיב מיד ולבצע את התהליך בשרשור אחר.

סוגי התראות

ממשק ה-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, Note a note, Cat Stream, Chipte’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 של איש הקשר שמייצג את הפקודה הקולית שנעשה בה שימוש.